CloudStreams 10.15 | webMethods CloudStreams Documentation | Administering webMethods CloudStreams | CloudStreams Configuration Options | The Administration Options | Setting the OAuth Tokens Options
 
Setting the OAuth Tokens Options
If you will be setting the Authentication Type field to OAuth on the Streaming Providers page (as described in Setting the Streaming Providers Options), you need to set the options here, on the OAuth Access Tokens page.
If OAuth will be used as an authentication mechanism, you must create an alias containing OAuth details. For example, when a Streaming Provider is created that will use OAuth, the provider details include an OAuth alias. When OAuth is chosen on the Streaming Providers page, an alias must be selected from a drop-down list of OAuth Token aliases that are currently defined. At run time, the OAuth alias is used to lookup parameters, such as Access Token, that are used to establish the connection with the provider.
OAuth is a scheme to limit the need for user credentials when operating on behalf of a resource owner. Instead of using the owner's credentials at run time, an Access Token is used. Prior to run time, the owner and user engage in a dance with a Resource Server and an Authorization Server to obtain an Access Token that will grant the user limited access to resources controlled by the owner. The precise steps in the dance vary with OAuth version, provider (Salesforce versus Twitter) and OAuth grant scheme (two-legged dance versus three-legged dance). Given this variation and the complexity of this process, CloudStreams assumes that the proper OAuth fields are obtained, and stores the tokens and other properties for use at run time.
Some of the information that is stored is considered to be sensitive and is stored securely, just as a password would be.
Currently, two OAuth versions are supported, v1.0a and v2.0. The parameters that are stored with an alias are different in the two versions, though there is also significant overlap.
*To set the CloudStreams > Administration > OAuth Tokens options
1. In Integration Server Administrator, select Solutions > CloudStreams > Administration > OAuth Tokens.
2. Click Add New Token, complete the following fields, and click Save.
Option
Description
Name
A unique string to identify a collection of alias token parameters.
Provider
Identifies the OAuth provider (such as Salesforce or Twitter).
OAuth Version
Select the OAuth version, v1.0a or v2.0.
Consumer ID
The 'Consumer Key' issued by the Service Provider and used by the consumer to identify itself to the Service Provider. In OAuth 2.0, this is a 'client identifier' issued to the client to identify itself to the authorization server. Also referred to as the “Client ID”.
Consumer Secret
In OAuth 2.0, this is an optional field. This is a secret used by the Consumer to establish ownership of the "Consumer Key" and is a secret matching to the "client identifier". It is also referred to as the "Client Secret".
Access Token
The token used for authentication, instead of other credentials. This token is issued by the Authorization Server. The process for obtaining a token varies with version, vendor and OAuth grant type.
For OAuth 2.0, CloudStreams will use the keystore and truststore specified in the CloudStreams > Administration > General tab when making a connection to the third-party OAuth 2.0-based service provider to refresh the access token. The refresh URL is almost always SSL-based, so the truststore specified in CloudStreams will be used during the SSL handshake to verify the provider certificate. If the provider requires two-way SSL authentication, then the keystore specified in CloudStreams will be used to provide the client certificates. For details about the keystore and truststore specified in CloudStreams, see Setting the General Options.
If a truststore is not specified in the CloudStreams > Administration > General tab, CloudStreams will use the default truststore for the jvm (cacerts). This might be a problem if you have defined the default truststore to only contain specific certificates, because if that alias is defined, the well-known certificates will not be included when defining the trust. In this case, make certain the truststore alias keystore includes the certs necessary to trust the URLs defined in this field too.
Access Token Secret
Issued with the v1.0a Access Token only. A secret used by the Consumer to establish ownership of a given 'Access Token'. Secrets are used to sign the requests.
Instance URL
This is an optional field and is used to specify a runtime host, if applicable. This may be required in some back ends like Salesforce.
Refresh Access Token
Option to refresh the 'Access Token'. OAuth 2.0 access tokens typically have a very short lifetime. When an access token expires, the OAuth profile does not automatically refresh the expired access token. Select this option if you want an expired access token to be refreshed automatically. If you select this option, you must also specify Refresh Token and Refresh URL.
The access token is refreshed whenever the session expires. Session expiration is handled according to the setting of the Session Management property in your connection. Note that if Session Management is set to none, then you must manually modify the access token in the OAuth alias. (The Refresh Access Token option will not be applicable in this case.)
If you want to refresh the 'Access Token' automatically, set Session Management to either 'fixed' or 'idle'. The Timeout value should be based on the backend settings.
Refresh Token
Issued with the OAuth v2.0 access token only. Required only if Refresh Access Token is enabled.
A token used by the client to obtain a new access token without having to involve the resource owner.
Refresh URL
Available only if Refresh Access Token is selected.
The provider specific URL to refresh an 'Access Token'. This is required when 'Refresh Access Token' is enabled.
Refresh URL Request
Options for sending the parameters, for example, refresh_token, grant_type, client_id, and client_secret required by an access token refresh (HTTP POST) request.
The available options are:
*URL Query String - The refresh request parameters, for example, refresh_token, grant_type, and so on, and their values are sent as query strings in the URL of the POST request.
Example:
www.examplebackend.com/o/oauth2/token?grant_type=
refresh_token&client_id=842428530070-pubfebfgfqkgj6t54m4ns6
&client_secret=4adQT95cAtUxWINbDxGP9SJ4&refresh_token=
1%2Fn072P4BXpuNObjCLUtiZTc4fMH6YersmxBIv8QN3bhw
*Body Query String - The refresh request parameters, for example, refresh_token, grant_type, and so on, and their values are sent as query strings in the body of the POST request.
Example:
POST /o/oauth2/token HTTP/1.1
Host: accounts.backend.com
Content-length: 163
content-type: application/x-www-form-urlencoded

client_secret4adQT95cAtUxWINbDxGP9SJ4&grant_type
=refresh_token&refresh_token=
1%2Fn072P4BXpuNObjCLUtiZTc4fMH6YersmxBIv8QN3bhw&
client_id=407408718192
*Custom ESB Service - Use this option if the back end requires some refresh requests in a custom format, for example, requests which need more parameters than the ones specified by OAuth v2.0, or the back end uses some custom way of organizing parameters, or expects some other HTTP method request (other than POST). If you select this option, you must specify the name of your custom service in the ‘Service Name’ field.
Service Name
User implemented service for refreshing the ‘Access Token’. This is required when the Refresh URL Request is specified as Custom ESB Service. This service should strictly conform to the following specification:
-wm.cloudstreams.service.common.lookup.specs:
oauthTokenRefreshServiceSpec