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 following authentication type is supported for users using password:

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"
  2. Enter your password, and then click LOG IN.

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 log in 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 on 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 Administrator created locally on Fortanix DSM will not be able to log in to the account. When updating the SSO configuration, ensure 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.

If you select either of the following options, then Mandatory two-factor authentication to log in with password option is disabled.

  • 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 the Fortanix DSM account using their local password when the SSO mechanism is mis-configured.
  • 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 account using their local password when the SSO mechanism is mis-configured.

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

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

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

  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. 

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

OAuth / OpenID 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. 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`
  • 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 provided by the identity providers. For example:

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

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

  1. On the Authentication page, click ADD OAUTH INTEGRATION 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. For more information on OAuth / OpenID Connect provider configuration, refer to User Guide: Single Sign-On.

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:

  • Resolve user’s email address to a Distinguished Name (DN)
  • Authenticate to the directory using the DN and user-supplied password

DN Resolution Methods

To resolve the user’s email address to a DN, 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 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. 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. We recommend setting the userPrincipalName attribute for all users in the directory when configuring Fortanix DSM with UPN login method.

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

  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.

Changing Password

To update the password, perform the following steps:

  1. Log in to Fortanix DSM as a System Administrator.
  2. To change the password, go to the My profile
  3. Click the Change Password tab under password section.
  4. Enter your current password in the Current Password
  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.

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

1.3.1  Prerequisites

  • 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.
NOTE
  • To use your device for 2FA, it must support either FIDO U2F or FIDO2/WebAuthn.
  • Only verified users can configure 2FA. A user is verified when they successfully re-verified their email ID. When the "Sign-up email configuration" in the System Administration Settings is set to All Users or Users Since the users will be given the option to re-verify their email address.

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. To configure this, follow the steps below:

  1. Click My profile to go to your profile settings. 
  2. In the option for Two-step Authentication, click ENABLE to enable two-factor 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.

Accepting Terms & Conditions

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

TnC.png

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.
  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 option.
  3. Configure the required SSO integrations using SAML, OAUTH, or LDAP as described in Section 1.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 the IdP is not configured correctly.
  5. Now select the check box Mandatory two-factor authentication to log in with password.
  6. Click SAVE CHANGES to save the changes.
  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.
  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.

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:

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.

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.

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 and click REGENERATE.

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.

NOTE
  • If an application needs to authenticate to Fortanix DSM using a certificate, then the App Id needs to be embedded in the certificate in one of the following ways:
    • App Object Identifiers (OID): Provided as the value of a custom OID in the certificate.
    • Standard human-readable UUID encoding: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx provided as the value of CN.

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.

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://<fortanix_dsm_url>",
"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.

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
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, for example:
      https://<fortanix_dsm_url> (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. 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: 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.

 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.

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

NOTE
The App name must match the AWS ARN associated with the calling entity.

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 SAVE.
  4. In the detailed view of the new authentication method page, set the expiration period in the Expiration Setting section and click UPDATE

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

1.7.9 Workspace CSE App Auth 

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 Integration Guide: Fortanix DSM with Google Workspace CSE.

1.8  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. 
  3. Click SAVE to save the application.
    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.

1.9  Create Applications and Groups Programmatically using App Authentication Methods

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

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 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
    • Certificate
    • Trusted CA
    • JWT Web Token
    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.
  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.
    NOTE
    • Administrative apps can create and delete quorum approval requests.
    • Administrative apps can manage keys without the app manageable permission.

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

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

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

1.9.5  IP Whitelisting of Applications in Administrative Apps

Refer to the next section for more details.

1.10 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 
  2. Select Restrict authentication to trusted IPV4 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.
  5. Click SAVE to save the settings. 

1.11 Configuring LDAP Authentication When Using SSH

To configure LDAP authentication on the Fortanix DSM node while using SSH, follow the steps below:

  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.  

1.12  References

Comments

Please sign in to leave a comment.

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