Invoke a Service Provider API with a JWT Assertion

You can invoke the API of a service provider using a JWT user or client assertion security policy in an integration. For this example, a high-level overview is provided of how to call a simple "hello world" API from a service provider using a JWT assertion.

Note:

This use case describes accessing an API of the National Health Service (NHS). The content of the JWT header and JWT payload files uploaded are unique to the standards of the NHS. If accessing an API of a different service provider through a JWT assertion, ensure that your header and payload files conform to the standards of that service provider.
  1. Manually create a signing key outside of Oracle Integration.
  2. In the navigation pane, click Settings, then Certificates.
    1. Click Upload.
    2. In the Alias name field, enter the alias name. You also specify this alias on the Connections page when configuring the JWT assertion security policy. For this example, the following alias is specified. 
      nhsJwtDemo
    3. From the Type list, select Signing key.
    4. Click Private.
    5. Click Select key file to select the signing key you created previously.

      The Upload certificate page is shown. Below the introductory text are fields for Alias name, Description, and Type. Below this is a Category list with selections for Private and Public. Below this is the Select key file section. The Choose File link is shown. Below this is the Sign private key password field.

    6. If the private signing key is encrypted, enter the private signing key password.
  3. In the navigation pane, click Design, then Connections.
    1. Create a REST Adapter invoke connection, and click Create.
      The Connections page is displayed.
    2. In the Connection type field, select a connection type.
    3. In the Connection URL field, enter the URL of the API to access. For this example, an NHS URL is provided.

      The Properties section shows fields for Connection type and Connection URL.

    4. From the Security Policy list, select OAuth Client Credentials using JWT Client Assertion. This selection is typically used for application-driven APIs.
    5. In the Access token URI field, specify the access token URI for the service provider.
    6. Upload the JWT headers file and JWT payload file.
      You create the content in JSON files. The content of both files is specific to the service provider you want to invoke. For this example, the NHS-formatted header and payload follow this format:
      • JWT header file: This file requires an algorithm (alg) and a key identifier (kid) that is uniquely-generated and associated with the uploaded signing key.
        : {
  "alg": "RS256",
  "kid": "AfZ4kopskH4V7oe11tRIBDbe4539fie_P",
  }
      • JWT payload file: At a minimum, this file requires the iss (issuer of the claim), sub (user name subject), aud (audience), and exp (token expiration time) claims and values (jti is optional). These claims are described in your NHS documentation. See Access Tokens and Audit (JWT).
         {
  "iss": "1445233d3fgd3fbdb30638r536d129fc",
  "sub": "1445233d3fgd3fbdb30638r536d129fc",
  "aud": "https://dev.api.service.nhs.uk/oauth2/token",
  "exp": 1674594057,
  "jti": "b2cdfckd-3gre-2u2d-4150-2062f10cfbd4"
}

      Additional claims, including custom claims, can also be included in both files. See the documentation provided by the service provider for instructions on how to configure these files.

    7. For the JWT private key alias, enter the same name you specified when uploading the signing key certificate in Step 1. This name is used to generate the JWT assertion.


      The Security policy list shows OAuth Client Credentials using JWT Client Assertion as the selected value. Below is the Access token URL field, the JWT headers in JSON format field, JWT payload in JSON format field, and JWT private key alias field.

    8. Click Optional security if you want to specify optional scopes or access token request values. For this example, none are specified. The way to specify the scope and access token request values varies from service providers. Some service providers require values. See Variations of JWT Usage by Service Providers.
    9. Test the connection.
      You are ready to create an integration that uses this connection to call the NHS API.
  4. In the navigation pane, click Design, then Integrations.
  5. Create an application integration to call the NHS API and receive an "echo" in response.
  6. Design the integration. For example, add and configure a REST Adapter trigger connection.
  7. Add a REST Adapter as an invoke connection to call the NHS API.
    1. On the Basic Info page of the Adapter Endpoint Configuration Wizard, specify the relative resource URI. For this example, a "hello world" API provided by the NHS is specified. This API calls back to the integration after the JWT token is successfully validated by the NHS service provider.
    2. Select the action to perform.

      The What is the endpoint's relative resource URL field is shown. Below this is the What action do you want to perform on the endpoint list.

    3. Complete the remaining fields of the wizard.
  8. Complete the remaining design of the integration.
    When complete, the integration looks as follows:


    The integration shows a REST Adapter trigger, a mapper, a REST Adapter invoke, and a mapper.

  9. Activate the integration.
  10. Hover over the row of the integration on the Integrations page.
  11. Select Actions Actions icon, then select Run.
  12. Run the integration.
    The activity stream provides details, including the response sent back.


    The Activity stream is shown. At the top is the instance ID. To the right are three icons. Below this, the tracing level is set to Production. Below this are the milestones of the integration flow. Each milestone is green, indicating that the integration instance was successful.

    In the Configure and run page, the response message indicates that the NHS service provider validated the token and responded back with a Hello Application! message.


    The Response section shows a status of 200 OK and the instance ID. Below this, the Body tab is selected to show the message response. The Headers tab appears to the right.

See JWT Assertion Support for Outbound Invocations.