Configuring SOACS for BPEL invocations of OAuth2 protected services

OAuth2 has become increasingly popular for authorizing access to web services.  Invoking these services is possible by applying Oracle Web Services Manager (OWSM) policies to the component in the composite.  OWSM actually acquires the OAuth Access Token and includes it in the HTTP request to the resource server for you automatically.  This blog describes the steps needed to setup and utilize OAuth2 protected services from a BPEL composite.

** NOTE **: There is a known issue where tokens do not get refreshed upon expiry.  This has been addressed in Bug 27362824.

The steps below are divided into two categories:

• Initial setup
• Per service setup

Initial Setup

After provisioning a SOACS instance, there are a couple of steps remaining in order to utilize OWSM policies.  These steps only need to be performed one time.

Create a Keystore for OWSM

OWSM requires a safe place to store keys (both private and public). In our case we’re not actively using any key pairs but OWSM will throw an error if the keystore has not been created. So we need to create an empty keystore with a specific path or stripe and name to avoid that error.

To create this keystore in the proper location use the Enterprise Manage (EM) console to perform the following steps:

1. Go to the WebLogic Domain → Security → Keystores page.
2. Click on “Create Stripe” button
3. Enter the name “owsm”
4. Click on the newly created “owsm” stripe
5. Click on the “Create Keystore” button.  You should see the following dialog box:
6. Fill in the Keystore name as “keystore”
7. Ensure the Protection type is “Policy”
8. Click on “OK”

Create a credentials map for OWSM

The OPSS Credential Store contains zero or more Credential Maps. And those Maps then contain zero or more “Keys”. A key in this context may be a username and password or it could be generic textual data. In our case we need to store an OAuth Client ID and Secret which are effectively a username and password.

As with the Keystore above, the necessary Credential Map is not created at provisioning time and so we need to manually create it ourselves.

To create the Credential Map open the EM console and perform the following steps:

1. Go to WebLogic Domain → Security → Credentials
2. Click on the “Create Map” button
3. Fill in the name “oracle.wsm.security”
4. Click "OK

Per Service Setup

The following steps have to be completed for each remote service invoked by a BPEL composite.

Store the OAuth Client ID and Secret in the OPSS Credential Store

In order for your composite to invoke the OAuth2 protected service, the application it represents should have been registered with the provider and a client ID and secret generated. This client ID and secret are used to retrieve the access token needed to invoke the service.  These credentials need to be stored in a secure location such that even if the SOA server is compromised, or an administrator was to “go rogue”, the password would still be safe. FMW provides a secure place for this called the OPSS Credential Store.

Next we need to store the actual username and password (again OAuth client ID and secret).

To do that:

Fill in the Key field with a name. We will use this name in the next step so note the value you choose.

1. Click on the map created in the previous step
2. Click on the “Create Key” button. The following dialog box will appear:
3. Ensure that the Type field has “Password” selected
4. Enter the OAuth Client ID in the “User Name” field
5. Enter the OAuth Client Secret in the “Password” field
6. Enter the same value in the “Confirm Password” field
7. Click “OK”

You should end up with something like the following:

Attach the correct OWSM Policies to the SOA Composite

In order for OWSM to be invoked you need to attach the correct policies to the component within the Composite.

The policies we need are:

• "oracle/oauth2_config_client_policy"
  This policy is used to configure the OAuth settings
• "oracle/http_oauth2_token_client_policy"
  This policy acquires the OAuth Access Token and attaches it to the request.

To attach these policies perform the following steps:

1. Open the EM console
2. Navigate to your SOA Composite
3. Go to the Dashboard tab (if you are not already there). You should see the following:
4. Click on the name of the reference that needs to use OAuth2, in this case “SOAPReference”
5. On the reference component page, click on the “Policies” tab.
6. Click on the “Attach/Detach” button
7. Go to the “Available Policies” pane
8. Locate the “oracle/oauth2_config_client_policy” and “oracle/http_oauth2_token_client_policy”. You can use the search feature to locate them more easily. Once they are listed in the pane, select each of them then click on the “Attach” button.

Once both policies are properly attached, you should see the following:

1. 9. Click “OK” to apply the changes.

At this point the policies have been attached but they have not yet been configured.

Configure the OWSM policies

OWSM needs to know (1) the URL of the OAuth server, and (2) where to get the Client ID and Secret. To provide this configuration information you must override the policy properties.

To do that, perform the following steps:

1. Navigate to the “Directly Attached Policies” pane on the "Policies" tab of the Reference page (shown below)
2. Click on the “oracle/oauth2_config_client_policy”
3. Click on the “Override Policy Configuration” button. You should see the following dialog:

1. 4. Fill in the “token.uri” property value
2. 5. Click “Apply”
3. 6. Click on “oracle/http_oauth2_token_client_policy”
4. 7. Click on the “Override Policy Configuration” button
5. 8. Use the name of the credential key created in an earlier step as the “oauth2.client.csf.key” value
6. 9. Set the “federated.client.token” to false (if it is not already set to that value)
7. 10. Set the “subject.precedence” property to false.
8. 11. Fill in the scope value as appropriate for your use case.
9.  

The dialog should appear as below:

1. 12. Click “Apply” to save the changes

Grant OWSM access to the Keystore for the Composite

The final step is to grant OWSM permission to use the credentials on behalf of the SOA Composite. This is also done via the EM console.

1. Go to the WebLogic Domain → Security → System Policies page
2. In the search field, search for Type of “Codebase”
3. Use the Name “Includes” option
4. Enter “wsm-agent-core” in the Name field
5. Press the button to search. The following entry should appear in the Policies pane:

1. 6. Click on the policy name to select it
2. 7. Click on the “Edit” button

You should then see the following dialog box containing the current permissions for this policy:

1. 8. Click the “Add” button to add a new permission
2. 

1. 9. Click on the “Select here to enter details for a new permission” check box
2. 10. In the The “Permission Class” field enter “oracle.wsm.security.WSIdentityPermission”
3. 11. In the “Resource Name” enter the SOA Composite name in the following format exactly, substituting your composite name for <composite_name>:“resource=<composite_name>,mapName=oracle.wsm.security”
4. 12. In the “Permission Action” enter “getKey”
5. 13. Click “OK” to create the permission

Summary

Although it takes some setting up, utilizing OWSM policies makes it possible to invoke OAuth2 protected services via configuration rather than having to build the authorization process into the composite.