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.
      
      

      

      
      
   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.
      
      

      

      
      
   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.

      
      
      

   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.
      
      

      

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

   
   
   

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

    
    
    

    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.

    
    
    

See JWT Assertion Support for Outbound Invocations.