Authenticating with a JSON Web Token

This topic describes how to connect to a REST API that requires a .json web token (JWT). This authentication mechanism can be considered "free form" because it allows you to configure a web authentication method that is used to retrieve a JWT, which is then passed to the REST API for authorization.

You can use this authentication type for custom authentication scenarios, where the REST API does not support any standard like OAuth 2.0. These are the basic requirements for using this authentication type in GENESIS:

  • The authentication process of the REST API returns a JWT or a .json object that contains a JWT.
  • At minimum, the returned JWT contains the expiration time (exp) claim that GENESIS uses to determine whether the token has expired or not. For more information, refer to Web Services Authentication Methods.

When the JWT expires, GENESIS automatically requests a new token by calling the web authentication method again.

The following procedure uses the Microsoft Dataverse REST API as an example. To access Dataverse data, you have to create an app registration in Microsoft Entra ID. It is the same application that is used in Authenticate with OAuth 2.0 and Client Credentials Grant, but this procedure creates a web authentication method instead of using the built-in OAuth 2.0 support. This illustrates that you can perform any kind of call using a web authentication method, as long as the result contains a JWT.

To connect to a REST API using .json web token (JWT):

  1. Open Workbench and in Project Explorer, expand your project > Data Connectivity.

  2. Right-click Web Services and select Create a new Folder. Give the folder a name and click Apply.

    You can skip this step and use an existing folder, like the default Sample Web Services folder.

  3. In Project Explorer, right-click the desired folder and select Add REST Service. The REST service configuration dialog is displayed.
  4. Give the service a name and in the General Settings section in Base URL, enter the URL for the desired REST API. This information is typically available in the API documentation. Then click Apply.
  5. In Project Explorer, right-click the newly added service and select Add Web Authentication Method. The Web Authentication Method dialog is displayed.
  6. Fill in the form with the parameters required to authenticate with the REST API.

  7. In the Authentication Result section, click Authenticate. When the anonymized schema of the authentication result is displayed in Result Schema, click Apply & Close.

  8. Go back to the configuration dialog of the related service (created in step 3) and in General Settings in Authentication, select JSON Web Token. The authentication options for JWT are displayed in the Connection Credentials section.

  9. In Connection Credentials, configure the authentication options as needed, and then click Apply. See the table for more information.

    Connection Authentication Option

    Description

    Authentication Method

    Use this drop-down list to select the web authentication method to be used to retrieve the .json web token.

    Token Property

    Use the drop-down list to browse the return schema of the web authentication method. If the web authentication method returns a .json object that contains the JWT, select the property in the return schema that contains the JWT.

    Authorization Parameter Kind

    Specify the way to send the JWT to the REST API when making authenticated calls from GENESIS.

    Authorization Parameter Name

    Assign a name to the authorization parameter. For example, when using HTTP Header as the Authorization Parameter Kind, this is the name of the HTTP header where the parameter value will be placed.

    Authorization Parameter Value

    Enter the value of the authorization parameter that is sent with each call. The special @JwtSecurityToken placeholder is replaced with the JWT before making the call to the REST API.

    The three Authorization Parameter fields describe how to build a parameter to use the JWT for the calls to the REST API. This parameter is automatically and transparently added to all web methods and web manipulators configured under the service.

    The following image shows an example of the settings.