Title: OAuth 2.0 in the HTTP Connector

Introduction:

All grant types for OAuth 2.0 will require the client ID and client secret since it is used to construct the POST request as an x-www-form-urlencoded?body. Scope and additional authorization/access token parameters are specified by the endpoint. We assume you have set up the callback URL or redirect URI in the endpoint correctly. Some important things to know first if you are using the native OAuth 2.0 implementation in the HTTP connection,

The platform makes the authorization token and access token requests for grant type authorization code and resource owner credentials, not the selected runtime since the platform will now handle the refreshing and storage of the token. For the grant type client credential and JWT bearer, the runtime makes the calls. You will be able to use a proxy on the local runtime to view that request if you want to

A proxy cannot be used to view the OAuth 2.0 requests through the atom since the platform handles it for the grant types mentioned above

The access token (or any part of the token response) cannot be retrieved from within the process, the HTTP connector automatically sets those

Response to the Access Token request:

Access Token Response:

The response with an access token should contain the following properties:

? access_token (required) The access token string as issued by the authorization server.

? token_type (required) The type of token this is, typically just the string "Bearer”.

? expires_in (recommended) If the access token expires, the server should reply with the duration of time the access token is granted for.

? refresh_token (optional) If the access token will expire, then it is useful to return a refresh token which applications can use to obtain another access token. However, tokens issued with the implicit grant cannot be issued a refresh token.

? scope (optional) If the scope the user granted is identical to the scope the app requested, this parameter is optional. If the granted scope is different from the requested scope, such as if the user modified the scope, then this parameter is required.

Grant Types:

1. Authorization Code

2. Resource Owner Credentials

3. Client Credentials

Authorization Code :

1. When you click generate in Boomi (the application) on the 'Access Token' button, a GET request is sent to the Authorization Token URL of the endpoint/API (the resource)
2. The user has to log in and allow the application access
3. Once that is successful, an authorization code is sent back to Boomi (via the callback URL) to be used
4. The HTTP connector makes an access token request (along with client ID/secret) to the?Access Token URL
5. If successful (the authorization code is correct), an access token, expiration, and refresh token (if applicable) is sent back and stored
6. Subsequent calls will use "<<token_type>> <<access_token>>" from the token response in the Authorization header and are sent to the API endpoint?made from the?URL?(in the connection) and resource path (in the operation)

All of the above is done automatically behind the scenes after you enter your credentials the first time you hit generate. The HTTP connector will try its best to refresh the token by making subsequent refresh token requests to the?Access Token URL?and storing the new access token automatically.?

Resource Owner Credentials:

1. When you click generate, a username and password window will popup asking for credentials
2. This is not stored anywhere and is sent in a request (along with client ID/secret)?to the?Access Token URL
3. If successful, an access token, expiration, and refresh token (if applicable) is sent back and stored
4. Subsequent calls will use "<<token_type>> <<access_token>>" from the token response in the Authorization header?and are sent to the API endpoint?made from the?URL?(in the connection) and resource path (in the operation)

The HTTP connector will try its best to refresh the token by making subsequent refresh token requests to the?Access Token URL?and store the new access token automatically. If there is no refresh token, you have to get a new access token. If there is a method to keep the access alive longer through continued use, that is entirely up to the endpoint to let you know how long an access token is kept alive and how it can be kept further alive.??

Client Credentials:

1. When you run the process, a request is made to the?Access Token URL
2. An access token is used for that process run
3. Subsequent calls will use "<<token_type>> <<access_token>>" from the token response in the Authorization header and are sent to the API endpoint?made from the?URL?(in the Connector) and Resource Path (in the Operation)

There is no refresh token so you can't refresh the current access token. A new access token should be acquired each time or until it expires.?

Authorization request:

• The endpoint requires another HTTP method other than GET to get the authorization code request, e.g. POST
• Having additional headers in authorization code or access/refresh token requests, e.g. an additional Authorization header for?basic auth
• Access and refresh token request

A standard OAuth 2.0 token request would send a POST request with an x-www-form-urlencoded?body like this,

POST /token HTTP/1.1 
Host: server.example.com  
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&client_id=balhablah        

... so anything not similar to that wouldn't work in Boomi e.g.,

• Having additional headers in authorization code or access/refresh token requests, e.g. an additional Authorization header for?basic auth
• The body is not a?x-www-form-urlencoded?body e.g. the endpoint requires the body to be JSON or XML
• The endpoint expects the parameters (like client ID, secret, etc)?to be sent as a header instead of a body or in addition to the body
• The refresh token lives the same or a shorter amount of time than the access token, the HTTP connector will try to send a refresh token request, but it's too late the refresh token is invalid now. You'll have to generate your access/refresh token again if your access token has expired by then
• The endpoint's refresh token request?uses another grant type other than "grant_type=refresh_token" in the x-www-form-urlencoded body
• Having a different access token URL than the?refresh token URL,?since the HTTP connector will send the refresh token request to the access token URL

Access token response:

The HTTP connector expects an access token response to follow the standards so it should look something like this,

{
    "token_type": "Bearer",
    "access_token": "T7GR1ecMM513sqFdNGa10RzMWBM6",
    "expires_in": "1799",
?   "other_elements": "test"
}        

If there are extra elements that's acceptable. Things that will not work,

• Getting a token response is in another data format other than?JSON format, e.g. XML
• Getting a nonstandard token_type value i.e. the token_type value should be the standard "Bearer" not something else like "myToken" since the value of token_type is used to generate the Authorization header
• The response uses element names other than the specified "token_type", "access_token", "expires_in", "refresh_token", and "scope". The access_token element should be named "access_token" and not something like "accessToken". For optional elements like refresh_token and scope, it might not cause a problem for authentication, but if the endpoint needs them?to be used, there might be an issue with refreshing, etc down the road since Boomi wouldn't recognize something other than "refresh_token" and "scope" if the endpoint decided to use another equivalent name (like "refresh token")?and expected them to be used in the same way

If the endpoint has something like the above, the HTTP connector will not be able to make OAuth 2.0 requests to the resource. You will need to make more manual calls and construct the OAuth 2.0 requests according to the endpoint's documentation. Again, most of the things mentioned here are from an endpoint not following the standard OAuth 2.0 specifications like having different access token and refresh token endpoints. The additional Authorization header (and the refresh token life) for basic auth is currently not supported, but is an option according to specifications. For various strategies to use an endpoint's OAuth 2.0 and ways to store the access and refresh the token yourself, please view making Manual OAuth 2.0 Calls.