User's Guide: Single Sign-On

1.0 Introduction

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.

2.0 Setting Up SSO

Perform the following steps to set up SSO for your account:

1. Log in as an Account Administrator and click the Settings menu item from the DSM left navigation panel and click the AUTHENTICATION tab on the Account Settings page.

2. Select the SINGLE SIGN-ON radio button, and then add the desired SSO mechanism as described in the following sections and provide the required configuration values.

3.0 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.

3.1 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.

3.2 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

4.0 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

4.1 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

5.0 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

5.1 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.

5.1.1 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.

5.1.2 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 [email protected] 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.

5.1.3 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.

6.0 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.

6.1 Configuring External Roles 

NOTE

To create external role, you must have added one or more LDAP integrations in the account authentication settings.

Perform the following steps to import external roles as group objects in an LDAP directory:

1. Log in to your Fortanix DSM account as an Account Administrator.

2. Navigate to the Groups menu item, and select the EXTERNAL ROLES tab.

3. On the External Roles page, click the CREATE NEW EXTERNAL ROLE button.

4. On the Import External Roles from LDAP Directory page, add the following:

   • Source: Select the origin of the LDAP integration from the drop down menu.

     NOTE

     If authorization is disabled for this LDAP Directory, enable it in LDAP configuration in the Account Authentication Settings to be able to map external roles to DSM groups.

   • Base DN: This is the starting point in the LDAP directory tree from which searches will begin.

   • Scope: Select from the following options:

     • Whole subtree: Searches through all levels of the directory starting from the Base DN.

     • Single level: Limits the search to only one level directly below the Base DN.

   • Object Class: Select the type of objects being searched from.

   • Filters: Select this to refine the search and find specific entries within the directory.

5. Click the SEARCH DIRECTORY button to search the LDAP directory.

   From the search results, select the LDAP group(s) that you want to import as external roles. You can select multiple groups at once.

6. After selecting the desired group(s), click the Import button to bring these groups into Fortanix DSM as external roles.

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.

After the LDAP groups are imported, you need to map these groups to a user or an application.

• For more information on how to map the external roles to a user, refer to Section 2.6: LDAP Authorization for Users.

• For more information on how to map the external roles to an application, refer to Section 2.5: LDAP Authorization for Applications.

6.2 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.

6.3 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.

Perform the following steps to enable user self-provisioning for an LDAP integration:

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. After the 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.

6.4 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.

6.5 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

7.0 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.