User's Guide: Single Sign-On – Fortanix

SDKMS accounts can be integrated with third-party Single Sign-On (SSO) providers. When an account is configured for SSO, users in that account will be able to login with their SSO credentials. Currently, the following SSO mechanisms are available: SAML and OpenID Connect / OAuth. To setup SSO for your account, login as administrator and go to Authentication tab on Account Settings page and select Single Sign-On, then add the desired SSO mechanism and provide required configuration values.

Configuring a SAML provider

To enable SAML for your account, first obtain the Identity Provider (IdP) metadata XML file. Then upload or paste the SAML IdP metadata in SDKMS settings. The IdP must meet the requirements set forth below. The SSO configuration page will inform you if the provided IdP metadata is compatible.

SAML Identity Provider registration

When configuring SDKMS as a Service Provider with your IdP, provide the following information:

Entity ID: https://sdkms.fortanix.com/saml/metadata.xml
POST binding URL: https://sdkms.fortanix.com/saml

SAML Identity Provider requirements

In order to use a SAML IdP with SDKMS, the IdP must:

Adhere to SAML 2.0, Web Browser SSO profile
Use one or more signing keys specified as an X.509 certificate
Use the urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress name format
Accept the POST binding for requests
Not require signed requests
Use the POST binding for response
Sign responses, assertions, or both

Configuring an OpenID Connect / OAuth provider

To enable SSO using OpenID Connect / OAuth for your account, first obtain the following information from your Identity Provider (IdP):

Client ID
Client Secret

You would need to register SDKMS with your IdP to obtain these credentials. Provide the following values to your IdP:

Application type: web application
Redirect URL: https://sdkms.fortanix.com/oauth

The IdP must meet the requirements set forth below. You need to configure the IdP parameters in SDKMS. The following information are needed:

Provider name
Logo URL (optional)
Authorization endpoint URL
Token endpoint URL
Token endpoint authentication method (client_secret_basic or client_secret_form)
UserInfo endpoint URL (optional)
TLS configuration: use Global Root CAs or provide a custom CA certificate

Most of these parameters are published in a well-known location by identity providers. For example:

OpenID Connect / OAuth Identity Provider Requirements

In order to use an OpenID Connect / OAuth IdP with SDKMS, the IdP must:

Support Authorization Code Flow described in OpenID Connect Core specification
Support email scope
Provide user’s email address to SDKMS in Token or UserInfo response
Provide non-encrypted ID token during Token response

LDAP Authentication

SDKMS can be configured to authenticate users through an LDAP-compliant directory. SDKMS supports ldaps scheme as well as ldap and in both cases the communication with the directory server is encrypted with TLS. When using the ldap scheme, the StartTLS operation is initiated immediately after connecting to the server.

LDAP authentication is performed in two steps:

Resolve user’s email address to a Distinguished Name (DN)
Authenticate to the directory using the DN and user-supplied password

DN Resolution Methods

To resolve the user’s email address to a DN, SDKMS can be configured to use one of the following methods.

Search the directory

SDKMS can search the directory to find the user object matching the user’s email address. The search is performed in a subtree and using the following filter: (&(objectClass={0})(mail={1})) where {0} is the configured object class (e.g. User or inetOrgPerson) and {1} is the user’s email address. Some directories do not allow anonymous search, in which case a service account for SDKMS should be created in the directory. When configured this way, the mailattribute must be set for user objects in the directory.

Construct the DN from email address

Given an email address of form name@domain, SDKMS can be configured to lookup a format string based on the domain part and insert the name part in the format string to construct the DN. For example, if example.com is configured with format string uid={},ou=users,dc=example,dc=com, then the email address test@example.com will be mapped to the following DN: uid=test,ou=users,dc=example,dc=com. The format string must include the placeholder {} which is replaced by the name part.

With Active Directory, SDKMS can use the email address in place of the DN. When specifying an email address in place of the DN, Active Directory would check the value against the userPrincipalName attribute and if that attribute is not set, then it would accept values that match SamAccountName @ domain, where SamAccountName is the legacy user identifier attribute and domain is the fully qualified domain name of the Active Directory domain controller. We recommend setting the userPrincipalName attribute for all users in the directory when configuring SDKMS with UPN login method.

LDAP Authorization

In addition to authentication, SDKMS can leverage group membership in an LDAP-compliant directory to assign users to groups dynamically. This requires mapping LDAP groups to SDKMS groups which is achieved by defining external roles in SDKMS and mapping these external roles to SDKMS groups. After a user authenticates to SDKMS using LDAP, SDKMS retrieves the list of directory groups that the user belongs to and if those groups are mapped to SDKMS groups, the user is added to the mapped SDKMS groups for the current session.

Account administrators can create external roles for the account. To do that, they must have added one or more LDAP integrations in account authentication settings. Using the LDAP search functionality, account administrators can look for group objects in an LDAP directory and import those as external roles into SDKMS. After importing the LDAP groups to SDKMS, group administrators can map the external roles to their group by specifying a desired access level.

For example, if an Active Directory group identified by the distinguished name CN=My Group,CN=Users,DC=example,DC=com is added as an external role, an administrator of group Example can map that external role to Example with access level Group Auditor When a user that belongs to this Active Directory group authenticates to SDKMS through LDAP, his session will have auditor access to the Example group. Note that the user must be an account member since account administrators and auditors have default access to all groups. Also note that the user need not be added to the Example group directly, but the user will have access to the Example group based on his/her Active Directory group membership and if the user is kicked out of that Active Directory group, he/she will lose access to the SDKMS group as well.

When enabling LDAP authorization, the account administrator can specify how long each authorization is valid. When an authorization expires, SDKMS will ask the LDAP directory for the user's current group memberships and updates the user's session accordingly.

It's also possible to specify a required role for all users authenticating through LDAP. If a user is not a member of this directory group, SDKMS will prevent that user from selecting the account.

When authorization is enabled for an LDAP integration, the following settings are required:

- Base DN
- User Object Class

The Service Account setting is also needed if the directory does not allow anonymous search. Note that these settings are also applicable when DN resolution is set to Search by Mail.

In order to use the LDAP authorization mechanism the LDAP directory must support identifying objects with unique ids using one of the following attributes:

- entryUUID defined in RFC 4530, supported by Open LDAP and others
- objectGUID used by Active Directory

When comparing an external role against a user's LDAP groups, SDKMS uses the group's unique id instead of its distinguished name. Unique ids are more flexible compared to DNs since changing object attributes does not affect its unique id but it may change its DN, for example, the group name is usually a part of its DN.

LDAP Identity Provider Requirements

The identity provider must:

Conform to LDAPv3 protocol specified in RFC 4511 and other related RFCs
Either support ldaps scheme or if using ldap scheme, it must support the StartTLS extended operation

Warning: administrator lock-out

If the SSO mechanism is mis-configured, you will not be able to login to your account. When updating the SSO configuration, make sure to check the box for “Account administrators can log in with password” option. This way, account administrators can still login with password and access the account.

Multiple accounts

Different accounts might have different SSO providers. As such, a user can be in multiple accounts with different SSO providers. Such a user will need to select which SSO provider to use during the login process. When switching accounts, a user might need to re-authenticate to satisfy the new account’s authentication requirements.