Fortanix Self-Defending KMS provides access to its functions and APIs to two types of entities – humans (users), and machines (applications). There are many ways to authenticate to Self-Defending KMS 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 which controls which entity has authorization to perform which function under what conditions.
User Authentication Using Password
The below forms of authentication is supported for users using password:
Username and password stored in Fortanix Self-Defending KMS
This is done using the "Log in without SSO” option.
- In the Fortanix Self-Defending KMS login screen, select the option “LOG IN WITHOUT SSO".
- Enter your password, and then click LOG IN.
Username and password stored in Fortanix Self-Defending KMS along with second-factor authentication
Using a U2F (Universal 2nd Factor) device, such as a YubiKey or a Google Titan Key. To configure this, follow the steps below:
- Click My profile to go to your profile settings.
- In the option for Two-step Authentication, click ENABLE to enable two-factor authentication. Figure 4: Enable 2-Step Authentication
User Authentication Using SSO - Configuration
Fortanix Self-Defending KMS 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 setup SSO for your account:
- Login as administrator, and click the Settings icon in the Fortanix Self-Defending KMS UI, and then click the AUTHENTICATION tab in Account Settings page.
- 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 mis-configured, you will not be able to log in to your 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 password and access the account.
Currently, the below SSO mechanism is available for users:
SSO using a third-party identity provider
The following protocols are supported:
- OAuth / Open ID Connect
To Configure user authentication using SAML, follow the below steps:
- In the Authentication page, select ADD SAML INTEGRATION to configure SAML.
- 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 configure user authentication using OAuth, follow the below steps:
- In the Authentication page, click ADD OAUTH INTEGRATION to configure OAuth.
- 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.
- For more information on OAuth / OpenID Connect provider configuration, refer to User Guide: Single Sign-On
To configure user authentication using LDAP, follow the below steps:
- In the Authentication page, click ADD LDAP INTEGRATION to configure LDAP.
- 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.
For more information on LDAP authentication, refer to User Guide: Single Sign-On
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 Self-Defending KMS login screen. The user will now be presented with all the SSO authentication mechanisms that were configured for logging in to Fortanix Self-Defending KMS.
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.
Currently, there are five forms of authentication methods supported for applications:
Figure 12 - Application Authorization.
Using a system-generated API Key
When you create an application in Fortanix Self-Defending KMS, 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.
Figure 13: Copy API Key
Certain app integrations require 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 Self-Defending KMS with VMware VSAN integration. Once this integration is set up, Fortanix Self-Defending KMS could be used for both vSphere VM encryption and VSAN encryption.
Using a client TLS certificate
Applications can also authenticate to Fortanix Self-Defending KMS 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 certificate in PEM format only.
Figure 15: Upload Certificate
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 Self-Defending KMS. To use this method, you should specify the CA's certificate and the common name you expect in your application's certificate. When the app authenticates itself to the Fortanix Self-Defending KMS using a client TLS certificate, it will verify that the app's certificate is signed by the specified trusted CA and that the common name matches the expected value. To do this, select the Trusted CA option as the authentication method, and then upload a certificate using the UPLOAD CERTIFICATE The user can also paste the certificate using the text box provided. We support certificates in PEM format only.
- Common name: This is the common name in the certificate that the App will use to authenticate.
Google Service Account
Google Service Account method is used by a service account in Google Cloud to use the external KMS interface from GCP KMS interface. To learn more about this scheme, please refer to the article Using Fortanix Self-Defending KMS with Google Cloud EKM Interface.
JSON Web Token (JWT)
Applications can also authenticate to Fortanix Self-Defending KMS 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:
"sub": "my app",
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.
To authenticate to Fortanix Self-Defending KMS, the app should present the signed JWT along with its account UUID as an HTTP Basic Auth header encoded in the following form:
The following snippet shows how to do this encoding in a shell script (BASH):
$ echo -n "$ACCT_ID:$JWT" | base64 -w0
- The JWT body must include the following fields:
- sub the subject of the token must match the app's name in Fortanix Self-Defending KMS.
- iss the issuer of the token is validated against a list of issuers.
- aud the audience of the token must include the Fortanix Self-Defending KMS endpoint URL, e.g.
https://sdkms.fortanix.com (this might be different for you if using an on-prem Fortanix Self-Defending KMS cluster).
- 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 Self-Defending KMS 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:
One or more valid issuers. This information is used to validate the iss field of the JWT.
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 17. When specifying multiple keys, you should specify the Key ID so that keys can be differentiated using their 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
- Fetched: provide a URL that can be used to fetch the signing key(s). To improve performance,
Fortanix Self-Defending KMS would cache the fetched keys, but you can control how long the keys are cached as shown in Figure 18. 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:
We recommend using fetched signing keys when you need to periodically rotate the signing keys.
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.
- The IP Whitelisting of 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:
- Go to the detailed view of an application and click the EDIT button to the right of Allowed IP-addresses
Figure 19: Add IP address range
- Select Restrict authentication to trusted IPV4 CIDRs option.
Figure 20: Enter trusted IPV4 CIDRs
- Enter the CIDR as shown in Figure 20. 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.
- You can add multiple CIDRs using the ADD ANOTHER CIDR
- Click SAVE to save the settings as shown in Figure 20.
Figure 21: Saved CIDRs
- Using Fortanix Self-Defending KMS with Google Cloud EKM Interface: https://support.fortanix.com/hc/en-us/articles/360030816111-Using-SDKMS-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