Welcome > Integration > OAuth 2.0 servers > Authentication methods

Authentication methods

TotalAgility supports the following authentication methods.

Secret in post body

The client ID and secret is sent in request's body. The request is verified using fiddler.

Note 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 is sent in the header as encoded text. The request is verified using fiddler.

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 2.0 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 2.0 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, certificate and password are not available on reopening the settings. You can enter values for claim attributes. TotalAgility provides inbuilt support for RS256 signature algorithm as this is commonly used by OAuth providers.

Custom

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

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

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 An string used to identify the client.
CLIENT_SECRET string Applicable Applicable Applicable The secret string the client will use.
ACCESS_TOKEN_URL string Applicable Applicable Applicable The URL to get an access token. Specify Url without "/token"
SCOPE string Applicable Applicable Applicable The full scope string defining the requested permissions.
AUTHERIZATION_CODE string Applicable Not Applicable Not Applicable This parameter is the authorization code that the client received 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 be an exact match of the redirect URI that was used when generating the authorization code. Else, the service must reject the request.
Note Some OAuth servers may explicitly require to avoid redirect URI/scope in token requests.
CODE_VERIFIER string Applicable Not Applicable Not Applicable The application makes the request to exchange the code for tokens, it only sends the Code Verifier instead of a fixed secret. Now the Authorization Server can hash the Code Verifier and compare it to the hashed value it stored earlier. Assuming the hashed value matches, the Authorization Server will return the tokens.
POST_PARAMETERS Dynamic Complex variable Applicable Applicable Applicable Additional post parameters which needs to be passed to retrieve the access token.
QUERY_PARAMETERS Dynamic Complex variable Applicable Applicable Applicable Additional query parameters which need to be passed to retrieve access token.
REFRESH_TOKEN string Applicable Applicable Not Applicable If passed, access token will be generated using refresh token.
USER_NAME String Not Applicable Applicable Not Applicable Username of the resource owner. This is not saved in the TotalAgility database and available to custom map only during authorization or when saving in designer.
PASSWORD string Not Applicable Applicable Not Applicable Password of the resource owner. This is not saved in the TotalAgility database and available to custom map only during authorization or when saving in 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 TotalAgility uses the access token to retrieve the required resource information.
ACCESS_TOKEN_EXPIRY_IN_SECONDS long Applicable Applicable Applicable When token is expired. After expiration, token will be generated using the refresh token.
REFRESH_TOKEN string Applicable Applicable Not Applicable TotalAgility passes the refresh token to the custom map to get 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.

Note For security and performance reasons, we recommend you to 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 long lived page access token for Facebook using Client secret, auth code and other client details.

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

  • OAuth ResourceOwnerPassword Grant Sample: Generates Azure AD token using user name 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.

Note 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 also includes the code to generate long lived user token and long lived page token using short lived user token.

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

    • ROPC folder: Contains code to generate Azure AD user token using 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.