Cloud API Management OAuth2 Backend Authentication Custom Policy Configuration Values

Configuration Values

Applicable to Local Edition only

The scope parameter is supported only in Boomi Cloud API Management – Local Edition 6.3.0 and later. It is not supported in Boomi Cloud API Management.

The following configuration values can be defined while configuring the Cloud API Management OAuth2 Backend Authentication Policy on the Call Transformation page:

Field name	Type	Field Value	Required/Optional	Description
Processing Adapter	String	`CAM_OAuth2BackendAuthentication_Service`	Required	Adapter used to secure target requests using OAuth access tokens obtained from customer-provided OAuth token endpoint details.
Perform Pre-processing	Boolean	Enabled	Required	When enabled, the policy checks the cache for an existing access token and requests a new one from the configured token endpoint if none is found.
Data to make available for pre-processing (PreInput Value)	Map	—	Required	Specifies the input data made available for pre-processing.
	Integer Range: 1 - Infinite	`defaultTtl`	Required	Provide the cache TTL for the access token. If the `expires_in` parameter is not received in the token response, or the introspect request is not provided, then set it to the TTL of the token object stored in the cache. No default value.
	String Range: 1 - Infinite	`clientId`	Conditionally required	Provide the `clientId` in the area-encrypted value. An exception is thrown if `grant_type` is `client_credentials`, or a `password` with `clientCredentials` is used, and the `clientId` is not provided. No default value.
	Integer Range: 1 - Infinite	`readTimeout`	Required	Provide the `readTimeout` value in seconds to connect to the OAuth token endpoint. The `readTimeout + connectTimeout` of the token endpoint should be less than the `connectTimeout` of the target request, and the total value of the token endpoint should not exceed the `connectTimeout` of the target request. No default value.
	Integer Range: 1 - Infinite	`connectTimeout`	Required	Provide the `connectTimeout` value in seconds to connect to the OAuth token endpoint. No default value.
	String	`tokenClientCredentialsLocation`	Optional	The default value is header, and the other option is body. Any other string will give an exception. Note: For the body, `clientId` and `clientSecret` values are included within the body in URL-encoded format. For the header, `clientId` and `clientSecret` are included within the header as Authorization Basic `base64(clientId:clientSecret)` format.
	String	`clientSecret`	Conditionally required	Provide the `clientSecret` in the area encrypted value. An exception is thrown if `grant_type` is `client_credentials`, or a password with `clientCredentials` is used, and the `secret` is not provided.
	String	`tokenRequestURI`	Required	Provide the complete URI to hit the token request. No default value.
	String	`grantType`	Optional	Provide the `client_credentials` or `password` value. The default value is `client_credentials` Allowed values: `client_credentials` and `password`
	String	`tokenType`	Optional	Allowed value: `Bearer`. If this value is not provided, then this value defaults to `Bearer`.
	Boolean	`passwordIncludeClientCredentials`	Conditionally required	Set value to `true` when `grant_type` is configured as `password`. Set value to `true` or `false` to determine whether `clientid` and `secret` should be included in the request. If it is marked `true`, but `clientid` or `secret` are not provided, then an error will be thrown. The default is `false`.
	String	`username`	Conditionally required	Provide the username in the area encrypted value. An exception will be thrown if the password `grant_type` is used and the username is not provided.
	String	`password`	Conditionally required	Provide the password in the area encrypted value. An exception will be thrown if the password `grant_type` is used and the password is not provided.
	String (space-delimited)	`scope`	Optional	When requesting access tokens through the authentication service, you can optionally include the `scope` parameter to restrict or specify the exact permissions granted to the token. Available in Local Edition 6.3.0 and later only; not supported in Cloud API Management. Provide a space-delimited list of scopes to request from the token endpoint. Scope values are case-sensitive. The policy trims trailing spaces from the `scope` value and URL-encodes it before sending it to the token endpoint. No other parsing or validation is performed. Requested scopes must be a subset of the scopes configured on your OAuth2 server. An unassigned or invalid scope is rejected by the token endpoint (`invalid_scope`), and that failure is propagated to the API caller. `scope` is always sent in the token request body, per the OAuth2 spec (RFC 6749). If the `scope` is not provided, no `scope` parameter is sent in the token endpoint request. There is no default value.
Perform Post-processing	Boolean	Enabled	Required	Important: You must enable this option to perform post-processing. This is mandatorily required if pre-process is enabled.
Data to make available for post-processing (PostInput Value)	Map	—	Optional	Specifies the input data made available for post-processing.
	String	`clientId`	Optional	Provide the `clientId` in area encrypted value. No default value.
	Integer Range: 1 - Infinite	`readTimeout`	Optional	Provide the `readTimeout` value in seconds to connect to the OAuth introspect endpoint. No default value.
	Integer Range: 1 - Infinite	`connectTimeout`	Optional	Provide the `connectTimeout` value in seconds to connect to the OAuth introspect endpoint. No default value.
	String	`introspectClientCredentialsLocation`	Optional	In the introspection endpoint request, provide the location where the `clientId` and `secret` are passed. The default value is header, and the other option is body. Any other option will give an exception. Note: For the body option, provide `clientId` and `clientSecret` values within the body in URL-encoded format. For the header option, provide `clientId` and `clientSecret` values within the header as Authorization Basic `base64(clientId:clientSecret)` format.
	String	`clientSecret`	Optional	Provide the `clientSecret` in area encrypted value. No default value.
	String	`introspectRequestURI`	Optional	Provide the complete URI to hit the token request. No default value.

Generating Area-encrypted Values using Java or PHP

Some PreInput Value fields, such as clientId, clientSecret, username, and password, require values encrypted using our area encryption. We provide you with a decryptedAreaKey specific to your area. Use that key to encrypt each credential before configuring the CAM_OAuth2BackendAuthentication_Service policy on the Call Transformations page.

You can encrypt your credentials using one of the following methods:

Option 1: Java

Procedure

Run the following Java command for each credential you want to encrypt:
```
java -jar area-encrypt-1.0.0.jar <decryptedAreaKey> <Data>
```
Where:
- decryptedAreaKey: The area key will be provided by us.
- Data: The plain-text credential (your confidential data) to encrypt (for example, your client ID).
The command returns output in the following format:
```
Decrypted Area Key provided: <decryptedAreaKey>
Data provided: <Data>
Encrypted Data: <encrypted-string>
```
Copy the <encrypted-string> value and paste it into the relevant PreInput Value field.
Repeat this step for each of clientId, clientSecret, username, and password.

Option 2: PHP

Procedure

Run the following PHP command for each credential you want to encrypt. This requires PHP with the mcrypt extension installed on your machine. :
```
php encrypt_key_v3.php <decryptedAreaKey> <Data>
```
The command returns an encrypted string.
Copy the <encrypted-string> value and paste it into the relevant PreInput Value field.
Repeat this step for each of clientId, clientSecret, username, and password.

Example configurations

The following examples show how to configure the PreInput Value field on the Call Transformations page. Replace the placeholder <area-encrypted> values with the encrypted strings generated in the Generating Area-encrypted Values using Java or PHP section.

note

Do not add the scope parameter to the examples below - "Example: client_credentials grant type" and "Example: password grant type." These examples work the same way in both Cloud API Management and Boomi Cloud API Management - Local Edition.

Example: client_credentials grant type

grantType:client_credentials
tokenRequestURI:https://auth.example.com/oauth2/token
clientId:<area-encrypted-client-id>
clientSecret:<area-encrypted-client-secret>
tokenType:Bearer
tokenClientCredentialsLocation:header
defaultTtl:3600
connectTimeout:10
readTimeout:30

Example: password grant type

grantType:password
tokenRequestURI:https://auth.example.com/oauth2/token
clientId:<area-encrypted-client-id>
clientSecret:<area-encrypted-client-secret>
username:<area-encrypted-username>
password:<area-encrypted-password>
passwordIncludeClientCredentials:true
tokenClientCredentialsLocation:header
tokenType:Bearer
defaultTtl:3600
connectTimeout:10
readTimeout:30

Configuration Steps

You can configure this policy using either of the following UIs: