Securing Outbound RESTful Service Invocations using OAuth2

This part of the documentation lists in what way Oracle Health Insurance applications provide support for OAuth2. A thorough understanding of OAuth standards is assumed as a prerequisite for further reading, i.e. this guide does not provide an introduction into OAuth.

OAuth2 use cases supported by Oracle Health Insurance applications

For Oracle Health Insurance applications the following OAuth2 related use cases are supported:

A RESTful service client in one Oracle Health Insurance application interacting with an OAuth2 secured RESTful service in another Oracle Health Insurance application. Examples of this are:
- Enrollment: Oracle Health Insurance Claims (the client) sending an enrollment request to Oracle Health Insurance Policies (the server).
- Data Replication: Oracle Health Insurance Authorizations (the client) retrieving member change events from Oracle Health Insurance Policies (the server).

These use cases are supported using the OAuth2 Client Credentials grant type (grant_type=client_credentials).

2. In Oracle Health Insurance applications customers can configure REST clients to call external RESTful services. The use of these REST clients and handling responses is scripted by customers in Groovy logic that is executed by Oracle Health Insurance applications. Oracle Health Insurance applications support all OAuth2 related configuration for these customer-configurable clients.

These use cases are also supported using the OAuth2 Client Credentials grant type (grant_type=client_credentials).

3. A lightweight UI that executes entirely inside a web browser. One example of this is an Oracle JET based Javascript UI as is under construction for Oracle Health Insurance applications. Another example is a custom client built by customers. Support for this use case is outlined in a separate chapter.

Configuration example: Data Replication - Oracle Health Insurance Authorizations retrieving

member change events from Oracle Health Insurance Policies

In this scenario Oracle Health Insurance Authorizations is configured to retrieve Member changes from Oracle Health Insurance Policies (Data Replication). The Oracle Health Insurance Policies RESTful services are "OAuth secured". The example makes use of the following components:

An OAuth2 Authorization Server, for example as provided by the Oracle Identity Cloud Service (IDCS) or Oracle Access Manager (OAM).
Oracle Health Insurance Policies is deployed in a separate WebLogic domain. The Oracle Health Insurance Policies RESTful services require the use of a valid OAuth bearer or access token.
Oracle Health Insurance Authorizations is also deployed in a separate WebLogic domain. The Oracle Health Insurance Authorizations REST clients that access Oracle Health Insurance Policies RESTful services are configured to call OAuth secured services.

1. Configure the OAuth2 Authorization Server and register client

applications

Setting up a specific OAuth2 Authorization Server is beyond the scope of this guide, see the OAuth2 Authorization Server’s product documentation for that.

Before a client application can request access to resources on a resource server, the client application must first register with the OAuth2 Authorization Service as OAuth client. For the Data Replication mechanism three clients are registered with the OAuth2 Authorization Server:

one used by the Authorizations application for retrieving change events and
another one used by the Authorizations application for retrieving entities and
a third one used by the Policies application to validate / introspect an access token

For the purpose of this example, the following OAuth Client applications are registered:

Attribute	Value
Person Events Client Id	Specify a client id that is unique within the context of the OAuth2 Authorization Server, e.g. "AuthsDataReplicationPersonEvents"
Person Events Client Secret	Specify a secret or choose to generate one, e.g. "2576ce9b-88e7-44bf-96f1-5cb5e5412323"
Person Entities Client Id	Specify a client id that is unique within the context of the OAuth2 Authorization Server, e.g. "AuthsDataReplicationPersonEntities"
Person Entities Client Secret	Specify a secret or choose to generate one, e.g. "0ab1fcb1-4f0f-4874-a08f-f7fdfe31d8a1"
Policies Access Token introspection Client Id	Specify a client id that is unique within the context of the OAuth2 Authorization Server, e.g. "PolDataReplicationTokenIntrospection". Note that some OAuth2 Authorization Servers require specific privileges to be set in order to allow introspection. Make sure that the introspection feature for this client application is enabled.
Policies Access Token introspection Secret	Specify a secret or choose to generate one, e.g. "3de4fgf1-6m7j-6543-a08f-f7fdfe31d8a1"

Attribute

Value

Person Events Client Id

Specify a client id that is unique within the context of the OAuth2 Authorization Server, e.g. "AuthsDataReplicationPersonEvents"

Person Events Client Secret

Specify a secret or choose to generate one, e.g. "2576ce9b-88e7-44bf-96f1-5cb5e5412323"

Person Entities Client Id

Specify a client id that is unique within the context of the OAuth2 Authorization Server, e.g. "AuthsDataReplicationPersonEntities"

Person Entities Client Secret

Specify a secret or choose to generate one, e.g. "0ab1fcb1-4f0f-4874-a08f-f7fdfe31d8a1"

Policies Access Token introspection Client Id

Specify a client id that is unique within the context of the OAuth2 Authorization Server, e.g. "PolDataReplicationTokenIntrospection".

Note that some OAuth2 Authorization Servers require specific privileges to be set in order to allow introspection. Make sure that the introspection feature for this client application is enabled.

Policies Access Token introspection Secret

Specify a secret or choose to generate one, e.g. "3de4fgf1-6m7j-6543-a08f-f7fdfe31d8a1"

Make sure that the Client Credentials grant type is supported.

2. Verify the OAuth2 Authorization Server is setup and successfully returns

an Access token

Base64 encode the clientId and clientSecret for use in a Basic Authentication Authorization header, i.e. Base64Encode(AuthsDataReplicationPersonEvents:2576ce9b-88e7-44bf-96f1-5cb5e5412323) and execute a curl command like the following to validate that the OAuth2 Authorization Server returns an access token:

curl -i -H 'Authorization: Basic QXV0aHNEYXRhUmVwbGljYXRpb25QZXJzb25FdmVudHM6MjU3NmNlOWItODhlNy00NGJmLTk2ZjEtNWNiNWU1NDEyMzIz' \
-H 'ContentType: x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'scope=urn:opc:idm:__myscopes__' \
--request POST 'https://host:port/oauth2/v1/token'

The OAuth2 server should respond with a JWT access token e.g.:

HTTP/1.1 200 OK
Date: Thu, 26 Oct 2017 18:04:15 GMT
Content-Type: application/json;charset=UTF-8
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubdomains;

{"access_token":"eyJhbGciOiJSUzI1NiIsInR ..."
,"token_type":"Bearer"
,"expires_in":3600
}

3. Configure Oracle Health Insurance Policies to secure its resources using OAuth

In case the Oracle Health Insurance Policies application receives requests that have an Authorization HTTP header containing an OAuth2 bearer token it needs to be able validate these tokens. In this example token introspection according to the RFC 7662 standard will be configured. In order to do that, set the following system properties for Oracle Health Insurance Policies:

ohi.oauth.token.validation.method=OAUTH2_ENDPOINT
ohi.oauth.token.introspection.endpoint.url=https://host:port/oauth2/v1/introspect
ohi.oauth.token.introspection.endpoint.client_id=PolDataReplicationTokenIntrospection

This instructs Oracle Health Insurance Policies to validate the token using the RFC 7662 compliant introspection endpoint that the OAuth2 Authorization Server exposes. The call to the introspection endpoint will be secured using Basic Authentication. The key to the Basic Authentication credentials is specified as value for the "ohi.oauth.token.introspection.endpoint.client_id" property. The password needs to be configured in the Oracle Health Insurance Policies credential store by sending a PUT request like the following to the "/api/credentials/credential/PolDataReplicationTokenIntrospection" resource:

{"username": "PolDataReplicationTokenIntrospection",
 "password": "3de4fgf1-6m7j-6543-a08f-f7fdfe31d8a1"
}

When the OAuth2 Authorization Server introspects the token it will not only verify that it is still valid (and not expired) but it will also return the user or subject (claim "sub" in the JWT token) for which the token was created. These subjects need to be provisioned as users in the Policies application and they need to be properly authorized, i.e. granted the correct access role.

4. Configure the REST Client in Oracle Health Insurance Authorizations so that it supports

calling OAuth-secured services

For Data Replication two REST requests are used: request DataReplicationPersonEvents to inquire about Person related change events in the source system (Oracle Health Insurance Policies in this case) and request DataReplicationPersonEntities to actually retrieve the changed Person entities data. The default security feature for these is Basic Authentication.

To specify that Oracle Health Insurance Authorizations calls these OAuth secured Oracle Health Insurance Policies resources with a proper OAuth access token set the following properties:

ohi.service.DataReplicationPersonEvents.client.authentication=OAuth
ohi.service.DataReplicationPersonEntities.client.authentication=OAuth

Next, configure the REST clients in Oracle Health Insurance Authorizations so that an OAuth Access Token can be obtained using the OAuth Client Credentials grant type. For the DataReplicationPersonEvents client POST a request with the following JSON payload to the Oracle Health Insurance Authorizations "/api/generic/oauthclientcredentialsgrantconfigurations" resource:

{ "restClientId": "DataReplicationPersonEvents",
  "clientId": "AuthsDataReplicationPersonEvents",
  "tokenURI": "https://host:port/oauth2/v1/token",
  "scope": "urn:opc:idm:__myscopes__"
}

For the DataReplicationPersonEvents client, set the client secret by PUTting the following payload to the Oracle Health Insurance application’s "/api/oauthclientconfigurations/{id}/setclientsecret" resource:

{ "clientSecret": "2576ce9b-88e7-44bf-96f1-5cb5e5412323"
}

with headers:

Accept = application/json
Content-Type = application/json

{id} is the ID of the DataReplicationPersonEvents client. It is possible to reset client secret for the DataReplicationPersonEvents client using the same URL and payload structure mentioned above.

And for the DataReplicationPersonEntities client POST a request with the following JSON payload to the Oracle Health Insurance Authorizations "/api/generic/oauthclientcredentialsgrantconfigurations" resource:

{ "restClientId": "DataReplicationPersonEntities",
  "clientId": "AuthsDataReplicationPersonEntities",
  "tokenURI": "https://host:port/oauth2/v1/token",
  "scope": "urn:opc:idm:__myscopes__"
}

For the DataReplicationPersonEntities client, set the client secret by PUTting the following payload to the Oracle Health Insurance application’s "/api/oauthclientconfigurations/{id}/setclientsecret" resource:

{ "clientSecret": "0ab1fcb1-4f0f-4874-a08f-f7fdfe31d8a1"
}

with headers:

Accept = application/json
Content-Type = application/json

{id} is the ID of the DataReplicationPersonEntities client. It is possible to reset client secret for the DataReplicationPersonEntities client using the same URL and payload structure mentioned above.

Note: The Oracle Health Insurance configuration is environment-specific, i.e. it needs to be repeated for separate instances of Oracle Health Insurance applications and per WebLogic domain.

Configuration example: setting up a Callout Rule in Oracle Health Insurance Policies

In this example a Callout Rule is defined in Oracle Health Insurance Policies for calling an OAuth secured RESTful service in an external application. For Callout Rules OAuth2 access tokens can be obtained using the Client Credentials grant type. Therefor, the configuration is very similar to the configuration that was outlined in the previous example.

1. Create the Callout Rule Dynamic Logic

Define the Callout Rule Dynamic Logic and save it in the application.

// Invoke the Callout request
Object response = initCallOut(WebTarget.class)
                 .path("url_to_the_service_endpoint")
                 .request()
                 .buildGet()
                 .invoke();

// Handle the response
if (response.getStatus() == 200 || response.getStatus() == 201) {
  def message = new groovy.json.JsonSlurper().parse(response.readEntity(String.class))
  policy.SOME_DYNAMIC_FIELD = message.SOME_FIELD_VALUE
} else {
  throw new RuntimeException("Unexpected response received")
}

For this example we assume the Dynamic Logic is saved with the uniquely identifying code 'SAMPLE_CALLOUT_RULE'.

2. OAuth2 Authorization Server Set Up

Register a client application with the OAuth2 Authorization Server and make sure it is set up to support the Client Credentials grant type. Verify that the OAuth2 Authorization Server returns an access token when its token endpoint is accessed for the configured client. For reference see steps 2 and 3 of the previous example.

3. Configure the REST Client in Oracle Health Insurance Policies so that it supports calling

OAuth-secured services

To specify that the resource that is invoked using the SAMPLE_CALLOUT_RULE Dynamic Logic is secured using OAuth set the following properties:

ohi.service.SAMPLE_CALLOUT_RULE.client.authentication=OAuth

Next, configure the REST client for this Callout rule so that an OAuth access token can be obtained using the OAuth Client Credentials grant type. For that purpose POST a request with the following JSON payload to the Oracle Health Insurance Policies "/api/generic/oauthclientcredentialsgrantconfigurations" resource:

{ "restClientId": "SAMPLE_CALLOUT_RULE",
  "clientId": "aConfiguredAndUniqueClientId",
  "expirationPeriod": "3600",
  "tokenURI": "https://host:port/oauth2/v1/token",
  "scope": "urn:opc:idm:__myscopes__"
}

For the REST client for this Callout rule, set the client secret by PUTting the following payload to the Oracle Health Insurance application’s "/api/oauthclientconfigurations/{id}/setclientsecret" resource:

{ "clientSecret": "aConfiguredClientSecret"
}

with headers:

Accept = application/json
Content-Type = application/json

where {id} is the ID of the REST client for this Callout rule. It is possible to reset client secret for the REST client for this Callout rule using the same URL and payload structure mentioned above.