User Authentication

1 - API Keys

Overview

API keys, or Application Programming Interface keys, are alphanumeric codes used to authenticate and control access to web-based services or APIs (Application Programming Interfaces). These keys serve as unique identifiers for developers or applications seeking permission to interact with Anchore Enterprise. API keys are commonly employed in software development to manage and secure the flow of data between different applications, allowing authorized access while preventing unauthorized usage. They play a crucial role in ensuring the integrity, security, and controlled usage of APIs, acting as a form of digital credentials for developers to connect their applications to external services.

Generating API Keys

A system user can generate an API key for self use. Some users have specific RBAC roles (ie account-user-admin) that allow management of API keys for other system users. For more details on generating and managing API keys, please refer to this section: Generating API keys

Generating API keys as an SAML (SSO) user

API keys for SAML (SSO) users are disabled by default. To enable API keys for SAML users, please update your helm chart values file with the following:

    user_authentication: 
        allow_api_keys_for_saml_users: true

API keys are an additional authentication mechanism for SAML (SSO) users that bypasses the authentication control of the IDP. When access has been revoked at the IDP, it does not automatically disable the user or revoke all API keys for the user.

Using API Keys

API keys are authenticated using basic auth. In order to use API keys you need to use a special username _api_key and the password is the value that was output when you created the API key.

e.g.

curl -u '_api_key:<API key value>' http://localhost:8228/v2/images

Caveats for API keys

API Keys generally inherit the permissions and roles of the user they were generated for, but there are certain operations you cannot perform using API keys regardless of which user they were generated for:

• You cannot Add/Edit/Remove Users and Credentials.
• You cannot Add/Edit/Revoke API Keys.

2 - User Credential Storage

Overview

All user information is stored in the Anchore DB. The credentials can be stored as plaintext or in a hashed form using the Argon2 hashing algorithm.

Hashed passwords are much more secure, but can be more computationally expensive to compare. Hashed passwords cannot be used for internal service communication since they cannot be reversed. Anchore provides a token based authentication mechanism as well (a simplified Password-Grant flow of Oauth2) to mitigate the performance issue, but it requires that all Anchore services be deployed with a shared secret in the configuration or a public/private keypair common to all services.

Passwords

The configuration of how passwords are stored is set in the user_authentication section of the config.yaml file and must be consistent across all components of an Anchore Enterprise deployment. Mismatch in this configuration between components of the system will result in the system not being able to communicate internally.

user_authentication:
  hashed_passwords: true|false

For all new deployments using the Enterprise Helm chart, hashed_passwords is defaulted to true.

All helm upgrades will carry forward the previous hashed_passwords setting.

NOTE: When the configuration is set to enable hashed_passwords, it must also be configured to use OAuth. When OAuth is not configured in the system, Anchore must be able to use HTTP Basic authentication between internal services and thus requires credentials that can be read.

Bearer Tokens/OAuth2

If Anchore is configured to support bearer tokens, the tokens are generated and returned to the user but never persisted in the database. Users must still have password credentials, however. Password persistence and protection configuration still applies as in the Password section above.

Configuring Hashed Passwords and OAuth

NOTE: Password storage configuration must be done at the time of deployment, it cannot be modified at runtime or after installation with an existing DB since it will invalidate all existing credentials, including internal system credentials and the system will not be functional. You must choose the mechanism at system deployment time.

Set in config.yaml for all components of the deployment:

Option 1: Use a shared secret for signing/verifying oauth tokens

user_authentication:
  oauth:
    enabled: true
  hashed_passwords: true
keys:
  secret: mysecretvalue

Option 2: Use a public/private key pair, delivered as pem files on the filesystem of the containers anchore runs in:

user_authentication:
  oauth:
    enabled: true
  hashed_passwords: true
keys:
  private_key_path: <path to private key pem file>
  public_key_path: <path to public key pem file>

Using environment variables with the config.yaml bundled into the Anchore provided anchore/enterprise image is also an option. NOTE: These are only valid when using the config.yaml provided in the image due to that file referencing them explicitly as replacement values.

ANCHORE_AUTH_SECRET = the string to use as a secret
ANCHORE_AUTH_PUBKEY = path to public key file
ANCHORE_AUTH_PRIVKEY = path to the private key file
ANCHORE_OAUTH_ENABLED = boolean to enable/disable oauth support
ANCHORE_OAUTH_TOKEN_EXPIRATION = the number of seconds a token should be valid (default is 3600 seconds)
ANCHORE_OAUTH_REFRESH_TOKEN_EXPIRATION = the number of second a refresh token is valid (default is 86400 seconds)
ANCHORE_AUTH_ENABLE_HASHED_PASSWORDS = boolean to enable/disable hashed password storage in the anchore db instead of clear text

3 - LDAP

Overview

The Lightweight Directory Access Protocol (LDAP) is a standardized and widely-used client-server protocol for accessing directory information, and can be enabled in Anchore Enterprise Client to authenticate users against an existing directory server.

In order to configure Anchore Enterprise Client for use with LDAP, the requisite information for connecting and authenticating with an LDAP directory server must first be provided by an administrator. For the purposes of determining what users can see and do once they are logged in, the administrator must also create one or more account association entries, called user mappings.

When an LDAP user authenticates, the Anchore Enterprise account associated with their session is determined by the first user mapping containing a search filter that matches the information in their LDAP record. LDAP authentication will fail if no matches are found, if the associated account is disabled, or if the user’s login credentials are incorrect.

The following sections in this document describe how to configure the Anchore Enterprise Client for use with an LDAP directory server, how to add user mappings, and how to log in to the application as an LDAP user.

Server Connection Properties

Administrators can provide the information used to connect Anchore Enterprise Client to an LDAP server from the LDAP sidetab in the Configuration view. Please note that this sidetab is not visible to non-administrative users.

The connection property fields shown in this view are described below:

After you have entered the required connection properties, click the Save button to store them. Once stored, you can click the Test button to verify that the application can authenticate with the LDAP server using the details you’ve provided.

Note: Clicking Save when no values are provided in any of the fields will disable LDAP in the application and prevent LDAP from being displayed as an authentication option on the login screen.

User Mappings

LDAP user mappings contain search filters that unite the results of searches made against the data attributes of LDAP records with account information stored in Anchore Enterprise.

When an LDAP user submits their credentials on the login page, the first match encountered will provide Anchore Enterprise Client with an associated Anchore Enterprise account that is used to define the scope of what the user can see and do once they are fully authenticated.

If a match is detected, the submitted password is then validated against the one stored inside the matched LDAP record. If the password is correct and the associated Anchore Enterprise account is not suspended, the user will be successfully logged in. If no match is found or the password is incorrect, authentication will fail.

Adding a User Mapping

User mappings can be created by administrators from inside an account within the Accounts sidetab in the Configuration view, or from the LDAP sidetab in the area below the server connection properties form.

To add a new user mapping containing an LDAP search filter, click the Add New LDAP User Mapping button—or if no user mappings are currently defined, click the Let’s add one! button in the empty table.

You will be presented a dialog, similar to the one shown below, where you can provide an LDAP search filter:

LDAP Search Filters

The LDAP search filter in each mapping provides the criteria for associating that mapping with an Anchore Enterprise account. For example:

uid=$USERNAME

In the above example, the user mapping requires that the uid (user ID) attribute in an LDAP record matches the data represented by the $USERNAME token.

The =$USERNAME string is a required entry, and the actual value of the token resolves to whatever value the user enters in the Username field when they log in to Anchore Enterprise Client.

In Microsoft® Active Directory® (AD) implementations that support the LDAP protocol, the sAMAccountName attribute is the broad equivalent of uid:

sAMAccountName=$USERNAME

Note: The submitted value of $USERNAME should always correspond to an attribute with a unique value within the LDAP user record, or one that is unique in combination with other criteria. In Active Directory, the uniqueness of sAMAccountName is enforced, whereas this may not be true for uid (which is an optional attribute in AD).

Additional filter criteria beyond the user identity can be provided to assert granular control over user access. The following examples describe filters with narrower scope:

(&(cn=$USERNAME)(|(ou:dn:=Administrative)(ou:dn:=Management)))

(&(ou=devops)(uniqueMember=uid=$USERNAME,dc=example,dc=org))

A detailed summary of the syntax and formula of LDAP search filters is beyond the scope of this document, however RFC 1558 provides a comprehensive description of how these entries are structured.

Mapping Order

By default, mappings are evaluated in priority order, with new entries being stored at the lowest priority. It can be challenging to infer the exact order of all mappings when they are spread across multiple accounts, so the table listing all current mappings the LDAP sidetab shows the priority of every item and includes the account with which they are associated. Example:

From here you can move row entries to a higher or lower order of precedence by clicking down on a hotspot () and then dragging the row up or down the list.

The priority order of user mappings determines the order in which search filters are evaluated when a user logs in. The first mapping to successfully locate an LDAP user record that matches the $USERNAME and any other criteria in its search filter will be used to determine the Anchore Enterprise account association for that user.

Once a user is located, subsequent mapping entries will be ignored, regardless of (possibly narrower) specificity, as only priority order matters here.

Test Mapping Behavior

You can evaluate the behavior of your user mappings by entering $USERNAME data (for example, the uid of a user) in the Check $USERNAME Against LDAP Mappings search field.

If an LDAP record is located that matches the search filter criteria of a mapping, you’ll be informed of which mapping provided the match, the associated Anchore Enterprise user, and the distinguished name of the user whose LDAP record was returned.

Login With LDAP Credentials

If a set of valid LDAP server connection properties have been stored by an administrator, the LDAP authentication option is activated in the application login view, in addition to the Default option of authenticating against the user records stored in Anchore Enterprise:

The value entered in the Username field will be used by the application to populate the $USERNAME token when evaluating each user mapping. The value entered in the Password field will be used to authenticate the matched user with the LDAP directory server.

Once these operations have completed, and providing the account associated with the mapping is not disabled, the user will be logged in.

4 - SSO

Overview

Anchore Enterprise can be configured to support user login to the UI using identities from external identity providers that support SAML 2.0. Anchore never stores any credentials for the users, only their usernames and Anchore permissions. All UI access is gated through a user’s valid login into the identity provider. Anchore uses the external provider to verify username identity and initialize a username, account, and roles on first login for a new user. Once a user’s identity is initialized in Anchore, the Anchore administrator can manage user permissions by managing the roles associated with the user’s identity in Anchore itself.

Terms

SAML Terms:

• Identity Provider (IDP) - The service that stores the identity database and provides identity and authentication services to Anchore.
• Service Provider (SP) - The service providing resources to the end user, in this case, the Anchore Enterprise deployment.
• Assertion Consumer Service (ACS) - The consumer of SAML assertions generated by the Identity Provider. For Anchore Enterprise, the UI proxies the SAML assertion to the Anchore Enterprise API service which consumes it, but the UI is the network endpoint the user’s browser interacts with.

Anchore Terms:

• Native User - A user that exists in the Anchore DB and has login credentials (passwords).
• SAML User - A user that exists in the Anchore DB only with a username and permissions, but no credentials. This prevents any username conflicts. SAML users will also be associated with a single Identity Provider. This prevents overlapping usernames from multiple Identity Providers gaining access to unexpected users or accounts.

How SAML integration works

When a user logs into the Anchore Enterprise UI, they can choose which Identity Provider to authenticate with. User credentials are never passed to Anchore Enterprise. Instead, other information about the user is passed from the Identity Provider to Anchore. Some information used by Anchore during login include the username, authenticating Identity Provider, associated account, and initial RBAC permissions.
After the initial login, RBAC permissions can be adjusted for this user directly by an Anchore administrator. This allows the Anchore administrator the ability to control access of Anchore users without having to gain access to the corporate IDP system.

Dynamic SAML User Provisioning

The first time a SAML User logs into Anchore, if the username is not found within the Anchore DB, a record will be automatically created for the user. If the user’s associated account is not found within the Anchore DB, an account record will also be automatically created at this time. This is often referred to as Just In Time Provisioning (JIT).

Explicit Creation of SAML Users

An Anchore administrator has the ability to create other users with administrator privileges. This includes Native and SAML Users. When creating a SAML Administrator User, the username and the Identity Provider’s name will be required. Upon SSO login by this new user, it will be associated with account admin and have all the permissions of an Anchore administrator.

A global configuration mode is also available if SSO is the preferred method of login, but the Anchore administrator would like explicit control over which users can gain access to Anchore Enterprise.

sso_require_existing_users: ${ANCHORE_SSO_REQUIRES_EXISTING_USERS}

When this configuration mode is set to true, any users who have permissions to create other users, will now have the ability to explicitly create SAML Users. As stated above, when creating a SAML User, the username and the Identity Provider’s name will be required. In addition, an RBAC role will also be needed for each SAML User creation. Upon SSO login by this new user, it will be associated with the account it was created in and have all the RBAC permissions provided for it. When this configuration mode is set to true, SSO logins are only permitted within Anchore for users who have existing SAML user records fround in Anchore DB.

When explicitly creating SAML Users, the account and RBAC role provided will take precedent over any default values or IDP Attributes which may be configured in the SAML Configuration described below. For more information, please see Mapping.

Note: Any users that have previously authenticated via SSO will continue to have access regardless of the configuration mode setting. If you wish to prevent future access when setting sso_require_existing_users to true, simply delete the user record in Anchore.

SSO Login Validation

During subsequent SSO logins, Anchore will find an existing user record in the Anchore DB. The following information will be validated:

• The user record must be a SAML User. If the user was previously configured as a Native User and you want to convert it to a SAML User, simply delete the user record in Anchore and have the user log in again via SSO.
• The user record must be authenticating from the same Identity Provider. If the user has been changed to authenticate via a different Identity Provider, simply delete the user record in Anchore and have the user log in again via SSO.

Configuration Overview

In order to use SAML SSO, the Anchore Enterprise deployment must:

1. Have Oauth enabled. This is required so that Anchore can issue bearer tokens for subsequent API usage by the UI to the system APIs.

2. Using hashed passwords is optional but highly recommended. See User Authentication for more information on configuring OAuth and hashed password storage.

3. Be able to reach the IDP login URL from the user’s browser.

4. Be able to reach the metadata XML endpoint in the IDP (if using url).

Configuration of SAML SSO is done via API/UI operations but requires configuration both in your Identity Provider and in Anchore.

In the IDP:

• Must support HTTP Redirect binding
• Should support signed assertions and signed documents
• Must allow unsigned client requests from Anchore
• Must allow unencrypted requests and responses

Anchore IDP Configuration Fields are as follows.

• Name - The name to use for this configuration. It will be part of the UI’s /service/auth/sso/ route as well as the /saml/sso/ and /saml/login/ routes that are used to implement SSO.
• Enabled - Whether auth via this configuration is allowed.
• ACS HTTPS Port - HTTPS port if non-standard. If omitted or -1, 443 is used.
• SP Entity ID - The identity for the Anchore system to present when requesting auth from the SAML IDP. This is typically a URL identifying the Anchore deployment.
• ACS URL - The URL to which SAML Responses should be sent from the IDP. For UI usage, this should be the hostname and port of the UI deployment and a path: /service//sso/auth/{idp config name}.
• Default Account - If set, this is the account that SSO users will be initialized to be members of upon sign-in the first time. This property or IDP Account Attribute must be set.
• Default Role - The role that will be granted to new users on first sign-in. Use this setting to apply a consistent role to all users if you do not want that data imported from the IDP. This property or IDP Role Attribute must be set.
• IDP Account Attribute - A SAML assertion attribute name from the SAML responses that Anchore will use to determine the account name to initialize the user into. If the account does not exist, it is created. For more information on the initialization process see Initializing User Identities below. This property or Default Account must be set.
• IDP Username Attribute - A SAML assertion attribute name from the SAML responses that Anchore will use to determine the username for the anchore identity. This is optional and typically will not need to be set. If omitted, the SAML Subject is used and this should meet most needs.
• IDP Metadata URL - URL to retrieve the IDP metadata xml from. This value is mutually exclusive with IDP Metadata XML, so only one of the two properties may be specified.
• IDP Metadata XML - Raw XML for the IDP metadata. This value is mutually exclusive with IDP Metadata URL, so only one of the two properties may be specified.
• IDP Role Attribute - The SAML assertion attribute from the SAML responses that Anchore will use to initialize a user’s roles. This may be a multi-value property. This property or Default Account must be set.
• Require Signed Assertions - If true, require the individual assertions in the SAML response to be signed by the IDP.
• Require Signed Response - If true, require the SAML response document to be signed.

Using SAML Attributes to Initialize Users and Account in Anchore

The properties of the user including the account it belongs to, the roles it has in that account as well as any other accounts the user has role access to are all initialized based on the combination of the Anchore IDP configuration and the SAML response presented by the IDP at the user’s first login.

See Mapping for more information on that process and how the configuration works.

Deleting SAML SSO Configuration

An Anchore administrator has the ability to create, modify, and delete the SAML Configuration. During deletion of the SAML Configuration, any user that was created with this Identity Provider, either dynamically or explicitly, will also be deleted.

4.1 - Mapping SSO Identities into Anchore

Overview of Mapping External Identities into Anchore

Anchore SSO support provides a way to keep users’ credentials centrally stored in a corporate Identity Provider and outside of the Anchore deployment. Anchore’s SSO approach uses the external identity store to authenticate a user and bootstrap its permissions using Anchore’s RBAC system. For each login, the user’s identity is verified against the external provider but once the identity is initialized inside the Anchore deployment, its access to resources is controlled by the Anchore Enterprise RBAC system. This approach allows Anchore admins to manage user access without having to require administrator access to a corporate or central IT identity system while still being able to leverage that system for defining identity and securing access credentials.

The identity mapping process has two distinct phases:

1. Initial identity bootstrap - Occurs on the first login of a user to Anchore causing dynamic construction of an Anchore user record.
2. Identity verification and assertion validation - Validates the administrators requirements against the external identity record on each login.

Defining the Username

By default, with SSO, the SAML Assertion’s “Subject” attribute is used to define the username. Using the subject is the right solution in most situations, but in extreme cases it may be necessary to provide the username in some other form via attributes in the SAML Response. This behavior can be configured by setting: idp_username_attribute in the SAML Configuration within Anchore. This should only be used when the subject either cannot be used due to it being a transient ID as configured by the IDP itself, or you want the username to map to some form other than the IDP’s username, email, or persistent ID.

If the idp_username_attribute is set to an attribute name, and that attribute is not found or has no value in the SAML Response presented during login, then that user login will be rejected by Anchore.

If idp_username_attribute is an empty string or null, then the SAML Response’s subject attribute is used as the username. This is the default behavior.

Defining the Account the User Belongs To

In Anchore, all users belong to an Account. When an SSO user logs into Anchore UI for the first time, the identity is initialized with the username (as defined above), but the account to which the user belongs is configurable via a separate pair of configuration properties in the SAML Configuration within Anchore. These configuration properties are mutually exclusive.

idp_account_attribute - If set in the SAML Configuration, this attribute must be found within the SAML Response during each login for every user. The attribute value received is the ‘account name’. It must also be valid. A valid value must be greater than three characters and must not be a reserved account name such as ‘admin’ or ‘anchore-system’ If the attribute is not found within the SAML Response or the value is not valid, the login is rejected.

default_account - If set in the SAML Configuration, it’s value is the account all users that login from this IDP will be assigned.

• In both cases, on the initial login by the user, if the account does not already exist within Anchore, an external account with that name is created.

Defining the User’s Initial Roles

In Anchore, all users are allowed to have one or more Roles that describe a set of access permissions.
Roles are assigned to the user via a separate pair of configuration properties in the SAML Configuration within Anchore.
These configuration properties are mutually exclusive.

idp_role_attribute - If set in the SAML Configuration, the attribute must be found within the SAML Response during each login for every user. The attribute value received is one or more ‘role name’. The value must also be valid. If the attribute is not found within the SAML Response or the value is not valid, the login is rejected.

default_role - If set in the SAML Configuration, it’s value will be the single role set for all users that login with this IDP. During a user’s first login, this role will be set on the account during user identity initialization. On subsequent logins for this user, the value will be ignored.

Revoking SSO User Access

1. Disable the Anchore account. Any user, SSO or otherwise, that is a member of a disabled account cannot log in or perform API operations.
2. If using idp_account_attribute or idp_role_attribute, simply remove or zero that attribute at the IDP for that user or group. All affected users will no longer be able to log in to Anchore.

Changing the Anchore SAML Configuration

Initialization of identities and roles occurs on the user’s first login. Once initialized, the configuration must match the SAML Response presented during each login for the user to log in.

Thus, changes to the SAML Configuration within Anchore may affect subsequent logins for your users. For instance, if you change the SAML Configuration within Anchore to start using attributes instead of defaults, a user’s SAML Response will need to contain the same attributes. Failure to find the correct attribute(s) with valid values will prevent the user’s login.

Example SSO configurations

Anchore and an external Identity Provider

Here are examples for both Okta and KeyCloak that provide simple defaults and identity mappings.

• KeyCloak
• Okta
• Azure

Identity Mapping configuration

Below are example configuration values for a single SAML Configuration within Anchore to achieve different behavior:

1. All SSO users in one account with the same read-write permissions:

   • default_account = ‘account’
   • default_role = ‘read-write’

2. SSO users in accounts managed by the IDP property, for example a ‘groups’ property:

   • default_account = null
   • default_role = null
   • idp_account_attribute = "primary_group"
   • idp_role_attribute = "roles"
   • Will initialize the user with the roles specified in the ‘roles’ attribute for the accounts in the ‘primary_group’ attribute.
     • E.g. if ‘primary_group’ = [’testers’], and ‘roles’ = [‘read-only’] for a user, [email protected]
     • [email protected] will be initialized at login as username = [email protected] in account testers with role read-only
     • Because the account is from an attribute, [email protected] might have ‘primary_group’ = [‘security_engineers’] and thus be initialized in a different account in Anchore.

4.1.1 - KeyCloak SAML Example

Configuring SAML SSO for Anchore with KeyCloak

The JBoss KeyCloak system is a widely used and open-source identity management system that supports integration with applications via SAML and OpenID Connect. It also can operate as an identity broker between other providers such as LDAP or other SAML providers and applications that support SAML or OpenID Connect.

The following is an example of how to configure a new client entry in KeyCloak and configure Anchore to use it to permit UI login by KeyCloak users that are granted access via KeyCloak configuration.

Configuring KeyCloak

Anchore supports multiple IDP configurations, each given a name. For this example we’ll choose the name “keycloak” for our configuration. This is important as that name is used in several URL paths to ensure that the correct configuration is used for validating responses, so make sure you pick a name that is meaningful to your users (they will see it in the login screen) and also that is url friendly.

Some config choices and assumptions specifically for this example:

1. Let’s assume that you are running Anchore Enterprise locally. Anchore Enterprise UI is available at: https://localhost:3000. Replace with the appropriate url as needed.
2. We’re going to choose keycloak as the name of this saml/sso configuration within Anchore. This will identify the specific configuration and is used in urls.
3. Based on that, the Single-SignOn URL for this deployment will be: https://localhost:3000/service/sso/auth/keycloak
4. Our SP Entity ID will use the same url: http://localhost:3000/service/sso/auth/keycloak

Add a Client entry in KeyCloak

1. See SAML Clients in KeyCloak documentation

2. For this example, set the following values in “Add Client” screen (these are specific to the settings in this example described above):

   1. Client ID - http://localhost:3000/service/sso/auth/keycloak - This will be the SP Entity ID used in the Anchore configuration later
   2. Client Protocol: “saml”
   3. Client SAML Endpoint: “http://localhost:3000/service/sso/auth/keycloak”

3. In the next screen, Client Settings

   

   1. Name - “Anchore Enterprise”. This is only used to display a friendly name to Keycloak users in the KeyCloak UI. Can use any name you like.

   2. Enabled - Select on

   3. Include Authn Statement - Select on

   4. Sign Documents - Select on

   5. Client Sign Authn Requests - Select Off

   6. Sign Assertions - Select off

   7. Encrypt Assertions - Select off

   8. Client Signature Required - Select off

   9. Force Post Binding - Select off. Anchore requires the HTTP Redirect Binding to work, so this setting must be off to enable that.

   10. Force Name ID Format - Select on

   11. Name ID Format - Select username or email (transient uses a generated UUID per login and persistent use the Keycloak user’s UUID)

   12. Root URL - Leave empty

   13. Valid Redirect URIs - Add http://localhost:3000/service/sso/auth/keycloak

   14. Base URL - Leave empty

   15. Master SAML Processing URL - http://localhost:3000/service/sso/auth/keycloak

   16. Fine Grain SAML Endpoint Configuration

       1. Assertion Consumer Service Redirect Binding URL - http://localhost:3000/service/sso/auth/keycloak

   17. Save the configuration

   

4. Download the metadata xml to import into Anchore

   1. Select ‘Installation’ tab.
   2. Select Format
   • Keycloak <= 5.0.0
   1. Select Format Option - SAML Metadata IDPSSODescriptor
   • Keycloak 6.0.0+
   1. Select Format Option - Mod Auth Mellon files
   2. Unzip the downloaded .zip and locate idp-metadata.xml
   3. Download or copy the XML to save in the Anchore configuration

Configure Anchore Enterprise to use the KeyCloak

1. You’ll need the following information from keycloak in order to configure the SAML record within Anchore:

2. The name to use fo the configuration, in this example keycloak

3. Metadata XML downloaded or copied from the previous section

4. In the Anchore UI, create an SSO IDP Configuration:

5. Login as admin

6. Select “Configuration” Tab on the top

7. Select “SSO” on the left-side menu

8. Click “Let’s Add One” in the configuration listing

1. Enter the values:
   1. Name: “keycloak” - This is the name of the configuration and will be referenced in login and sso URLs, so we use the value chosen at the beginning of this example
   2. Enabled: True - This controls whether or not users will be able to login with this configuration. We’ll enable it for the example but can disable later if no longer needed.
   3. ACS HTTPS Port: -1 or 443 - This is the port to use for HTTPS to the ACS (Assertion Consumer Service, in this case the UI). It is only needed if you need to use a non-standard https port
   4. SP Entity ID: http://localhost:3000/service/sso/auth/keycloak (NOTE: this must match the Client ID you used for the Client in the KeyCloak setup
   5. ACS URL: http://localhost:3000/service/sso/auth/keycloak
   6. Default Account: keycloakusers for this example, but can be any account name (existing or not) that you’d like the users to be members of. See Mappings for more information on how this
   7. Default Role: read-write for this example so that the users have full access to the account to analyze images, setup policies, etc.
   8. IDP Metadata XML: Paste the downloaded or copied XML from KeyCloak in step 4.3 above
   9. Require Signed Assertions - Select off
   10. Require Signed Response - Select on
   11. Save the configuration

You should now see a ‘keycloak’ option in the login screen for the Anchore Enterprise UI. This will redirect users to login to the KeyCloak instance for their username/password and will create a new user in Anchore in the keycloakusers account with read-write role.

4.1.2 - Microsoft Entra ID SAML Example

Configuring SAML SSO for Anchore with Microsoft Entra ID (formerly Azure Active Directory)

Azure Enterprise Applications allow identities from an Azure Directory to be federated via Single Sign On (SSO) to other applications. In doing so Azure is acting as a SAML Identity Provider (IdP) that can be used with Anchore Enterprise as a SAML Service Provider (SP).

Configuring Azure

Anchore supports multiple IDP configurations, each given a name. For this example we’ll choose the name “azure” for our configuration. This is important as that name is used in several URL paths to ensure that the correct configuration is used for validating responses, so make sure you pick a name that is meaningful to your users (they will see it in the login screen) and also that is url friendly.

Some config choices and assumptions specifically for this example:

1. Let’s assume that you are running Anchore Enterprise locally. Anchore Enterprise UI is available at: https://anchore.example.com. Replace with the appropriate url as needed.
2. We’re going to choose azure as the name of this saml/sso configuration within Anchore. This will identify the specific configuration and is used in urls.
3. Based on that, the Single-SignOn URL for this deployment will be: https://anchore.example.com/service/sso/auth/azure
4. Our SP Entity ID will use the same url: https://anchore.example.com/service/sso/auth/azure

Azure Setup

1. Create a generic Enterprise Application in Azure.

   

   1. Navigate to the Azure portal: https://portal.azure.com

   2. Type “Enterprise Applications” into the search bar in the top middle of the screen and click on it.

   3. Click on Create your own application near the upper left.

2. Select SAML as the single sign-on method.

   

3. From your new Azure AD Enterprise Application select Single sign-on.

   

4. Select Edit Basic SAML Configuration (section 1).

   

5. For both Identifier (Entity ID) & Reply URL (Assertion Consumer Service URL) enter the URL for your Anchore deployment along with: “/service/sso/auth/azure”. The word “azure” can be customized. This will become the name of the SSO configuration that users will see each time they login via SSO. Example URL: https://anchore.example.com/service/sso/auth/azure (Make note of the URL for upcoming steps) - Click Save when finished

   

6. Copy the “App Federation Metadata Url” found in section 3. This will be used in the next section.

   

7. Configure Users and Groups that will be allowed to login to Anchore.

   

   1. Select Users and groups under Manage.

   2. Click Add user/group.

   3. Click on the hyper-linked “None Selected”.

   4. Select/Check users and/or groups who will be granted access to login to Anchore.

   5. Press Select when finished.

Configure Anchore Enterprise to use the Azure Identity Provider

1. Ensure you have a non-admin Account created in Anchore. In this example I am creating an account named “saml” and setting it as the default account to create users who use this SSO configuration but do not already exist in Anchore.

   

2. Login to Anchore and navigate to System, SSO and click on Add new SAML IDP.

   

3. Enter the values (Note that all values can be changed except Name):

   1. Under “Name” enter “azure” or whatever you choose to name the SSO integration.
   2. Enter the URL (https://anchore.example.com/service/sso/auth/azure in this example) under “SP Entity ID” and “ACS URL”. This URL was known as Entity ID and Reply URL in Azure.
   3. Select the account created or selected in step 1 for “Default Account”.
   4. Select the appropriate role for “Default Role”.
   5. Paste the Federation Metadata URL from the previous section into “IDP Metadata URL”.
   6. Uncheck “Require Signed Response?”.

   

4. Save the configuration, configuration is complete when you see a login with ‘azure’ option on the login screen. Users can now log in to your Anchore deployment using this Azure endpoint.

See: Mapping Users and Roles in SSO for more information on using the account and role defaults, IDP attribute values and understanding how identities are mapped into Anchore’s RBAC system.

Using Azure Groups with Anchore User Groups

User groups in Anchore can grant users access to multiple Anchore accounts with varying/selectable access levels in each.

In this example we have two teams within the organization named TeamA and TeamB. We will create a group in Azure for each team that will be sent to Anchore upon SAML login where each team will have their own Anchore account. We can optionally grant each team read-only access to the other teams account.

To map groups from Azure to Anchore:

1. Create an account in Anchore for TeamA and TeamB.

   

2. In Azure create or add desired groups to the “Users and Groups” section of your Anchore SSO Enterprise Application.

   

3. In Anchore create (a) user group(s) matching group names from Azure. Please note that the name of a user group cannot be changed but its contents can be changed at any time. For the sake of this example add both the TeamA and TeamB accounts. Grant the TeamA user group full control to the TeamA account and read-only to the TeamB account. When adding the user group for TeamB grant full-admin access to the TeamB account and read-only access to the TeamA account.

   

4. In your Azure Enterprise Application under Single Sign On select edit on Attributes and Claims, section 2.

   

5. Click on Add a group claim.

   

6. For “Which groups associated with the user should be returned in the claim” Select “Groups assigned to the application”

   1. For Source attribute select “Cloud-only group display names”
   2. Expand Advanced Options
   3. Check “Customize the name of the group claim”
   4. Check “Emit groups as role claims”

7. Edit your Anchore SAML Identity Provider and enter “http://schemas.microsoft.com/ws/2008/06/identity/claims/role" in the “IDP User Groups Attribute”. Under User Groups select TeamA and TeamB.

   

At this point when logging in via azure SSO a user will either land in the Default Account and need to switch account from the drop down in the upper right or if an IDP Account Attribute was configured to initially put them in the desired account they would only need to switch accounts appropriately.

4.1.3 - Okta SAML Example

Configuring SAML SSO for Anchore with Okta

Some config choices and assumptions specifically for this example:

1. Anchore UI endpoint: http://localhost:3000. Replace with the appropriate url as needed.
2. IDP Config Name: okta. This will identify the specific configuration and is used in urls, and can be any url-safe string you’d like.
3. The Single Sign-on URL (also called the Assertion Consumer Service/ACS URL) for this deployment will be: http://localhost:3000/service/sso/auth/okta. This is constructed with the UI endpoint and path /service/sso/auth/{IDP Config Name}
4. Our SP Entity ID will use the same url: http://localhost:3000/service/sso/auth/okta. This could be different but for simplicity we use the same value.

Configure Okta: Add an Application

See Okta SAML config to see how to create a new application authorization server. The following steps are used during specific steps of that walk-thru

1. In step #6
   1. Single sign on URL, this is the URL Okta will direct users to. This must be a URL in the Anchore Enterprise UI based on the name you chose for the configuration. In our example: http://localhost:3000/service/sso/auth/okta
   2. Set the Use this for Recipient URL and Destination URL checkbox as well. a1. Set the Audience URI(SP Entity ID) to a URI that will identify the anchore installation. This can be the same as the single-sign-on URL for simplicity. We’ll need to enter this value later in the Anchore config as well.
   3. Leave Default RelayState empty
   4. Name ID format can be left “Unspecified” or set to an email or username format.
   5. Choose the application username that makes sense for your install. Anchore can support a regular username or email address for the usernames.
2. In step #7, these attribute statements are not required but can be set. This is, however, where you can set additional attributes that you want Anchore to use to initialize the user’s Anchore account or permission set. Later in the SAML Configuration you can specify attributes that Anchore will look for to extract the account name and roles for initializing a user that doesn’t yet exist in Anchore.
3. In step #9, be sure to copy the metadata URL link so you have that. Anchore will need that value.
   1. Right-click here and copy the link address: The URL should be something like: https://<youraccount>.okta.com/app/<appid>/sso/saml/metadata
4. Finish the setup and save the Application entry.
5. Important: To allow Okta users to login to Anchore you need to assign the Okta user to this new Application entry. See Assign and unassign apps to users for information on this process.

Configure Anchore Enterprise to use the Okta Identity Provider

You’ll need the following information from okta to enter in the Anchore UI:

• The name chosen for the configuration: okta in this case
• Metadata XML URL (from “configuring okta” step 3.1 above)
• The Single Sign-on/ACS URL described in Step 3

In the Anchore UI, create an SSO Idp Configuration:

1. Login as admin
2. Select “Configuration” Tab on the top
3. Select “SSO” on the left-side menu
4. Click “Let’s Add One” in the configuration listing

And…

1. Enter the values:

   • Name: okta - This is the name of the configuration and will be referenced in login and sso URLs, so we use the value chosen at the beginning of this example
   • Enabled: True - This controls whether or not users will be able to login with this configuration. We’ll enable it for the example but can disable later if no longer needed.
   • ACS HTTPS Port: -1 or 443 - This is the port to use for HTTPS to the ACS (Assertion Consumer Service, in this case the UI). It is only needed if you need to use a non-standard https port
   • ACS URL: http://localhost:3000/service/sso/auth/okta
   • Default Account - The account to add all okta users to when they login, for this example we use oktausers
   • Default Role - The role to grant okta users when they login in initially. For this example, we use read-write, the standard user type that has most abilities except user management.
   • IDP Metadata URL - The url from “Configure Okta” step 3.1
   • Require Signed Assertions - Select On
   • Require Signed Response - Select On

2. Save the configuration, configuration is complete when you see a login with ‘okta’ option on the login screen. Users can now log in to your Anchore deployment using this Okta endpoint.

See: Mapping Users and Roles in SSO for more information on using the account and role defaults, IDP attribute values and understanding how identities are mapped into Anchore’s RBAC system.