SSO Support
Overview
Anchore Enterprise 2.1+ can be configured to support user login to the UI using identities from external identity providers that support SAML 2.0. In such a configuration, Anchore never stores any credentials for the users, only their usernames and Anchore permissions, and 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 may 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 RBAC Manager service which consumes it, but the UI is the network endpoint the user’s browser interacts with.
Anchore Terms:
Native user - Users that exist in the Anchore DB and have login credentials (passwords). External user - A user that exists only with a username and permissions, but no credentials. External Anchore users will also have an associated ‘source’ field that stores the SAML entity ID of the identity provider that the user was initialized from. This ensures that any username conflicts will not result shared usernames or accounts since Anchore does support multiple identity provider integrations.
How SAML integration works
When using SAML SSO, users log into the Anchore Enterprise UI via the identity provider without ever passing credentials to Anchore. Information about the user is passed from the identity provider to Anchore and Anchore initializes the user’s identity within Anchore using that data. After first sign-in, the username exists without credentials in Anchore and additional RBAC configuration can be done on the identity directly by Anchore administrators. This allows users with access to administer Anchore to control access of their own users without also having to have access to a corporate IDP system, which is rare.
If a username that already exists in Anchore and has a login credential within Anchore (a password) and tries to login via SAML/SSO, that login will be rejected to ensure an existing user is not accidentally overwritten or another unique user granted access to a different user’s account via name conflict. If you want to convert a user from a native Anchore user to an external user, simply delete the user record in Anchore and have the user login via SSO. Anchore will re-initialize the username.
Configuration Overview
In order to use SAML SSO, the Anchore Enterprise deployment must:
-
Have Oauth enabled. This is required so that Anchore can issue bearer tokens for subsequent API usage by the UI to the system APIs.
-
Using hashed passwords is optional but highly recommended. See User Credential Storage for more information on configuring OAuth and hashed password storage.
-
Be able to reach the IDP login URL from the user’s browser
-
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:
- Name - The name to use for this configuration. It will be part of the UI’s /service/auth/sso/ route as well as the RBAC Manager’s /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. Either this or IDP Account Attribute must be set.
- Default Role - The role that will be granted to new users on first sign-in. This setting is mutually exclusive with IDP Role Attribute. Use this setting to apply a consistent role to all users if you do not want that data imported from the IDP
- 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
- 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 and Default Role are mutually exclusive, only one may be used.
- 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
On initial login by a new user via SSO, Anchore initializes a new identity in the Anchore DB that is used for RBAC authorization. This record only persists the username and IDP’s issuer entity ID as the user source. These users never have login credentials in the Anchore DB, and cannot have passwords set so no non-SSO login in possible for these users.
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.
For more information, see Mapping for more information on that process and how the configuration works.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.