Introduction

This article explains how we can secure our third-party endpoints using Oauth authentication using inbuilt cloud stream REST connector

Audience

It is assumed that readers of this article know how to create integrations on Webmethods.io Integration.

Pre-requisite

• webMethods.io Integration tenant.
• Endpoints enabled with oAuth 2.0

      Use Case    

• Clients want to secure their endpoints using oAuth 2.0.
• In our case we will be using client credentials as grant type to achieve same.

• Step 1: Get the access token using client credentials
• Step 2: Authorization server returns access token to the business client
• Step 3: Client submits the request to resource server along with access token
• Step 4: resource server internally validates the access token with authorization server
• Step 5: On successful validation of token, the resource server sends the response back to the business client.

In our usecase:

• Authorization sever: Local auth server running on webMethods.io Integration
• Resource server: API hosted on webMethods.io Integration
• Business client: flow service which invokes the API (secured with oAuth 2.0)

         What is oAuth 2.0?

·       oAuth 2.0 (Open Authorization) is an authorization framework that allows applications to obtain secure access to user resources without exposing user credentials (like passwords).

·       It enables third-party apps to request limited access to a resource on behalf of the user

·        For more details refer the below official link: https://oauth.net/2/

    🔑 OAuth 2.0 Grant Types (Flows)

• Authorization Code (Most Secure) – Used by web and mobile apps to request access tokens securely.
• Client Credentials – Used for machine-to-machine (M2M) authentication, like APIs.
• Implicit (Deprecated) – Used for single-page apps (SPA) but is now discouraged due to security risks.
• Password Grant (Not Recommended) – The app directly collects user credentials (less secure).
• Refresh Token – Allows apps to get a new access token without user intervention.

For more details refer to the below link: https://oauth.net/2/grant-types/

• In our use case we are going to implement the using the grant type= “Client credentials”, As want to do connectivity between 2 machines without any manual intervention.

 Assets Developed for the use case Implementation:

•        Configured REST to get the access token
•         Configure REST API in webMethods.io Integration.
•         Creating the Application on Authorization server
•         Configured REST connector with OAuth 2.0 as authentication mechanism
•         Callback service: to generate the token in the backend when access token expires.
•         Flow service to test the flow end to end.

Note: We must create callback service to generate the token when it expires, As when we have client credentials as grant type then we don’t get refresh token in the response. Refer the sample response email for same.

{

"access_token":"b31ba626deaf45dfbf",

"token_type":"Bearer",

"expires_in":60,

"scope":"POScope"

}

Flow diagram for the usecase

Description for each step

1. Client flow service invokes purchase order API using the rest connector “GetStatus”
2. GetStatus connector receives the request and invokes the call back service to get the access token.
3.  Callback service internally invokes the REST connector.
4. This REST connector submits request to get the access token from Authorization server for grant_type as “client_credentials”.
5. Authorization server provides the access token back to the REST connector.
6. REST connector then sends the access token back to the callback service.
7. This callback service forwards token to the REST connector which submits the request to API.
8. Now GetStatus REST connector will submit request to the API with access token.
9. PurchaseOrderStatus will receive the request and check for the authenticity of the token.
10. Send the successful response for the request to the REST connector
11. Same response is sent back to the client.

Implementation Steps

Create REST connector for access token

•  This REST connector will be used to generate access token.
•  Add new REST connector and name it as “getaccesstoken”.
• Provide the access token URL and select the authentication type as “credentials”.

Request for getting access token 

grant_type: "client_credentials"  (query string parameter in the connector under request)

Response

{

"access_token":"b31ba626deaf45dfbf",

"token_type":"Bearer",

"expires_in":60,

"scope":"POScope"

}

• Provide the resource name and configure the path.
• Select the “POST” method   

• Under the request tab set grant type parameter as QUERYSTRING_PARAMS.
• Configure the header for content-type

·        Under response tab create the document with the below Json definition.

{

"access_token":"b31ba626deaf45dfbf",

"token_type":"Bearer",

"expires_in":60,

"scope":"POScope"

}

·        Save the connector

·        Now we have to configure the account under which the REST connector will be invoked.

·        Set Authorization type as basic

·        Click on Add new Account and provide client ID and client secret under the username and password.

Create REST API

• Under the project navigate to the API tab and configure the REST API.
• In our case we have created the API and named it as “PurchaseOrderStatus” API.

Note: Please follow the below documentation for configuring the API.

https://docs.webmethods.io/saas/webmethods-integration/11.0.10/apis/rest_api_builder/index.html#example_rest_api

Create Application on Authorization server

• We are using the Authorization server OOB offered by webMethods.io Integration.
• In our usecase we have registered the client and named it “RetailAppClient”.
• Create Scope and in our case we have named it as “PO Scope”.
• Add the API (PurchaseOrderStatus) created in the previously in the scope.
• Select the scope in the application.
• Refer the below link guides you to do step by step for OAuth 2.0 setup.

https://community.ibm.com/community/user/integration/viewdocument/webmethodsio-integration-secure-or?CommunityKey=82b75916-ed06-4a13-8eb6-0190da9f1bfa&tab=librarydocuments

Configured REST connector with OAuth 2.0 as authentication mechanism

·        Navigate to the connector tab under the project and select the REST connector.

·        Click on Add.

·        Provide the API url and select the authentication type as OAuth 2.0

• Under the request tab configure the header, parameters and body as required.
• In our usecase we are passing the PO number as parameter and there is no body required.

·       

• In similar fashion configure the details for response tab like header and body with the http codes as per the requirement.
• Save it.
• Our REST connector template is ready and now we will configure the accounts and operations for same.

• Click on New account and start providing the details.
• As mentioned earlier we want to configure the account so that in future once the access token is expired it is regenerated at the backend without any manual intervention.
• Provide the ClientID, client secret obtained by registration of Application on Authorization server.
• As of now we don’t have any access token, provide some random value to it.

• Set refresh access token to “true”.
• In the refresh URL we can pass any URL, As this will not be used to generate the token.
• Select refresh URL request as “refresh token call back service” from the drop down.
• Under the refresh token call back service click on + icon and add new callback service.
• This will generate the template for call back service, which we will configure shortly.
• In our we have named it as “GetStatus_PO_Acc_callback”

• Set the session management as fixed or auto.
• If we set the session management as fixed then it will start maintaining the based on the timeout value set in session timeout.
• The value of session timeout should be based on backend settings.
• If we set the session management as auto, then it will start maintaining the session as soon as we start invoking it.
• If we set the session management as “none” then access token will not be refreshed.
• In our case we are setting the session management as “auto”.

• Click save.
• Now we have to configure the callback service “GetStatus_PO_Acc_callback”.

• This callback service will have input and output already configured.

Configure the callback Service: GetStatus_PO_Acc_callback

• Click on the flow service GetStatus_PO_Acc_calback.
• Click on the i/o tab to check the pre-configured input and output parameter.

·   

• Select the rest connector “Getaccesstoken” created in the previously

• In the next step map the access token and other details to output parameter.
• Note: expires_in output variable should be mandatory mapped, as based on this value the token is generated in the backend.
• Below is the response we received when we run the service directly.

Create the flow service to test end to end

• Add the new flow service and name it as “GetPurchaseOrderStatus”
• Select the REST connector “GetStatus”.
• In our case we need to pass the PO number to get the status from API.

•       Now run the flow service. This flow service invoke the rest connector which will invoke the API to get the response. While invoking, this API  used OAuth to get the access token. To get this token rest connector “getaccesstoken” will be used and it will internally generate the token.