SSO

sso_require_existing_users: ${ANCHORE_SSO_REQUIRES_EXISTING_USERS}

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.

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.

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.

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.