IBM Support

Using OAuth with IBM Operational Decision Manager on Cloud

How To


Summary

OAuth is an open standard for access delegation. It is used as a way for Internet users to grant websites or applications access to information on other websites without giving them passwords. This mechanism permits the users to share information about their accounts with third-party applications or websites.

Objective

OAuth gives clients secure, delegated access to server resources on behalf of a resource owner. It specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials.

Designed to work with Hypertext Transfer Protocol (HTTP), OAuth allows access tokens to be issued to third-party clients by an authorization server, with the approval of the resource owner. The third party then uses the access tokens to access the protected resources hosted by the resource server.

OAuth support for ODM on Cloud is available from the December 2020 release (2020.12) onward. ODM on Cloud supports only the resource owner password credentials (ROPC) grant type for authenticating client application access to the cloud environment. It is not enabled by default. Contact ODM on Cloud Support to request its enablement. Requesting its enablement might require modifications to existing applications that rely on PD-S-SESSION-ID and PD-ID cookies, which are covered further in the Additional Information section at the end of this web page.

Steps

Using OAuth for REST calls

OAuth for REST calls can be used to run decision services, or use Rule Execution Server, Decision Center REST APIs or the user management REST API. To use OAuth for REST calls, follow these steps:

Task 1: Creating an OAuth token
1. Retrieve a CRSF token with your service credentials or user account.
Request:
curl -k -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"requested_lifetime": <time_in_seconds>}' 'https://<instance_id>.bpm.ibmcloud.com/instance/services/csrf_token' -v -u '<fid_name>:<fid_password>'
Response: 
{"expiration"<time_in_seconds>","csrf_token":"***"}


2. Create an authentication client and secret. This client is permanent and can be used to create authentication tokens (see step 3).
Request:
curl -k -X POST --header 'Authorization: Basic ***' --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'IBM-CSRF-TOKEN: <IBM_TOKEN>' -d '{"id_prefix":"<oauth_client_id_prefix>", "description": "<my_description>"}' https://<instance_id>.bpm.ibmcloud.com/instance/services/credentials/oauth_clients
 Response:
{"description":"*<my_description> ","creator":"<user_email>","client_id":" <oauth_client_id_prefix>.oac@<tenant_id>","client_secret":"***","creation_time":"YYYY-MM-DDTHH:MM:SS.MSSZ"}

3. Create an authentication token. This temporary token can be used in REST API calls. The refresh token can be used to generate another token.
Request:
curl -k -X POST -H 'content-type: application/x-www-form-urlencoded' -d grant_type=password -d client_id=<oauth_client_id> -d client_secret=<oauth_client_secret> -d username=<fid_name> -d password='<fid_password>' https://www.bpm.ibmcloud.com/mga/sps/oauth/oauth20/token
Response:
 {"access_token":"***","refresh_token":"***","scope":"","token_type":"bearer","expires_in":<time_in_seconds_specified_in_request>}
 
If the call is successful, the HTTP response code 201 is returned. If the client or service credentials are invalid, the call returns the HTTP response code BAD_REQUEST (400).

Task 2: Invoking REST APIs

Now, you can invoke Operational Decision Manager on Cloud REST APIs by using the generated tokens. The following examples use the Miniloan project in the Operational Decision Manager on Cloud getting started tutorial. All requests to REST APIs are described in the dedicated sections of the Operational Decision Manager on Cloud Knowledge Center.

Note that if the temporary access token is invalid or expired, the call returns the HTTP response code 302.

Decision Center REST API example
Request:
curl -k -X GET --header 'Accept: application/json' --header 'Authorization: Bearer <token_bearer>' 'https://<instance_id>.bpm.ibmcloud.com/odm/dev/decisioncenter-api/v1/decisionservices/<decision_service_id>'
Response: 

{"id":"<decision_service_id>","internalId":"brm.RuleProject:XX:XX","name":"Miniloan Service","buildMode":"DecisionEngine","advancedProperties":null}

Decision service execution REST API example
Request:
curl --location --request POST 'https://<instance_id>.bpm.ibmcloud.com/odm/dev/DecisionService/rest/Miniloan/1.0/Miniloan_ServiceRuleset' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Authorization: Bearer <token_bearer>' \
--data-raw '{"loan": {"duration": 240,"amount": 499999, "yearlyInterestRate": 0.05},"borrower": {"creditScore": 600, "name": "string", "yearlyIncome": 80000}}'
Response: 
{"__DecisionID__":"87d53382-fee5-49d7-993f-7c9e10f3c9390","loan":{"amount":499999,"duration":240,"yearlyInterestRate":0.05,"yearlyRepayment":39597,"approved":false,"messages":["Too big Debt-To-Income ratio"]}}

Rule Execution Server console REST API example
Request:
curl -k --header 'Authorization: Bearer ***' --request GET 'https://<instance_id>.bpm.ibmcloud.com/odm/dev/res/api/v1/ruleapps?count=true ' 
​

User management REST API example
Request:
curl -k -X GET --header 'Accept: application/json' --header 'Authorization: Bearer ***' --header 'IBM-CSRF-TOKEN: eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MDU2MzYxNDAsInN1YiI6InN1cmVzaGFwcGNsb3VkQGdtYWlsLmNvbSJ9.cdI9Hs3P1ARbxfHAJ64lxYiz70LoH_Y8zvBJbxt2TeE' 'https://<instance_id>.bpm.ibmcloud.com:443/instance/services/users?sort=user_id%3Aasc'
Response: 
{
"users": [
{
"email": "alex@acme.corp",
"user_id": "alex@acme.corp",
"base_dn": "ou=users,O=IBM,c=UK",
"given_name": "Alex",
"family_name": "Demo"
},
{
"email": "acme2oauth.fid@t1000",
       "user_id": "acme2oauth.fid @t1000",
       "base_dn": "ou=users,O=IBM,c=UK"
       }
],
"total_size": 2
}
 
Task 3: Managing an OAuth token’s lifecycle

Once a token is created (see task 1), do the following actions:

  •  Refresh token:  
    The tokens expire every 30 minutes. Applications must use this endpoint to refresh tokens.
Request:
curl -k -X POST -H 'content-type: application/x-www-form-urlencoded' -d grant_type=refresh_token -d refresh_token=<refresh_token> -d client_id=<oauth_client_id> -d client_secret=<oauth_client_secret> https://<instance_id>.bpm.ibmcloud.com/mga/sps/oauth/oauth20/token
Response:
{
 "access_token": "***",
 "refresh_token": "***",
 "scope": "",
 "token_type": "bearer",
 "expires_in": 179
 }
The request returns the HTTP BAD_REQUEST (400) response code if the refresh token is invalid or already used, or the client credentials are invalid, for example, because they are deleted.

  • Revoke token: 
    It's a good practice to revoke the tokens when the client application finishes processing. Use this endpoint to revoke the tokens, first the refresh token and then the access token.
Request:
curl -k -X POST -H 'content-type: application/x-www-form-urlencoded' -d client_id=<oauth_client_id> -d client_secret=<oauth_client_secret> -d token= <token_bearer> https://www.blueworkscloud.com/mga/sps/oauth/oauth20/revoke

Note: The response to this request is empty but the expected HTTP return code is 200.

Task 4: Adding an external Rule Execution Server by using OAuth to connect an Operational Decision Manager on Cloud Decision Center
OpenID Connect (OIDC) is an authentication framework that is built on top of the OAuth 2.0 protocol. Operational Decision Manager servers use OIDC to verify a user's identity with an OpenID Connect Provider, and to authorize access to the Operational Decision Manager applications and APIs.

Prerequisites

You need the following items to do this task:

  • An instance of Operational Decision Manager on Cloud Decision Center that is configured to use OAuth.
    You must have permission manager access to     Decision Center. Contact your cloud support representative to configure Decision Center to use OAuth.
  • An on-premises instance of Operational Decision Manager Rule Execution Server that is configured to use OAuth.
    You must have a user account or service     credentials for the on-premises instance.
Procedure
1. Create an OAuth client on the target Rule Execution Server (for an Operational Decision Manager on Cloud Rule Execution Server, follow tasks 1 and 2).
2. Create a server definition in the source Decision Center.
  1. Log in to the source Business console.
  2. Open the Administration tab.
  3. Open the Servers subtab.
  4. Create an oauth_providers.json configuration file by using the following JSON template and the client created in step 1:
{
  "providers": [
    {
  "name": "<name>",
  "grantType": "password",
  "authorizationURL": "https://www.bpm.ibmcloud.com/mga/sps/oauth/oauth20/authorize",
  "tokenURL": "https://www.bpm.ibmcloud.com/mga/sps/oauth/oauth20/token",
  "scope": "openapi",
  "clientId": "<client_id>",
  "clientSecret": "<client_secret>"
}
  ]
}

3. Import the configuration using the Import button  image-20201215115433-1 . 
 
 

Note: When a configuration file is imported, it replaces any previously existing definitions.

4. Create a new server definition by using the configuration:
  1. Click the Add button image-20201215115433-3.
  2. Specify the URL of the destination Rule Execution Server. Toggle the Use OpenID Connect button to on,  and select the correct configuration. The user name and password fields should correspond to the user or service credentials of the target Rule Execution Server:image-20201215115433-4
  3. Click Create.
5. Use the created server definition as a target server in the deployment configurations (see Deployment Configurations). When this server definition is used, Decision Center requests an OAuth token from the token provider by using the provided user name and password. Calls to the Rule Execution Server use the OAuth token when communicating with the server instead of using basic authentication.

image-20201215115433-2


Additional Information

Impact on existing applications
Once OAuth is enabled on your ODM on Cloud subscription, the PD-ID and PD-S-SESSION-ID cookies are no longer returned, which was previously the case for calls that use basic authentication. Whether you use basic authentication or OAuth, make sure that these cookies are not relied on for subsequent calls. Change your application code to use them only if they are provided by the initial call.

Limitations
There is a system-defined daily limit of several hundred concurrent valid grants (access and refresh token pairs). It is assumed that this limit is never reached. However, if you receive a message that the grant limit has been reached, check the grant creation design in your client applications or contact ODM on Cloud Support.

Document Location

Worldwide


[{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS7J8H","label":"IBM Operational Decision Manager on Cloud"},"ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

More support for:
IBM Operational Decision Manager on Cloud

Software version:
All Versions

Document number:
6373626

Modified date:
09 November 2022

UID

ibm16373626

Manage My Notification Subscriptions

Page Feedback