Single Sign-On

Updated: Oct 11, 2018

SmartKey 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, OpenID Connect / OAuth and LDAP. 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 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 SmartKey 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 SmartKey as a Service Provider with your IdP, provide the following information:

  • Entity ID: https://<region>.smartkey.io/saml/metadata.xml
  • POST binding URL: https://<region>.smartkey.io/saml

SAML Identity Provider Requirements

In order to use a SAML IdP with SmartKey, 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 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 SmartKey with your IdP to obtain these credentials. Provide the following values to your IdP:

  • Application type: web application
  • Redirect URL: https://<region>.smartkey.io/oauth

The IdP must meet the requirements set forth below. You need to configure the IdP parameters in SmartKey. 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 SmartKey, the IdP must:

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

Configuring LDAP Provider

SmartKey can be configured to authenticate users through an LDAP-compliant directory. SmartKey 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, SmartKey can be configured to use one of the following methods.

Search the directory

SmartKey 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 SmartKey should be created in the directory. When configured this way, the mail attribute must be set for user objects in the directory.

Construct the DN from email address

Given an email address of form name@domain, SmartKey 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.

UPN login

With Active Directory, SmartKey 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 SmartKey with UPN login method.

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.