Authentication - App and User

1.0 Introduction

All clients connecting to Fortanix-Data-Security-Manager (DSM) must be authenticated. Clients are classified as either users or applications. A user authenticates to Fortanix DSM using a password. An application authenticates to Fortanix DSM using either an API key or a TLS client certificate.

For both users and applications, the authentication flow operates as follows:

• Make a request to the create session API, authenticated with the master credential (password, API key, or client certificate) and HTTP Basic authentication. If authentication is successful, Fortanix DSM returns a “bearer token” which authenticates the client for the duration of a login session.

• Make requests to other Fortanix DSM APIs as desired, presenting the bearer token with each request. If the client is an application using certificate-based authentication, each request must also be authenticated with the client certificate.

• When the session is no longer needed, it is recommended to use the terminate session API to log out.

For REST API example using CURL command, refer to Example code - User Authentication.

Fortanix DSM APIs may be available to users only, to applications only, or to both users and applications. For information about the client types allowed by each API, refer to the API reference.

2.0 User Authentication Using Passwords

Authorization: Basic dGVzdEBleGFtcGxlLmNvbTpwYXNzd29yZA==

2.1 Password Reset

A user who has forgotten their password can initiate a password reset by clicking the “Forgot your password?” link on the login screen of the web interface and entering their email address on the form. A password reset link will be sent to the user by email.

3.0 Application Authentication Using API Keys

An API key is simply a random, secret token, that identifies an application in much the same way as a password identifies a user. The API key for an application can be retrieved in the Application view in the web interface or using the get application API. The API key should be provided to the application in a secure manner.

If you retrieve an application's API key in the DSM web interface, it is already encoded in the proper form for passing as the Basic auth parameter when calling the create session API.

A typical authorization header looks like this:

Authorization: Basic NzFmYWY3ZDktZDIyZi00NjRjLWE1ZDEtZGIyYWZjZDE5MzZjOjRLdk1OMHdwT2pWZWVjV2Y3X0V1Q3FWSVpVTTlnRlVZeFJnM0tmTl91OFItdlhudzFSREE1ejlUc21rRXVPY0dZVU1QNnQxeGJBd2ZfU2Nic2tqUlJ3

If you do not use the DSM web interface but need to retrieve the application credential directly using the RESTful Apps APIRESTful Apps API, the API key can be constructed as follows:

The Basic authentication string is the Base64 encoding of the application ID and the application credential, separated by a colon. For example, the API key above represents the Base64-encoded application ID 71faf7d9-d22f-464c-a5d1-db2afcd1936c and credential 4KvMN0wpOjVeecWf7_EuCqVIZUM9gFUYxRg3KfN_u8R-vXnw1RDA5z9TsmkEuOcGYUMP6t1xbAwf_ScbskjRRw.

3.1 Regenerating an API Key

You can regenerate an application’s API key by opening the application detail page, navigating to the Info tab, and clicking the Regenerate button in the API Key section.

4.0 Application Authentication Using Client Certificates

Applications can also be authenticated by presenting a client certificate when establishing a TLS connection with Fortanix DSM. The certificate associated with an application must be configured in Fortanix DSM, either using the web interface or by using the update application API.

When authenticating with a certificate, the HTTP Basic authentication string is the Base64 encoding of the application ID. Present both the certificate and the bearer token obtained from the create session API with each request.

5.0 Application Authentication Using Trusted CA

Applications can also be authenticated by presenting a client certificate that is signed by a trusted CA when establishing a TLS connection with Fortanix DSM. The trusted CA certificate must be configured in Fortanix DSM, either using the web interface or by using the update application API.

If the app presents any certificate (leaf or chain) that is signed by the registered trusted CA certificate (when the app was enrolled) and the common name in the certificate matches with what is registered when the app was enrolled, then authentication will succeed.

To use this method, you must 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.

For more information on how to use this method, refer to Using Client TLS Certificate Issued by Trusted CA.

To use this method of authentication for an application do the following:

1. Create a self-signed root CA or use a CA if you have one.

2. Create a CSR, make note of the common name you use in CSR. Where, the common name refers to the app UUID.

3. Sign your CSR with your root CA.

4. Add an App and use the Trusted CA auth method.

5. Upload/paste the root CA.

6. Enter the common name you used in CSR.

You can also introduce an intermediate CA to have a chain of certificates. In case you are using a chain, then the mechanism will be same, that is add CA certificate when adding App, however, when authenticating the app, you will need to present the completed chain by putting the leaf certificate followed by an intermediate certificate in the same file.

When authenticating with a certificate, the HTTP Basic authentication string is the Base64 encoding of the application ID. Present both the certificate and the bearer token obtained from the create session API with each request.

Additionally, you can use the Certificate Revocation List (CRL) or Online Certificate Status Protocol (OCSP) methods to authenticate an application using client TLS certificate issued by Trusted CA.

6.0 Switching Between API Key and Client Certificate Authentication

To change an application that is authenticating with an API key to authenticate with a client certificate, or vice-versa, open the application detail page, navigate to the Info tab, and open the “Change authentication method” drop-down. Select the desired authentication method and click Save. If switching to client certificate authentication, you will be prompted to upload a certificate.

7.0 OAuth Authorization Framework in Fortanix DSM

A user can authorize an app for key management cryptography operations in groups that the user has an administrator role. This is achieved through the OAuth authorization framework in Fortanix DSM. The following is a step-by-step description of how an app can request and acquire this authorization:

• The app redirects the user to the Fortanix DSM authorization endpoint /oauth/v1/auth asking for
  user's authorization.

• The user authenticates to Fortanix DSM and gives consent. The user also needs to pick a default group for the app from groups in which he/she has the administrator role.

• Fortanix DSM redirects back to the app with an authorization code.

• The app authenticates itself to Fortanix DSM (using an API key or a certificate) then passes the authorization code to the Fortanix DSM token endpoint /oauth/v1/token. The token endpoint will generate a new bearer token for the app based on the authorization code granted by the user.

• The app can use the new bearer token to perform crypto and key management operations in user groups. Actions performed by the app using this token are listed in the audit logs as if they were performed by the user.

For more information about the OAuth authorization framework refer to RFC 6749.

For the OAuth scheme in the PKCS#11 library refer to the section OAuth with PKSC#11 Library.

For examples using CURL commands, refer to the Example Code.