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 2.0 providers.

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.
Expiration time: Define the time after which the JWT expires. (Default: 60 minutes)
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 2.0 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.

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:

Click Create new process adjacent to the Process field.

The Create new process dialog box is displayed.
Enter the Name for the process.
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.

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.
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.
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.