User's Guide: Authentication

1.0 Introduction

Welcome to the Fortanix-Data-Security-Manager (DSM) Authentication User Guide. This article describes the authentication and authorization mechanisms of the Fortanix DSM.

It also contains the information related to:

• Planned enhancements for these mechanisms.

• Steps the users can take to safeguard their own authentication credentials.

1.1 Fortanix DSM Authentication and Authorization

Fortanix DSM provides access to its functions and APIs to two types of entities – humans (users) and machines (applications). There are many ways to authenticate to Fortanix DSM for both users and applications, which vary in terms of ease of use, integration with existing enterprise Identity and Access Management Systems (IAM), and level of security. After authenticated, there is an elaborate access control mechanism which controls which entity has authorization to perform which function under what conditions.

NOTE

Fortanix DSM now uses cookies as the transport mechanism for session tokens during authentication. Instead of storing session tokens in local storage, DSM utilizes secure, HTTP-only cookies, enhancing security and ensuring better protection against unauthorized access.

Users who were logged in before the Fortanix DSM 4.37 release will be logged out and may receive an unauthorized access message. They must log in again to initiate a new session.

2.0 User Authentication Using Password

The following authentication type is supported for users using password:

2.1 Username and Password Stored in Fortanix DSM

This is done using the "Log in without SSO” option.

1. In the Fortanix DSM login screen, select the option “LOG IN WITHOUT SSO".

2. Enter your password, and then click LOG IN.

2.2 Changing Password

Perform the following steps to update the password:

1. Log in to Fortanix DSM as an account administrator.

2. To change the password, go to the My profile page.

3. Click the Change Password tab under password section.

4. Enter your current password in the Current Password field.

5. Enter your new password in New Password and New Password (Again).

6. Click the Change Password button to confirm the changes.

The user password is updated successfully.

3.0 Configure User Authentication Using SSO

Fortanix DSM 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 log in with their SSO credentials.

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

Select from the following options to prevent user lockout if SSO was incorrectly set up:

• Only account administrators can log in with password: Select this option during SSO configuration, if you want to allow only account administrators to log in with their local password when SSO is incorrectly set up. Other user roles will be restricted from logging in with passwords. You can also select Mandatory two-factor authentication to log in with password to add an additional authentication layer for account administrators to authenticate using the supported 2FA devices as described in Section 3.3: Configuring 2FA at the User Level.

• All roles can log in with password: Select this option during SSO configuration, if you want to allow any user role to log in to Fortanix DSM with their local password when the SSO mechanism is incorrectly set up.

• No roles can log in with password: Select this option during the SSO configuration, if you want no user role including the Administrator to log in to the Fortanix DSM using their local password when SSO is incorrectly set up.

NOTE

Selecting All role can log in with password and No roles can log in with password will disable Mandatory two-factor authentication to log in with password.

3.2 Supported SSO Mechanism

Currently, the following SSO mechanisms are available for users.

3.2.1 SAMLv2

Configuring a SAML provider:

To enable SAML for your account, first obtain the Identity Provider (IdP) metadata XML file. 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 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

SAML Identity Provider Requirements:

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

• Does not require signed requests

• Use the POST binding for response

• Sign responses, assertions, or both

Perform the following steps to configure the user authentication using SAML:

1. On the Authentication page, select ADD SAML INTEGRATION to configure SAML.

2. In the Add SAML Integration form, click UPLOAD A FILE to upload the configuration file (IdP metadata XML file), and then click ADD INTEGRATION to complete SAML configuration for user authentication.

3.2.2 OAuth / Open ID Connect

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

• Client ID

• Client Secret

OAuth/Open ID Connect Identity Provider Registration:

You would need to register Fortanix DSM with your IdP to obtain these credentials and provide the following values to your IdP:

• Application type: web application

• Redirect URL: https://<fortanix_dsm_url>/oauth

Configure OAuth/Open ID Connect Identity Provider:

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

• Provider Name

• Logo URL (optional)

• Authorization Endpoint URL

• Token Endpoint URL

• Authentication Method (client_secret_basic or client_secret_post)

• User Info Endpoint URL (optional)

• Host Validation check box

• 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 do not 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 SSO authentication.

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

• Google

• Microsoft

OpenID Connect / OAuth Identity Provider Requirements

To use an OAuth / OpenID Connect 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

Perform the following steps to configure user authentication using OAuth:

1. On the Authentication page, click the ADD OAUTH INTEGRATION button to configure OAuth.

2. In the Add OAuth Integration form, add all the required details about the OAuth provider, and then click ADD INTEGRATION to complete the OAuth configuration for user authentication.

3.2.3 LDAP

Fortanix DSM can be configured to authenticate users through an LDAP-compliant directory. Fortanix DSM supports the 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:

1. Resolve user’s email address to a Distinguished Name (DN)

2. 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 (for example, 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 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, Fortanix DSM 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 [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.

• 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. If 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.. It is recommended to configure the userPrincipalName attribute for all users in the directory when configuring Fortanix DSM with the UPN login method.

Perform the following steps to configure user authentication using LDAP:

1. On the Authentication page, click ADD LDAP INTEGRATION to configure LDAP.

2. In the Add LDAP Integration form, add all the required details about the LDAP provider, and then click ADD INTEGRATION to complete the LDAP configuration for user authentication.

For more information on LDAP authentication, refer to User Guide: Single Sign-On.

3.3 Configuring 2FA at the User Level

Two-Factor Authentication (2FA) or multi-factor authentication in Fortanix DSM can be configured at the user level. When 2FA is enabled for a specific user, that user will be required to set up 2FA before logging into their account.

3.3.1 Prerequisites

Ensure the following:

• A Fortanix DSM user

• 2FA is currently supported using the FIDO2/WebAuthn standard, which is supported by devices such as YubiKey. This also works for FIDO U2F authenticators since FIDO2/WebAuthn is backward compatible with them.

Once user authentication using a password or user authentication using SSO is activated, an additional authentication layer can be added by enabling 2FA using a device that supports U2F or FIDO2/WebAuthn.

Steps to Enable Two-Factor Authentication (2FA):

Fortanix DSM supports passkeys for 2FA, leveraging FIDO2/WebAuthn-compatible devices (for example: YubiKey). Follow these steps to enable 2FA:

1. Click the My profile tab from the DSM top-right of the page to go to your profile settings.

2. In the option for Two-step Authentication, click the ENABLE button to enable two-factor authentication.

3. Enter the profile password in the dialog box and click the NEXT button.

After the 2FA is enabled, an additional authentication layer configured for either user authentication using password or user authentication using SSO, which the user has already configured. 2FA can also be configured in the Fortanix DSM Quorum Policy for quorum approvals. For more information refer to the article User's Guide: Quorum Policy.

3.3.2 Accepting Terms & Conditions

On the My Profile page, you must select the checkbox to accept the latest terms and conditions of Fortanix.

3.4 Configuring 2FA at the Account Level

2FA can also be configured at Fortanix DSM account level. When 2FA is enabled at an account level, all users of the account will be required to set up 2FA before logging into the account.

3.4.1 Configuring 2FA for Authentication using Password

Perform the following steps to configure mandatory 2FA for user login with a password:

1. Log in to the Fortanix DSM as a system administrator and click the Settings menu item in the DSM left navigation bar.

2. Select the PASSWORD AUTHENTICATION option.

3. Select the check box Mandatory two-factor authentication for all team members.

4. Click the SAVE CHANGES button to keep the changes.

After this setting is saved, all users of the account (including yourself) must configure 2FA using the My profile page as described in Section 2.0: User Authentication Using Password. This will add an additional layer of authentication for the account users. Without this configuration, they will not be able to log in to Fortanix DSM.

3.4.2 Configuring 2FA for Authentication Using SSO

Perform the following steps to configure 2FA for authorization using SSO:

1. Log in to the Fortanix DSM as a system administrator and click the Settings menu item in the DSM left navigation bar.

2. Select the SINGLE SIGN-ON option.

3. Configure the required SSO integrations using SAML, OAUTH or LDAP as described in Section 3.0: Configure User Authentication Using SSO.

4. Select the check box account administrators can log in with password. This option prevents account administrators from being locked out of the account if the IdP is not configured correctly.

5. To add an additional authentication layer for account administrators, select the check box Mandatory two-factor authentication to log in with password.

6. Click the SAVE CHANGES button to save the changes.

NOTE

• When you select the Mandatory two-factor authentication to log in with password check box, the corresponding check box in the PASSWORD AUTHENTICATION tab will be automatically selected.  

• If you disable the Mandatory two-factor authentication to log in with password check box in the Password Authentication settings and save the changes, it will delete the SSO configuration upon your confirmation. This ensures that there are no conflicting password-based authentication mechanisms.

After this setting is saved, all users of the account (including yourself) must configure 2FA using the My profile page as described in Section 3.3: Configuring 2FA at the User Level. This will add an additional layer of authentication for the account users. Without this configuration, they will not be able to log in to Fortanix DSM.

3.5 Configuring 2FA at the System Level

2FA can also be configured at a Fortanix DSM system level. When 2FA is enabled at a system level, all the system administrators will be required to set up 2FA before logging into the System.

Perform the following steps to configure 2FA for authorization using SSO:

1. Log in to Fortanix DSM as a system administrator.

2. To configure 2FA go to the My profile page and follow the steps described in Section 3.3: Configuring 2FA at the User Level to enable 2FA.

This will add an additional layer of authentication for the system administrators. Without this configuration, they will not be able to log in to Fortanix DSM.

3.6 User Authentication Using SSO - Usage

After the configuration steps for user authentication using SSO are complete, the user can test the various authentication mechanisms using LOG IN WITH SSO option in the Fortanix DSM login screen. The user will now be presented with all the SSO authentication mechanisms that were configured for logging in to Fortanix DSM.

Multiple Accounts: Different accounts might have different SSO providers. A user can be in multiple accounts with different SSO providers. In these scenarios, the 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.

4.0 Application Authentication

Currently, the following are the types of authentication methods supported for applications:

4.1 Using a System-Generated API Key

When you create an application in Fortanix DSM, an API key is used to authenticate the application. This API key is a random, secret token, that identifies an application in the same way as a password identifies a user. The user can copy this API key using the COPY API KEY button for the application.

Certain app integrations require a username and password, so use the USERNAME/PASSWORD tab for this requirement. This tab contains the Username and Password values. The Username (app UUID) is a unique identifier that the system generates for each application. The Password is the app secret that is also randomly generated by the system. For example, the Username and Password fields are used for the Fortanix DSM with VMware VSAN integration. Once this integration is set up, Fortanix DSM could be used for both vSphere VM encryption and VSAN encryption.

You can regenerate an app API Key such that the old API key can continue to work for a configurable expiration period.

Perform the following steps to configure the expiration period for an API Key:

1. Go to the detailed view of an app.

2. In the INFO tab, click REGENERATE in the API Key section.

3. In the Regenerate API Key dialog, set the expiration period using the Expiration Setting section.

4. Select both the check boxes to confirm your understanding about the action.

5. Click the UPDATE button.

4.2 Using a Client TLS Certificate

Applications can also authenticate to Fortanix DSM using a client TLS certificate. To do this, select the Certificate option as the authentication method, and then upload a certificate using the UPLOAD CERTIFICATE button when you create a new application. The user can also paste the certificate using the text box. Only certificates in PEM format are supported.

4.3 Using Client TLS Certificate Issued by Trusted CA

If your application's client TLS certificate is signed by a certificate authority, you can use this method to authenticate your application to Fortanix DSM.

To use this method, you should specify the CA's certificate and the Subject Alternative Name (SAN) you expect in your application's certificate. The following SANs are supported:

• DNS Name: This is the default selection.

• IP Address

• Directory Name: This is a list of identifiers (key=value pairs). The user can add/remove any number of object identifiers for a Directory Name. The following object identifiers can be selected for directory names:

  • Common Name, Surname, Serial Number, Country Name, Locality, State/Province, Organization Name, Organizational Unit Name, Custom OID.

  NOTE

  If you add multiple identifiers for Directory Name with the same key=value pairs, the value will be overwritten with the most recent value that is added for the key.

When the app authenticates itself to Fortanix DSM using a client TLS certificate, it will verify that the app's certificate is signed by the specified trusted CA and that the SAN matches the expected value. To do this, select the Trusted CA option as the authentication method, Configure the SAN, and then upload a certificate using the UPLOAD TRUSTED CA CERT. The user can also paste the certificate using the text box provided. Only certificates in PEM format are supported.

4.3.1 Using Certificate Revocation List (CRL) in the Certificates

A Certificate Revocation List is a digital record maintained by a Certificate Authority (CA) containing the serial numbers of digital certificates that have been revoked before their expiration date. The primary purpose of a CRL is to provide a mechanism for entities in a cryptographic system to check the validity of digital certificates. By consulting the CRL, these entities can verify whether a particular certificate has been revoked due to data compromise or loss, thereby ensuring the security and integrity of digital communications.

Perform the following steps to use the CRL in the certificates:

1. Configure DSM: In the Fortanix DSM user interface, add a new app and select the Trusted CA as the authentication method.

2. Upload Root Certificate:

   • Upload the root CA certificate.

   • Add client certificate Subject Alternative Name (SAN) details. Ensure that these details correspond to both revoked and non-revoked certificates.

3. Select the Verify client certificate revocation status check box to activate CRL or OCSP verification during authentication. This option ensures that DSM verifies the revocation status of client certificates against the configured CRL. By default, this check box is not selected.

   

4. Authentication: Run the following command to authenticate the certificates using the Fortanix DSM app:

   curl https://apps.sdkms.test.fortanix.com/sys/v1/session/auth -X POST -u <APP_UUID> --cert <PATH/TO/CERTIFICATE> --key <PATH/TO/PRIVATE/KEY>

   Where,

   • <APP_UUID> refers to the UUID of the app.

   • <PATH/TO/CERTIFICATE> refers to the path of the client certificate.

   • <PATH/TO/PRIVATE/KEY> refers to the path of the client key.

4.3.2 Using Online Certificate Status Protocol (OCSP) in the Certificates

The Online Certificate Status Protocol is an Internet protocol used for obtaining the revocation status of an X.509 digital certificate. This contains signatures that assert a certificate has not been revoked. This makes it a more effective and efficient validation process, as it does not require a list to be downloaded to discover the status of a certificate.

To use the OCSP in the certificates, perform the Steps 1 to 4 explained in the Using Certificate Revocation List (CRL) in the Certificates section.

If revocation information is present in the client certificates, Fortanix DSM will use the following order of preference:

• If either a CRL distribution point or OCSP responder URL is present, Fortanix DSM will use it to check the revocation status.

• If both the CRL distribution point and OCSP responder URL are present, Fortanix DSM will obtain the OCSP response first. If the OCSP response is unknown, it will check the CRL.

• If neither is present, no revocation check will be done.

4.4 Google Service Account

Google Service Account method is used by a service account in Google Cloud to use the external KMS interface from the GCP KMS interface. To learn more about this scheme, refer to Using Fortanix Data Security Manager with Google Cloud EKM Interface.

4.5 External Directory

In this method, Fortanix DSM extends the Application’s authentication model to allow the application to authenticate using its credentials in Active Directory (AD). When this option is selected, the user is presented with a list of enrolled external directories and the user can choose a directory.

These types of applications authenticate to Fortanix DSM by providing the app_id and credentials of the app in AD. Fortanix DSM will look up the app by app_id, find the corresponding external directory, and present the credential to it for authentication. If the external directory successfully authenticates, then Fortanix DSM will continue to find authorization for the app.

4.6 JSON Web Token (JWT)

Applications can also authenticate to Fortanix DSM using signed JSON Web Tokens. A signed JWT is a cryptographically verifiable token that carries information about a subject and is encoded as three base64 encoded sections separated by dots. For example, the following:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjFhYWEwNWJjN2Q0NDQ1NWFmNzRmYTdmMDBhZDRmMjgyMTQ2YTQ2NzMifQ . eyJzdWIiOiJteSBhcHAiLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tIiwiYXVkIjoiaHR0cHM6Ly9zZGttcy5mb3J0YW5peC5jb20iLCJpYXQiOjE1NDYzMzkwMjIsImV4cCI6MTU0NjM0OTAyMn0 . KUtIf6zJGWozRplp32Vt-vt-Sy1TyXmL5svWJHvdKJ1q20zrGNoUhcvGYOSF7X3mIvxKXC_qGNQJZjsXA5KAJRhp-6SIn8MsexLbnfioxDny7ZuPHPo22pCS55xPukxZQSWW6JLRk7ITHvrYqY4boDao7bxZdoPshuw2ekZ6UHS5GdaWPcN-od_xS0nYqhdiI4gw-A23IrneFwwVCfziQ-u_tNuqXL0SjT3UbYPbtfkcQEfBdJpKPyU3ZdJ_gAKNj071vvAMKwM53wXclu-w7NKyNfgA1zz-S2gQfy643e61Lg8i-mlabwK7hXEFCx5ksnTpff037BRDUnzNphvOjQ

is a signed JWT and it carries the following information in its first 2 base64 encoded parts:

Header:

{
 "alg": "RS256",
 "typ": "JWT",
 "kid": "1aaa05bc7d44455af74fa7f00ad4f282146a4673"
}

Body:

{
 "sub": "my app",
 "iss": "https://example.com",
 "aud": "https://<fortanix_dsm_url>",
 "iat": 1546339022,
 "exp": 1546349022 
 }

If you are using Microsoft Entra ID to generate the JWT, then refer to Section 4.6.1: Generate a JWT from Microsoft Entra. For Microsoft Entra to accept the aud field as DSM SaaS domain URL to authenticate to Fortanix DSM.

The third part of the token is a cryptographic signature that can be independently verified by
anyone with knowledge of the public key that was used to sign the token.

All of the API endpoints accessible to apps also accept JWT authentication tokens if the app is configured with JWT authentication mechanism. An app holding a valid JWT token works similarly to an app with a valid API key. The JWT token needs to go in the HTTP Authorization header, encoded as the password with the username being the account ID of the account where the app is created: Authorization: Basic $TOKEN where $TOKEN is a base64 encoded $ACCT_ID:$JWT.

The following snippet shows how to do this encoding in a shell script (BASH):

$ echo -n "$ACCT_ID:$JWT" | base64 -w0

• Looking up the app in the specified account using the JWT subject field as app name,

• Looking up the public key for signature verification,

• Verifying the token's signature using that public key,

• Verifying temporal constraints including nbf (not before) and exp (expiration time)
  if present in the token,

• Verifying other constraints listed above (iss and aud).

To configure an app to use this authentication method, you would need to specify the following:

Valid Issuers:

One or more valid issuers. This information is used to validate the iss field of the JWT.

Signing Keys:

Either STORED SIGNING KEYS or FETCHED SIGNING KEYS. This is used to validate the signature on the JWT:

• Stored: provide one or more public keys by uploading or pasting the key in PEM format. When specifying multiple keys, specify the Key ID so that keys can be differentiated by unique Key IDs. In this case, the signed JWT should also indicate which signing key was used to sign that token by specifying kid in its header section.

  Note that if the signed JWT includes the kid field in its header you should always specify
  Key ID for the public key(s) configured on the app regardless of the number of signing keys
  specified.

• Fetched: provide a URL that can be used to fetch the signing key(s). To improve performance,
  Fortanix DSM will cache the fetched keys, but you can control how long the keys are cached. The specified URL should return the signing keys in one of the following formats:

  • JWK Set: refer to Section 5 of RFC 7517 for details.

  • A JSON object mapping key IDs to base64 encoded public keys in DER format. Here is an example:

    {
     "f00cd596-5108-4349-9dc2-0ce14c56b1f6": "MIIBoDANBgkqhkiG9w0BAQEFAAOCAY0AMIIBiAKCAYEAo6f6tb41PfkLk69EREUjQLwDArTEdYqKd9+QjlLm89Sv7sFzgtL/aNmzSPgJ9t1m0XOIMm51QkNEMA0tA9yEf3AjP6U/4F+f7A2jTLWY09wsXG3qulAw5FC78xCoK6pBBIwev2LRzo0Blz1exAv9mOXP/fGATQOdnwDRRr6lAbnynR86qxfF/ge0r+OVUEni4eOMAvr6lYrQeXKl1hQpb86JWq3eSdk/LYFB+8366bogjN+oLLb7LIBbmEEctZ7ygIxnKiCIhZS3C0tTHrBi4aNTLps7UPlJna7UqmmN5bdhgih9SjjnP7CJnZG8ZsB3JMXlpBE0dP5nnGW20ZqxbxBXYgSxOd1SnGIp/hI7aQctyB9M9di2C57gtlDB++tsAZg9FWZo1y8IMY4e1AEYHxhq5PEVhBL3jW0xXrZrcuoB0c7i7aX0B4vRnvNdflZ9omwP2zDd2jYcuqPaDkygjzuoDTsjcC/NvjHWmK1EEOvgsDDOMMXwQ9cErsEtLUbHAgED"
    }

  TIP

  When using fetched signing keys, the signed JWT should always contain a kid field in its header.

  It is recommended to use the fetched signing keys when you need to periodically rotate the signing keys.

Refer to RFC 7519 and RFC 7515 for more information about JSON Web Tokens.

4.6.1 Generate a JWT from Microsoft Entra

This section describes the steps to use Microsoft Azure Entra for app authentication to Fortanix DSM SaaS using JWT. This method ensures proper authentication with DSM SaaS by allowing the manual addition of the scope that contains the Fortanix DSM SaaS domain URL.

Perform the following steps to generate a JWT using Microsoft Entra:

1. Log in to https://portal.azure.com/.

2. Go to your already registered application or register a new application.

   

3. Navigate to Certificate & secrets → Client secrets tab. Click New client secret to create a client secret of your Azure application.

   

4. Identify which region of Fortanix DSM SaaS you will be using. For example, amer.smartkey.io, eu.smartkey.io, apac.smartkey.io, and so on.

5. Use the following URL to request the JWT:

   https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token

   Where, replace {your-tenant-id} with your Azure tenant ID.

6. The POST request requires the following fields and their respective values:

   1. grant_type: Enter the value as client_credentials.

   2. client_id: Enter your Application (Client) ID of the app registered on the Azure portal.

   3. client_secret: Enter your Client secret Value of the app registered on the Azure portal.

   4. scope: Enter https://{DSM_region}/.default, replacing {DSM_region} with the appropriate region value identified in Step 4 above. For example, amer.smartkey.io.

7. You need to send a POST request using a tool such as cURL, Postman, or any other HTTP client.

   Example cURL command:

   curl -X POST https://login.microsoftonline.com/{your-tenant-id}/oauth2/v2.0/token \ 
   -H "Content-Type: application/x-www-form-urlencoded" \ 
   -d "grant_type=client_credentials" \ 
   -d "client_id={your-client-id}" \ 
   -d "client_secret={your-client-secret}" \ 
   -d "scope=https://{DSM_region}/.default" 

   Where,  

   • {your-tenant-id} replace it with your Azure tenant ID.

   • {your-client-id} replace it with your Application (Client) ID of the app registered on the Azure portal.

   • {your-client-secret} replace it with your Client secret Value of the app registered on the Azure portal.

   • {DSM_region} replace it with with the appropriate region value identified in Step 4 above. For example, amer.smartkey.io.

8. After sending the request, you will receive a response containing the access_token, which is the JWT encoded value. Use this token to authenticate with Fortanix DSM SaaS.

   

4.7 Workspace CSE

Select this option to add a Google Workspace CSE user as an app. Ensure that the app name of the CSE user is same as email address of an existing Google Workspace user.. For more details, refer to Using Fortanix DSM for Google Workspace Client-Side Encryption.

4.8 AWS IAM

In this method, Fortanix DSM extends the Application’s authentication model to allow the application to authenticate using AWS Identity and Access Management (IAM) that provides fine-grained access control across all of AWS.

Fortanix DSM Authenticates with AWS IAM using the Signature Version 4 signing process.

Signature Version 4 (SigV4) is the process of adding authentication information to AWS API requests sent by HTTP. For security purpose, you must sign most requests to AWS with an access key. The access key consists of an access key ID and a secret access key, which are commonly referred to as your security credentials

How to Follow the Signature Version 4 Process:

1. Create a canonical request.

2. Use the canonical request and additional metadata to create a string for signing.

3. Derive a signing key from your AWS secret access key. Then use the signing key and the string from the Step 2 to create a signature.

4. Add the resulting signature to the HTTP request in a header or as a query string parameter.

When an AWS service receives a request, it performs the steps that calculate the signature sent in the request. AWS then compares its calculated signature to the one you sent with the request. If the signatures match, the request is processed. If the signatures do not match, the request is denied.

You can change between app authentication methods such that the previous authentication method will continue to work for a configurable expiration period.

The following are the steps to configure the expiration period for the previous authentication method:

1. Go to the detailed view of an app.

2. In the API Key section, click the drop-down list for Change authentication method and select the new authentication method.

3. Click the SAVE button.

4. In the detailed view of the new authentication method page, set the expiration period in the Expiration Setting section and click UPDATE.

4.9 AWS XKS

Select this option to protect the data in AWS with keys stored in Fortanix DSM that users can use to perform cryptographic operations. For more details, refer to Cloud Key Management / BYOK documentation.

5.0 Enable OAuth for an Application

A user can configure OAuth for an app to authorize the app to perform cryptographic and key management operations on their behalf in groups that the user has an administrator role.

Perform the following steps to enable OAuth:

1. In the create application form, click the Enable OAuth toggle button.

2. In the Authorized Redirect URIs field, enter the redirect URL.

   NOTE

   OAuth can also be enabled from the detailed view of an app.

Now, when the external application performs OAuth and requests permission to access the Fortanix DSM group to perform crypto and key management operations, the user will be redirected to the Fortanix DSM login page for authorization:

1. The user must log in to Fortanix DSM to authenticate and select the account that contains the app for which OAuth was enabled.

2. The user will see the consent page.

3. The user must select a default group from the list of groups in which the user has an administrator role that will store the security objects created by the app.

4. Click AUTHORIZE to authorize the app.
   For more details refer to the OAuth authorization framework.

6.0 Create Applications and Groups Using App Authentication Methods

6.1 Create Administrative Apps

Sometimes, creating the groups and applications programmatically using application authentication methods may be neccessary instead of creating the same by logging into the Fortanix DSM UI. For example, this will help in onboarding users of a particular sub-department of an organization in a more automated manner using their tools instead of human intervention with Fortanix DSM. This can be achieved using the Fortanix DSM Administrative App feature on the Account Settings page.

Perform the following steps to create an Administrative App:

1. Go to the Administrative Apps page and click ADD ADMINISTRATIVE APP button.

2. The Administrative App will display all the authentication methods that are currently supported by Fortanix DSM applications:

   • API Keys

   • Certificate

   • Trusted CA

   • JSON Web Token

   • AWS IAM

   • Workspace CSE App Auth

   NOTE

   There can be more than one administrative apps created with each administrative app mapped with different authentication methods.

3. You can assign a predefined Account Custom Role to restrict the operations that can be performed by a new or existing Administrative App. If the Administrative App performs any operation outside the selected Account Custom Role, it will result in an error. For more information, refer to User's Guide: Custom Role.

4. Click CREATE once the authentication method is configured for the administrative app.

5. Once the administrative app is created, a user can use one of the authentication methods configured for an administrative app, for example: COPY API KEY to authenticate to Fortanix DSM programmatically.

   NOTE

   • Administrative apps can create and delete quorum approval requests.

   • Administrative apps can manage keys without the app manageable permission.

6.2 Disable/Enable Administrative App

Perform the following steps to disable an administrative app:

1. Go to the Administrative App table view and click the toggle button to disable/enable an administrative app.

6.3 Delete Administrative App

Perform the following steps to delete an administrative app:

1. Go to the detailed view of the administrative app and click the DELETE ADMINISTRATIVE APP button at the bottom of the page.

6.4 View Audit Logs of Administrative App

Perform the following steps to view the audit logs of an administrative app:

1. Go to the detailed view of an administrative app, and click the AUDIT LOG tab.

6.5 IP Whitelisting of Applications in Administrative Apps

Refer to Section 7.0: IP Whitelisting of Applications for more details.

7.0 IP Whitelisting of Applications

Whitelisting of IP address for an application allows an application to authenticate itself only if it comes from the whitelisted IP address. The IP whitelisting feature allows a range of IP addresses to authenticate and access a group.

Perform the following steps to specify the range of IP address for the application:

1. Go to the detailed view of an application and click the EDIT button to the right of Allowed IP-addresses field.

2. Select Restrict authentication to trusted IPV4, IPV6 CIDRs option.

3. Enter the CIDR. Classless inter-domain routing (CIDR) is a set of Internet protocol (IP) standards that are used to create unique identifiers for networks and individual devices.

4. You can add multiple CIDRs using the ADD ANOTHER CIDR option.

5. Click SAVE to save the settings.

8.0 Configuring LDAP Authentication When Using SSH

Perform the following steps to configure LDAP authentication on the Fortanix DSM node while using SSH:

1. Install the LDAP dependency packages using the command:

   sudo apt-get install ldap-auth-client nscd ldap-utils

2. During the installation, you will be prompted to provide the following details of your LDAP server:

   • LDAP Uniform Resource Identifier (URI): This can be LDAP Server’s IP address or hostname.

   • Domain Name (DN) of the LDAP search base.

   • LDAP version to use.

3. Install the configuration package ldap-configusing the command:

   sudo apt install ldap-config

4. After the installation is complete, the details of the configuration provided in the previous steps can be verified in the file /etc/ldap.conf.

5. Verify the Pluggable Authentication Module (PAM) configuration at /etc/pam.d/common-sessionfile.
   The file should show the following line :

   session required        pam_mkhomedir.so skel=/etc/skel/ umask=0022

6. The configuration of LDAP authentication is complete. The connectivity can be verified using SSH with one of the users of the LDAP directory.  

9.0 References

• Using Fortanix DSM with Google Cloud EKM Interface: Using Fortanix Data Security Manager with Google Cloud EKM Interface

• RFC 7519: https://tools.ietf.org/html/rfc7519

• RFC 7515: https://tools.ietf.org/html/rfc7515

• RFC 7517: https://tools.ietf.org/html/rfc7517