OAuth grant flows

While OAuth 2.0 defines several different grant types, Hybrid Data Pipeline currently supports the following grant flows.

The authorization code grant type is the most commonly used because it is optimized for server-side applications, where source code is not publicly exposed, and Client Secret confidentiality can be maintained. This is a redirection-based flow, which means that the application must be capable of interacting with the user-agent (i.e. the user's web browser) and receiving API authorization codes that are routed through the user-agent. Now we will describe the authorization code flow:

Step 1: Authorization Code Link

First, the user is given an authorization code link that looks like the following:

Here is an explanation of the link components:

When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access to their account. If the user chooses to allow, the grant flow carries on with the next step. If the user chooses to deny, an error message will be displayed, specifying that “User denied OAuth access”.

Step 3: Application Receives Authorization Code

If the user clicks "Authorize Application", the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code. The redirect would look something like this:

Step 4: Application Requests Access Token

The application requests an access token from the API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint. The parameters are sent in request body as form url encoded. The following is an example of a POST request to Hybrid Data Pipeline's token endpoint.

Step 5: Application Receives Access Token

If the authorization is valid, the API will send a response containing the access token and a refresh token to the application. The entire response will look something like this:

The application is now authorized. It may use the token to access the user's account via the API, limited to the scope of access, until the token expires or is revoked. A refresh token can be used to request a new access token if the original access token has expired.

With the resource owner password credentials grant type, the user provides their service credentials (username and password) directly to the application. The application uses the /oauth2/token endpoint to obtain an access token from the service.

The following details are required in this grant type:

This grant type should only be used with trusted applications since user credentials need to be shared with the client application.

Resource Owner Password Credentials Flow

After the user gives their credentials to the application, the application will then request an access token from the authorization server. To generate the proper OAuth2 token, you need to pass the payload as "application/x-www-form-urlencoded". The POST request must include the user credentials in the request body. The authorization should be set to No Auth before posting the payload.

After the user credentials provided are authenticated, the authorization server returns an access token to the application. Now the application is authorized.