User's Guide: Authentication

1.0  Authentication

Fortanix Data Security Manager (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 IAM (Identity and Access Management Systems), and level of security. Once authenticated, there is an elaborate access control mechanism that controls which entity has the authorization to perform which function under what conditions.

1.1  User Authentication Using Password

The authentication method for users using a password is described below:

1.1.1  Username and Password Stored in Fortanix Data Security Manager

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

  1. In the Fortanix DSM login screen, select the option “LOG IN WITHOUT SSO". 1.png Figure 1: Login Without SSO
  2. Enter your password, and then click LOG IN.

2.png
                               Figure 2: Enter Password

1.2  User Authentication Using SSO - Configuration

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 login with their SSO credentials.

To set up SSO for your account:

  1. Log in as an Administrator, and click the Settings Settings.png icon in the Fortanix DSM UI, and then click the AUTHENTICATION tab in the Account Settings page.
  2. Select SINGLE SIGN-ON, and then add the desired SSO mechanism and provide the required configuration values.
WARNING
Administrator lock-out: If the SSO mechanism is misconfigured, Account Administrators created locally on Fortanix DSM will not be able to log in to the account. When updating the SSO configuration, make sure to select the Account administrators can log in with password option. This way, Account Administrators can continue to log in with the password and access the account.

Currently, the following SSO mechanisms are available for users is:

1.2.1  SSO Using a Third-party Identity Provider

The following protocols are supported:  

  • SAMLv2
  • OAuth / Open ID Connect
  • LDAP

SAMLv2

To Configure user authentication using SAML, follow the below steps:

  1. In the Authentication page, select ADD SAML INTEGRATION to configure SAML. 5.png Figure 3: Add SAML Integration
  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. 6.png Figure 4: Add SAML Integration

For more information on SAML provider configuration, refer to User Guide: Single Sign-On

OAuth / OpenID Connect

To configure user authentication using OAuth, follow the steps below:

  1. In the Authentication page, click ADD OAUTH INTEGRATION to configure OAuth. 7.png Figure 5: Add OAuth Integration
  2. In the Add OAuth Integration form, add all the required details about the OAuth provider, and then click ADD INTEGRATION to complete OAuth configuration for user authentication. 8.png Figure 6: Add OAuth Integration
  3. For more information on OAuth / OpenID Connect provider configuration, refer to User Guide: Single Sign-On.

LDAP

To configure user authentication using LDAP, follow the steps below:

  1. In the Authentication page, click ADD LDAP INTEGRATION to configure LDAP. 9.png Figure 7: Add LDAP Integration
  2. In the Add LDAP Integration form, add all the required details about the LDAP provider, and then click ADD INTEGRATION to complete LDAP configuration for user authentication. 10.png Figure 8: Add LDAP Integration

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

1.3  Authentication Using 2FA (Two Factor Authentication) at User Level

1.3.1  Prerequisites

  • A Fortanix DSM user
  • All users should have a U2F (Universal 2nd Factor) device such as a YubiKey or a Google Titan Key to enable 2FA.

Once user authentication using a password or user authentication using SSO is activated, an additional authentication layer can be added using second factor authentication (2FA) in Fortanix DSM using a U2F (Universal 2nd Factor) device, such as a YubiKey or a Google Titan Key. To configure this, follow the steps below:

  1. Click My profile to go to your profile settings. 3.png Figure 9: Profile Settings
  2. In the option for Two-step Authentication, click ENABLE to enable two-factor authentication. 4.png Figure 10: Enable 2-Step Authentication

Once 2FA is enabled we will now have 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 https://support.fortanix.com/hc/en-us/articles/360016047771-User-s-Guide-Quorum-Policy.

1.4  Configuring 2FA at Account Level

In Section 1.3 we described how to configure 2FA at a user level using the User’s profile. 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.

1.4.1  Configuring 2FA for Authentication using Password at Account Level

  1. Log in to Fortanix DSM as an Account Administrator and go to the Settings Setting1.png page for the account.
  2. Select the PASSWORD AUTHENTICATION
  3. Select the check box Mandatory two-factor authentication for all team members.
  4. Click SAVE CHANGES to save the changes.
      2FA.png
    Figure 11: 2FA for account level password authentication setting
  5. Once this setting is saved, all users of the account (including yourself) have to configure 2FA using the “My profile” page as described in Section 1.3. 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.

1.4.2  Configuring 2FA for Authentication Using SSO at Account Level

  1. Log in to Fortanix DSM as an Account Administrator and go to the Settings Setting1.png  page for the account.
  2. Select the SINGLE SIGN-ON
  3. Configure the required SSO integrations using SAML, OAUTH, or LDAP as described in Section 3.2.
  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 2FA is not enabled.
  5. Now select the check box Mandatory two-factor authentication to log in with password.
  6. Click SAVE CHANGES to save the changes.
      2FA1.png
    Figure 12: 2FA for account level SSO authentication setting
  7. Once this setting is saved, all users of the account (including yourself) have to configure 2FA using the “My profile” page as described in Section 1.3. 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.

1.5  Configuring 2FA at the System Level

In Section 1.3 and Section 1.4 we described how to configure 2FA at a user level and account 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.

  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 to enable 2FA.
      2FA2.png
    Figure 13: 2FA configuration at sys admin level
  3. 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.

1.6  User Authentication Using SSO - Usage

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

11.png
          Figure 14: User Authentication

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.

1.7  Application Authentication

Currently, there are five forms of authentication methods supported for applications:

AppAuthExtDir_1.png Figure 15 - Application Authorization

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

13.png Figure 16: Copy API Key

Certain app integrations require a username and password, so we 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.

Picture24.png
         Figure 17: Application Username and Password

You can regenerate an app API Key such that the old API key can continue to work for a configurable expiration period.
The following are the 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 as shown in Figure 18 and click REGENERATE. RegenerteAPIKey.png
                          Figure 18: Expiration Settings of Regenerating API Key

1.7.2  Using a Client TLS certificate

Applications can also authenticate to Fortanix DSM using a TLS client 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. We support certificates in PEM format only.

AppAuthExtDir_2.png Figure 19: Upload Certificate

1.7.3  Using a Client TLS Certificate Issued by a 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 SANs supported are:

  • 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. We support certificates in PEM format only.

AppAuth_SAN.png Figure 20: Upload Trusted CA Certificate

1.7.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, please refer to the article Using Fortanix Data Security Manager with Google Cloud EKM Interface.

1.7.5  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://sdkms.fortanix.com",
"iat": 1546339022,
"exp": 1546349022
}

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.

Any of the API Endpoints (REST APIs) can accept the JWT authentication token. An app trying to hold a valid JWT token works just like an app with a valid API key. Both these apps will use any of the Fortanix DSM REST APIs with a Authorization: Basic $TOKEN where $TOKEN is a base64 encoded $ACCT_ID:$JWT or $APP_ID:$API_KEY .

To authenticate to Fortanix DSM, the app should present the signed JWT along with its account UUID as an HTTP Basic Auth header encoded in the following form:

base64Encode(accountId:signedJwt)

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

$ echo -n "$ACCT_ID:$JWT" | base64 -w0
NOTE:
  1. The JWT body must include the following fields:
    • sub the subject of the token must match the app's name in Fortanix DSM.
    • iss the issuer of the token is validated against a list of issuers.
    • aud the audience of the token must include the Fortanix DSM endpoint URL, e.g.
      https://sdkms.fortanix.com (this might be different for you if using an on-prem Fortanix DSM cluster).
  2. In some scenarios, we also require the presence of kid field in the JWT header.
    This is discussed below in the section Signing Keys.

Fortanix DSM verifies the authentication request by (not necessarily in the order listed):

  • 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:

1.7.5.1  Valid Issuers

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

1.7.5.2  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 as shown in Figure 21. 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.

AppAuthExtDir_4.png
Figure 21: JWT Stored Signing Key Authentication

  • 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 as shown in Figure 22. The specified URL should return the signing keys in one of the following formats:
    • JWK Set: please 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.
    We recommend using fetched signing keys when you need to periodically rotate the signing keys.

AppAuthExtDir_5.png
Figure 22: JWT Fetched Signing Key Authentication

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

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

NOTE
The user should name the application to have a full distinguished name of the application in AD.

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.

AppAuthExtDir_6.png Figure 23: Authenticate app using External Directory

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 SAVE.
  4. In the detailed view of the new authentication method page, set the expiration period in the Expiration Setting section as shown in Figure 24 and click UPDATE. ChangeAuth.png Figure 24: Expiration Settings When Changing App Authentication Method

1.7.7  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. To enable OAuth:

  1. In the create application form, click the toggle Enable OAuth.
  2. In the Authorized Redirect URIs field, enter the redirect URL. AppAuth_Oauth1.png Figure 25: Enable OAuth
  3. Click SAVE to save the application.
    NOTE
    OAuth can also be enabled from the detailed view of an app as shown below:
    AppAuth_Oauth2.png
    Figure 26: Enable OAuth

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 following consent page. AppAuth_Oauth3a.png
    Figure 27: Enable OAuth
  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.

1.8  Create Applications and Groups Programmatically using App Authentication Methods

1.8.1  Create Administrative Apps

Sometimes we might need to create groups and applications programmatically using application authentication methods 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.

AdminApp1.png Figure 28: Administrative App

NOTE
The Fortanix DSM Administrative App can only be created by Account Admins.

To create an Administrative App:

  1. Go to the Administrative Apps page as shown in Figure 28 and click ADD ADMINISTRATIVE APP.
  2. The Administrative App will display all the authentication methods that are currently supported by Fortanix DSM applications:
    • API Keys (no ‘s’)
    • Certificate
    • Trusted CA
    • JWT Web Token

    AdminApp2.png Figure 29: Authentication Methods

    NOTE
    There can be more than one administrative apps created with each administrative app mapped with different authentication methods.
  3. Click CREATE once the authentication method is configured for the administrative app.

    AdminApp3.png Figure 30: Administrative App created

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

    AdminApp4.png Figure 31: Authentication methods

    NOTE
    • Administrative apps can create and delete quorum approval requests.
    • Administrative apps can manage keys without the app manageable permission.

1.8.2  Disable/Enable Administrative App

To disable an administrative app:

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

    AdminApp5.png Figure 32: Disable/enable Service Account

1.8.3 Delete Administrative App

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.

    AdminApp6.png Figure 33: Delete Administrative App

1.8.4  View Audit Logs of Administrative App

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.

    AdminApp7.png Figure 34: View audit logs

1.8.5  IP Whitelisting of Applications in Administrative Apps

Refer to the next section for more details.

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

NOTE
  • The IP Whitelisting of the application is an additional restriction on authenticating an application among the available authentication methods present such as authenticating using API Key, Certificate, Trusted CA, Google Service Account, and JSON Web Token.
  • This authentication mechanism should not be relied upon for security since the IP address can be fabricated.
  • If you do not see the IP Whitelisting setting enabled in the UI, please contact your System Administrator.

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 IP.png
    Figure 35: Add IP address range
  2. Select Restrict authentication to trusted IPV4 CIDRs option.
    IP1.png
    Figure 36: Enter trusted IPV4 CIDRs
  3.  Enter the CIDR as shown in Figure 36. 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
     
    1. Click SAVE to save the settings as shown in Figure 37. IP2.png Figure 37: Saved CIDRs

1.10  References

Was this article helpful?
0 out of 0 found this helpful