Using an OAuth REST-Based System Service
If your business process needs a system whose resources can be accessed using OAuth authentication, you can use the OAuth system service to allow delegated access to private resources.
OAuth is an open protocol that allows secure API authorization in a simple and standard method. Users can grant third-party access to their resources without sharing their passwords and can also grant limited access, in scope or duration.
OAuth's method of delegated access to private resources uses two sets of credentials: the process consumer (in our case, a BPEL process) identifies itself using its identifier and secret, while the resource owner is identified by an access token and token secret. Each set can be thought of as a username-password pair (one for the application and one for the end-user).
Here are some examples:
- •A social network can pull a user's address book from their e-mail provider to make it easy for the user to invite friends to that social network
- •A photo printing service can pull a user's photos from their photo hosting service to print selected photos
- •A financial aggregation service can pull a user's financial details from their banks and credit cards companies to show a combined view of that information
The OAuth system service provides authentication, access token storage for future use, and a way to do communication with the provider post authentication.
The supported OAuth service providers are listed in the PDD, as shown.
As a prerequisite, for each provider you want to access, you must register with the service provider and obtain a client identifier key and secret. These parameters are required for the Partner Role configuration in the PDD.
The OAuth system service is a client-side component of the OAuth protocol, and it abstracts OAuth tokens and request tokens (which are elements of the OAuth protocol) by a user id. Each operation takes a userId as one of the input elements to identify existing tokens. A userId can have one authorized OAuth token per OAuth provider at any given time.
Creating an OAuth Service
Use the following procedure to create an OAuth service:
- 1. In the Participants view of a process, create a new Partner Service Provider.
- 2. Select System Services from the Interfaces tree.
- 3. Select OAuth.
- 4. From the Partner Service Provider that you created, start with the getAccessToken operation to create an invoke activity. See the operation descriptions below.
The OAuth operations are as follows:
getAccessToken | Returns an OAuth access token for the given user. An access token is persisted after authorization is complete. |
getAuthorizationURL | Returns the authorization URL configured for the OAuth provider. Process Developer maintains this URL for each OAuth provider configuration listed in the PDD. This authorizationURL is invoked by the user (outside of Process Developer), and during this process, the OAuth provider lets the user know that Process Developer is trying to access the account and gets the user's content. Once the user approves the access, the provider returns a verifier string/code to the user. In the case of OAuth2.0, some providers require a redirect URL to which the request is redirected along with verifier string as a request parameter. For providers (usually OAuth2.0 providers) who require a redirect URL, it can be specified in the PDD along with other credentials. |
authorize | Takes the verifier string (given by the OAuth provider as a response to the authorizationURL) and authorizes with the OAuth provider. It also stores the OAuth access token returned by provider. This token is used further to access the protected resources on the provider. Once this token is generated, OAuth initial setup workflow is over. This is typically a one-time effort. However, it has to be done once the OAuth access token is expired (its lifetime is decided by OAuth provider). |
sendRequest | If the OAuth token for the given OAuth provider and user is present in Process Developer, this operation sends a request to access protected resources on OAuth provider system. This should be preceded by an authorize call, which generates and stores token in Process Developer. |
The following illustration shows a sample implementation for an OAuth service.
Specifying Deployment Details for an OAuth Service Provider
This topic discusses OAuth Invoke Handler Input Parameters.
When you create a PDD file for an OAuth provider, you must add the appropriate parameters for the Partner Role endpoint reference.
For a Partner role endpoint reference, select Oauth Service for the Invoke Handler.
Fill in the following configuration parameters for the service:
OAuth Provider | Select a provider from the list |
Key (required) | Represents the OAuth client ID, used to authorize a client. You must follow the procedure from the provider to obtain the key. For example, LinkedIn requires you to fill in a form online to receive a key and secret. |
Secret (required) | Secret text given by the OAuth provider. Used during authorization. |
Scope (optional) | Scope represent the subdomain of the OAuth provider that the OAuth client wants to access. Ex: https://docs.google.com/feeds/ is a scope value to access the Google docs feed. This is optional from the OAuth system service perspective, but can be mandatory based on the target OAuth provider. |
RedirectURL (optional) | This is usually required by OAuth2.0 providers. The response of authorization with a verifier string is redirected to this URL. Usually the verifier string is a query parameter (in the form url?code=verifierString). |
Adding a Custom Provider
It is possible to integrate with a custom OAuth provider (one that is not provided in the default list) and add it to the list in the PDD. To add a custom provider, create a configuration file (.oap file) in your project's deploy folder describing one or more endpoints for providers.
For example, to add the ACMEOAuthProvider:
<?xml version='1.0' encoding='UTF-8'?>
<oaconfig:oauthProviders xmlns:oaconfig="http://schemas.activebpel.org/OAuth/2011/08/01/aeoauthProviderConfig.xsd"
targetNamespace="http://schemas.activebpel.org/OAuth/2011/08/01/aeoauthProviderConfig.xsd">
<!-- name of the provider and version. Any text and oauth
version -->
<oaconfig:provider name="ACMEOAuthProvider"
oauthVersion="1.0">
<oaconfig:requestTokenEndpoint
verb="POST"> https://oauth.acme.com/ws/oauth/request_token
</oaconfig:requestTokenEndpoint>
<oaconfig:accessTokenEndpoint verb="POST">
https://oauth.acme.com/ws/oauth/access_token
</oaconfig:accessTokenEndpoint>
<oaconfig:authUrl verb="GET">
https://oauth.acme.com/ws/oauth/confirm_access?oauth_token=%s
</oaconfig:authUrl>
</oaconfig:provider>
</oaconfig:oauthProviders>
Note that the placeholders (%s) should be given in the URL templates so that the OAuth token is substituted by the OAuth system service.
Once the configuration file is part of project, it is detected, and the PDD's OAuth provider list is updated with the local configuration. Note that the extension of the file must be .oap. The file can hold any number of custom OAuth provider configurations.
A configuration file for out-of-the-box OAuth providers can be found in the Process Server catalog with the location hint project:/com.activee.rt.oauth.services/config/ae-oauth-providers.oap.
