Configure a JWT External Authentication Method

When an end user needs to verify their identity with a JWT External Authentication Method, one of your company servers, not the Digipass S3 Server, authenticates the end user. This section refers to this company server as the RP Server.

How a JWT external authentication method works

Let's assume that you have implemented user ID and password as a JWT External Authentication Method. Figure 7a illustrates how Digipass S3 Software interacts with your RP Server when an end user wants to authenticate.

Figure 7a Digipass S3 Interaction with RP Server during JWT External Authentication

1. Using your client app, the end user decides to login with their ID and password.

2. Your client app interacts with the Digipass S3 App SDK to send the ID and password to your RP Server to authenticate.

3. If the RP Server successfully authenticates the end user, it sends a JWT to the App SDK.

4. The App SDK sends this JWT to the API Server.

5. The API Server's JWT External Authentication plugin validates the JWT, extracts the username from the JWT, and sends that in a request to the Authentication Server.

6. The Authentication Server creates a response intended for the App SDK and sends that to the API Server.

7. The API Server sends the response to the App SDK.

Configuration instructions

Implementing a JWT External Authentication Method requires that you make changes to your client app, augment your RP Server to create and send a JWT after authentication, configure the JWT External Authentication plugin to validate that JWT, and configure the JWT External Authentication method in the Auth Server so it can be used in an Adaptive Rule. This process is described in detail below.

If your RP Server cannot return a JWT containing standard claims, then the Digipass S3 JWT External Authentication Plugin won't work for you. If your RP Server uses passwords for user authentication then you can use the Password External Authentication plugin. Otherwise you must create a custom External Authentication plugin to validate the credential that your RP Server returns.

1. Identify the JWT External Authentication Method that you want your end users to use and identify the RP Server that authenticates with this external method.

2. Add support in your client app for the JWT External Authentication Method by implementing specific classes. These classes in your client app display the UI, send an authentication request for a specific JWT External Authentication Method to your RP Server, and forward the JWT sent by the RP Server to the JWT External Authentication plugin. See Using an External Authentication Method in the Developer Guide for Android, iOS or Web.

3. Configure the Digipass S3 JWT External Authentication plugin to validate the JWT that your RP Server sends. The JWT External Authentication plugin validates using a JSON configuration object called jwt_config. Based on its default jwt_config, the JWT External Authentication plugin expects to validate a JWT with a lifespan of 3 minutes that was encoded using the symmetric HS256 algorithm with one secret key.
   
   For security reasons, each of your tenants needs to have a different jwt_config object in order for that tenant to use a JWT External Authentication method. It is easy to generate a jwt_config object using either the Admin Console or the Command Line Interface.
   
   Use the Admin Console to generate a default jwt_config:

   1. Switch to the desired tenant. Navigate to Configuration > API Server > Authentication API > External Authentication Plugins.

   2. Click Generate next to the label JWT Authentication Method.

   3. Click the label JWT Authentication Method to view the newly generated jwt_config object.

   4. Click and drag to select the "generate" field of the jwt_config object. Copy and paste it into a text file to use in step 5.
      

   Use nnl-mgmt.sh to generate a default jwt_config:

   The example below shows how to use this command for a tenant called finance. Replace https://MyRPServer.com with the URL for your RP Server.
   

   ./nnl-mgmt.sh apiserver create -tenantid finance -type ExternalAuthenticationPlugin -name jwt_config -issuer "https://MyRPServer.com"

   The example below creates a file called newExtAuthConfigFile that you can use in the next step.
   

   ./nnl-mgmt.sh apiserver export -tenantid finance -type 
   ExternalAuthenticationPlugin -name jwt_config -file newExtAuthConfigFile

      For more information about nnl-mgmt.sh's apiserver command, see API Server Configuration Commands.

4. You may wish to modify the JWT External Authentication plugin's jwt_config to do the following:

• If your RP Server's URL is different from the API Server's URL, you must modify jwt_config to add your RP Server as an issuer. See Adding an Additional Issuer.

• If you prefer to use an algorithm other than HS256, specify that algorithm and key needed to decode the JWT.

• Define where to find the key.

• Specify how long the JWT is valid.

For detailed instructions, see When to Modify a JWT Configuration Object. You can find documentation about jwt_config in Configuring JWT Generation and Validation. You can also refer to the subsection ExternalAuthentication Plugins.

5. Configure your RP Server to generate a JWT with the claims listed in Claim Set. When the RP Server successfully authenticates an end user, the RP Server must send this JWT to your client app. It may be helpful to give the text file created in Step 3. to your RP Server administrator, so they can use it to generate a JWT that can be validated by the Digipass S3 JWT External Authentication plugin.

6. Define the JWT External Authentication Method in the Authentication Server. See Adding a New Non-FIDO Authentication Method. Digipass S3 Software ships with an External Authentication method that you can use.

7. To use an External Authentication Method during Adaptive Authentication, add the External Authentication Method to the sequence of a new or existing Adaptive Authentication rule. See Step 5D. Enter Sequences.
   
   To use the method for Quick Authentication, modify how your client app performs registration and authentication. See Registering for Quick Authentication in the Developer Guide for Android, iOS or Web. Also see Implementing Quick Authentication in the Developer Guide for Android, iOS or Web.