How to Use the OAuth 2.0 Client Credentials Flow Using RS256-signed JWT Bearer

This topic walks you through how to create a WebService API, creating a server user and using the OAuth 2.0 client credentials flow (https://tools.ietf.org/html/rfc6749#section-4.4) to retrieve an access token using a RS256-signed JSON Web Token (JWT) bearer token (https://www.rfc-editor.org/rfc/rfc7523) that can be used as an authorization bearer for accessing that WebService API.

Create a WebService API

1. In your Designer, create a new project using the Standard WebService Framework.

   

2. Your project should contain one end point, which is called "function_1".

   

3. Click on your project name. In the Viewer screen, click the Details node and click modify.
4. In the Security section of the page, enable authentication (1) and add a user role (2 and 3). Save these changes.

   

5. Publish your project, ensuring that you set a start code.

   

The URL of the WebAPIExample endpoint will look like the following: https://<logicnets-hosts>/<company>/<start-code>/<end-point>; for example,  "https://lua5.logicnets.local/logicnets/WebAPIExample/function_1".

Create a Server User

1. From your LogicNets dashboard, open AccessManagement.

   

2. Create a new user, ensuring the user type is set to server (1). Copy the client id for use below and click Add (2).

   

3. Change Authentication Method to Bearer Authentication with RS256 signed JWT Web token (1) and click Generate new RSA key pair (2). Download the private key file or copy the generated private key for use below (3).

   

4. Click Save.
5. Create a new user group called webapiusers (1) and click Add (2).

   

6. Add the server-user you created in the previous step as local user.

   

7. Add the apiuser role of the previously published WebAPIExample by selecting WebAPIExample(1) and selecting apiuser (2). Click Assign (3).

   

8. Save the user group.

Create an Access Token to the WebAPIExample

With the steps above complete, you can use different clients to create an access token and access the WebAPIExample. This topic demonstrates using Postman (https://www.postman.com/), which has an integrated solution for calling OAuth2 IdPs to generate access-tokens. However, Postman does not support directly using a JWT-bearer as client-assertion-type (see https://www.rfc-editor.org/rfc/rfc7523), so in this tutorial we do this manually using jwt.io.

1. Open https://jwt.io/.
2. Create a JWT token, by doing the following:
   • Copy and paste the following text in the HEADER field (1):
     • {
         "alg": "RS256",
         "typ": "JWT",
         "nonce": "<nonce>”
       }
     • Copy and paste the following text in the PAYLOAD field (2):
       {
         "aud": "https://<logicnets-host>/<company>",
         "sub": "<user-id/client-id>",
         "iss": "<issuer-id>,
         "iat": <issue-at>,
         "exp": <expires-at>,
         "jti": "<unique-id>"
       }
     • Fill in the blanks:
       • aud (audience) -  This must contain the hostname and the company of your LogicNets installation, e.g. https://lua5.logicnets.local/logicnets.
       • sub (subject) – This must contain the client-id of the server-user you created earlier, e.g. 4664FD8C-9CEC-A8A2-D666-02A352A492A1.
       • iss (issuer) – This must contain a valid identifier of the API client, e.g. https://client.org.
       • iat (issued at) – This is the epoch time in seconds the JWT token was created. You can use https://www.epochconverter.com/ to generate a valid epoch stamp of now 1695023951 (Mon, 18 Sep 2023 07:59:11 GMT).
       • exp (expires at) – This is the epoch time in seconds when the JWT token will expire; for example, 1 hours (=3600) later than when the JWT token was created: 1695027551.
       • jti – This must contain a unique identifier; for example, f5203ecb-ae65-4a4b-8914-67baa258fca6.
     • Copy and paste the private key generated when you created the server-user (3).

       

     • Copy the generated JWT token (4).
3. Start Postman.
4. Create a new GET request (1) and fill in the URL (https://<logicnets-hosts>/<company>/oauth2token (e.g. https://lua5.logicnets.local/logicnets/oauth2token) (2), setting the following query parameters (3):
   • grant_type must be "client_credentials".
   • client_assertion_type must be "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".
   • client_assertion must contain the generated JWT token.

     

5. Click Send (1) and copy the access_token from the response body (2).

   

6. Create a new GET request to call the WebAPIExample.
   • Fill in the URL: https://<logicnets-hosts>/<company>/<start-code>/<end-point> (e.g. "https://lua5.logicnets.local/logicnets/WebAPIExample/function_1"). Note: The system will return a 403 error if no authentication header is passed.

     

   • To avoid a 403 error, you must add the authorization. Select Bearer Token (1) and copy and paste the access-token you generated earlier (2) in this process.

     

   • Click Send (1). The response status should be "200 OK" and the body will return the example data (3).