› Integration › OAuth servers › Authentication methods

Authentication methods

TotalAgility supports the following authentication methods.

Secret in post body

The client ID and secret are sent in the request's body.

When you are configuring an OAuth server for a POP3, IMAP or MS graph type of import source, we recommend that you use the "Secret in post body" authentication method.

Secret using basic authentication

The client ID and secret are sent in the header as encoded text.

Shared secret key JWT (JSON Web Token)

Configure the values for claim attributes. TotalAgility provides inbuilt support for HS256 signature algorithms as this is commonly used by OAuth providers.

  1. The following read-only fields are available with default values. These values are pre-configured in each authorization grant:

    • Issuer: Issuer of the JWT and contains the client ID of the OAuth Client.

    • Subject: Subject of the JWT (user). This value also contains the client ID.

    • Audience: Recipient for which the JWT is intended (the URL of the Authorization Server's token endpoint).

    • JWT ID: Unique identifier.

  2. Expiration time: Define the time after which the JWT expires. (Default: 60 minutes)

  3. Add additional claims as needed.

    1. Under Additional claims, click .

    2. Enter a name and value.

    3. Click Add.

These fields are also available for the Private key JWT method.

Private key JWT

When you select Private key JWT, you can select Certificate and set a Certificate password. However, the certificate and password are not available on reopening the settings. You can enter values for claim attributes. TotalAgility provides inbuilt support for the RS256 signature algorithm as this is commonly used by OAuth providers.

Custom

TotalAgility has inbuilt support for the commonly used OAuth authentication methods. However, you can write your custom token generation logic inside a synchronous business process.

You can either use a sample process and modify it to your requirement or create a new process.

If using a custom process with the authorization code grant type, you must refresh or renew the access token.

TotalAgility also provides sample .NET code (OAuth Sample .Net Code.zip) to generate tokens for different grants using client secret/client assertion/password and other client details. See Use sample code.

Create a new synchronous map

For a new synchronous map, you must specify the following initialization variables and output variables to generate tokens.

Initialization variables

Variable Id Variable type Authorization Code Grant process Resource Owner Password Credentials Grant process Client Credentials Grant process Description
CLIENT_ID string Applicable Applicable Applicable A string that identifies the client.
CLIENT_SECRET string Applicable Applicable Applicable The secret string the client uses.
ACCESS_TOKEN_URL string Applicable Applicable Applicable The URL to get an access token. Specify the URL without "/token"
SCOPE string Applicable Applicable Applicable A string that defines the requested permissions.
AUTHORIZATION_CODE string Applicable Not Applicable Not Applicable The authorization code that the client receives from the authorization server.
REDIRECT_URI string Applicable Not Applicable Not Applicable If the redirect URI was included in the initial authorization request, the service must require it in the token request as well. The redirect URI in the token request must match the redirect URI that was used when generating the authorization code. Else, the service must reject the request.

Some OAuth servers may explicitly require to avoiding the redirect URI/scope in token requests.

CODE_VERIFIER string Applicable Not Applicable Not Applicable The application requests to exchange the code for tokens. It only sends the Code Verifier instead of a fixed secret. The Authorization Server can hash the Code Verifier and compare it to the hashed value it stored earlier. If the hashed value matches, the Authorization Server returns the tokens.
POST_PARAMETERS Dynamic Complex variable Applicable Applicable Applicable Additional post parameters to retrieve the access token.
QUERY_PARAMETERS Dynamic Complex variable Applicable Applicable Applicable Additional query parameters to retrieve the access.
REFRESH_TOKEN string Applicable Applicable Not Applicable If passed, the access token is generated using the refresh token.
USER_NAME String Not Applicable Applicable Not Applicable

The username of the resource owner. The username is not saved in the TotalAgility database and is available to custom map only during authorization or when saving in the Designer.

PASSWORD string Not Applicable Applicable Not Applicable

The password of the resource owner. The password is not saved in the TotalAgility database and is available to custom map only during authorization or when saving in the Designer.

Output variables

Variable Id Variable Type Authorization Code Grant Process Resource owner password credentials Grant Process Client Credentials Grant Process Purpose
ACCESS_TOKEN string Applicable Applicable Applicable

The access token used by TotalAgility to retrieve the required resource information.

ACCESS_TOKEN_EXPIRY_IN_SECONDS long Applicable Applicable Applicable The time in seconds after which the token expires. After expiration, a new token is generated using the refresh token.
REFRESH_TOKEN string Applicable Applicable Not Applicable

The refresh token passed by TotalAgility to the custom map to get a new access token.

To create a new process directly from the Custom authentication method screen, perform the following steps:

  1. Click Create new process adjacent to the Process field.

    The Create new process dialog box is displayed.

  2. Enter the Name for the process.

  3. Click OK.

For security and performance reasons, we recommend you clear the "Record history" option at the process level so that after job execution, the token is not saved.

Use sample processes

TotalAgility provides the following sample processes:

  • OAuth Authorization Grant Sample: Generates the long-lived page access token for Facebook using the Client secret, auth code, and other client details.

  • OAuth Client Credential Grant Sample: Generates the access token for the OKTA client using the certificate and other client details.

  • OAuth ResourceOwnerPassword Grant Sample: Generates the Azure AD token using the username and password and other client details.

These business processes are available in \\Kofax\TotalAgility\Sample Processes\OAuth Samples\OAuth Sample Package.zip.

For an on-premise multi-tenant environment, business processes are available in \\Kofax\OnPremiseMultitenancyInstall\Sample Processes\OAuth Samples\OAuth Sample Package.zip.

When you import this package, these sample processes are available for use in the System Category of business processes.

Use sample code

The sample .NET code is available in OAuth Sample .Net Code.zip located at \\Kofax\TotalAgility\Sample Processes\OAuth Samples\

This sample code can be used to generate tokens for different grants using client secret/client assertion/password and other client details.

You must have Visual Studio 2017 or higher with .NET Framework 4.8 installed to use the sample code.

TotalAgility does not maintain the sample code therefore you must perform and own any changes you make to the sample code.

  1. Extract OAuth Sample .Net Code.zip to a local folder. The OAuth Sample .Net Code folder contains the Visual Studio solution files and compiled DLL folder.

  2. Load the “OAuth Samples .Net Code\OAuthCustomMapSamples.sln” solution.

    The \\OAuth Sample .Net Code\OAuthCustomMapSamples folder contains:

    • AuthGrant folder: Contains the code to generate a Facebook user token using the OAuth code and other client details. This folder also includes the code to generate long-lived user tokens and long-lived page tokens using the short-lived user tokens.

    • ClientCredentialGrant folder: Contains the code to generate the OKTA app token using the certificate and other details.

    • ROPC folder: Contains code to generate the Azure AD user token using the user credentials and other details.

  3. Compile the code in the release mode. Keep all other settings intact.

    The “OAuth Samples .Net Code\OAuth Samples .Net Code\bin\Release” folder contains the combined “OAuthSamples.dll” which can be used in TotalAgility.

See also: