User's Guide: Single Sign-On

Fortanix Data Security Manager (DSM) accounts can be integrated with third-party Single Sign-On (SSO) providers. When an account is configured for SSO, users for that account will be able to log in with their SSO credentials. Currently, the following SSO mechanisms are available: SAML and OpenID Connect / OAuth. To set up SSO for your account, log in as an administrator and go to the Authentication tab on the Account Settings page and select Single Sign-On, then add the desired SSO mechanism and provide the 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 Fortanix DSM settings. The IdP must meet the requirements set forth below. The SSO configuration page will inform you if the provided IdP metadata is compatible. For more information refer to Authentication using SAML.

SAML Identity Provider Registration

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

• Entity ID: https://<fortanix_dsm_url>/saml/metadata.xml
• POST binding URL: https://<fortanix_dsm_url>/saml

If the IdP requires signed requests, use the Service Provider metadata file, hosted at : <API endpoint>/saml/metadata.xml.

SAML Identity Provider Requirements

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

• Application type: web application
• Redirect URL: https://<fortanix_dsm_url>/oauth

The IdP must meet the requirements set forth below. To configure the IdP parameters in Fortanix DSM, the following information is required:

• 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
• Prompt: select any of the following options for authentication request. By default, the Consent option is selected.
  
  NOTE

  If you don’t want any value for Prompt field, then deselect the Consent option.
  • None: select this option to initiate the silent authentication with the authentication request.
  • Login: select this option to force a user authentication even if the user has been authenticated already with the authentication request.
  • Consent: select this option to force prompting user consent with the authentication request.
  • select_account: select this option to prompt the user to select a user account.
• Display: select any of the following options for Oauth server.
  
  • Page: select this option to display the consent UI associated with a full user agent window.
  • Popup: select this option to display the consent UI associated with a popup user agent window.
  • Touch: select this option to display the consent UI associated with a device that leverages a touch user interface.
  • Wap: select this option to display the consent UI associated with a feature-phone display type.
• Max Age: specifies the maximum amount of time that has elapsed in seconds since the OAuth provider last actively authenticated the end user.
  
  NOTE

  Ensure that the user knows about the supported OAuth parameters that he intends to use. As configuring the unsupported OAuth parameters might result in login errors. In case of such an error, only account administrator can log in to the account using the valid password only if “Only account administrators can log in with password” is selected at the time of account authentication configuration.
  The user will be unable to log in to account if “No roles can login with password” is selected while configuring the single sign on (SSO) authentication.

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

• Google
• Microsoft

OpenID Connect / OAuth Identity Provider Requirements

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

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

LDAP Authentication

Fortanix DSM can be configured to authenticate users through an LDAP-compliant directory. Fortanix DSM supports ldaps and ldap schemes. 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 the 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, Fortanix DSM can be configured to use one of the following methods.

Search the Directory

Fortanix DSM can search the directory to find the user object that matches the user’s email address. The search is performed in a subtree and uses 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 Fortanix DSM 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 an Email Address

Given an email address of the form name@domain, Fortanix DSM can be configured to look up 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 the 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, Fortanix DSM 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. iI that attribute is not set, then Active Directory 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 Fortanix DSM with the UPN login method.

LDAP Authorization

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

Defining External Roles 

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 Fortanix DSM. After importing the LDAP groups to Fortanix DSM, Group Administrators can map the external roles to that group by specifying the 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 a 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 Fortanix DSM through LDAP, the user's session will have auditor access to the Example group.

Authorization Settings

When enabling LDAP authorization, the Account Administrator can specify how long an authorization is valid for. When an authorization expires, Fortanix DSM will query the LDAP directory for the user's current group memberships and update the user's session accordingly.

It is also possible to specify a required role for all users and apps of the account authenticating through LDAP. The required roles supported are Account Administrator, Account Auditor, Account Member, Regular Apps, and Administrative Apps. If a user or app is not a member of this directory group and does not have the corresponding LDAP role, Fortanix DSM 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 an anonymous search. Note that these settings are also applicable when DN resolution is set to Search by Mail.

Self-Provisioning

When enabling LDAP authorization, the Account Administrator can also enable the self-provisioning of users for a particular LDAP integration in the account using the following steps:

1. Follow the steps in the User's Guide: Authentication to configure user authentication using LDAP.
2. In the Add LDAP Integration form, enable the toggle for Self-provisioning in the Authorization section.
3. Assign a role for the users who will be provisioned automatically when they first authenticate to Fortanix DSM.
   NOTE

   You can select from Account Auditor, Account Member, or Account Administrator. You can use the Fortanix REST API to assign a custom account role. Assigning a custom account role using the UI will be supported soon.
4. An account URL is generated. The Account Administrator must share this URL with the users who want to provision into this account.

Any user can now self-provision automatically into this account using the necessary LDAP authentication details without the need to be explicitly invited to join that account.

After self-provisioning is enabled by the Account Administrator, to enter the account:

1. Click the account URL that the Account Administrator shared with you to go to the Fortanix DSM login page and log in with your LDAP identity provider (IdP) credentials.
   NOTE

   If you do not have a Fortanix DSM user profile yet, it will be automatically created upon clicking the account URL and successfully logging in using the LDAP IdP.
2. Upon successful authentication, you will enter the account with the role that was configured by the Account Administrator.
   NOTE

   • If you are already an established member of the Fortanix DSM account that you are provisioning into, the authentication call for self-previsioning will not do anything else apart from establishing a session. Your role will be the same as before.
   • If you already have a pending invite into the account, clicking the account URL is equivalent to accepting the invite. Your account role will simply be whatever role you were invited to the account with; this may differ from the role that you would have been assigned, had you gone through a complete self-provisioning process.
   • The above two rules will not hold true if your account membership is disabled. This is because, if your account membership is disabled, you will not be allowed into the account.
   • For any future logins into Fortanix DSM, you can directly log in using your LDAP IdP. You do not need to use the account URL anymore.

Additional Requirements

In order to use the LDAP authorization mechanism, the LDAP directory must support identifying objects with unique ids with 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, Fortanix DSM 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 may change its DN. For example, the group name is usually included in the 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 the ldap scheme, the server must support the StartTLS extended operation

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.