Authentication

What is OAuth?

The OAuth 2 specification is a flexible authorization framework that describes different methods in which a client application can acquire an access token. Once acquired, you (as a developer) can use such token to authenticate a request to an API endpoint. The Access Token represents the user’s authorization for the client application to access their data on their behalf.

This section will outline how to use OAuth with Fusioo. For more information about OAuth feel free to also take a look at the official OAuth spec.

Fusioo supports three different authentication flows, depending on the type of application you are building:

1. Authorization Code Grant flow - This flow is the most common way of authentication for web applications.
2. Implicit Grant flow - You should use this flow if you are building a browser only applications that is not utilizing a backend server.
3. Password Grant flow - You should use this flow if your client application is intended for internal use only. The user has to share his email and password with your application.
4. Credentials Grant flow - This flow is suitable for machine-to-machine authentication. It is intended for internal use only.

Authorization Code Grant flow

To get started, you need to register an application.

1. In your application the user should be redirected to https://connect.fusioo.com/oauth/authorize with the following query string parameters:

   Parameter	Description
   response_type	required - Should be set to code
   redirect_uri	required - The URI where the user will be redirected on success or error. This must match the Redirect URI specified in your application settings.
   client_id	required - The Client ID uniquely identifies the application making the request.
   state	optional - An arbitrary value used by the application to maintain state between the request and callback. The parameter should be used for preventing cross-site request forgery.

   Full URL example: https://connect.fusioo.com/oauth/authorize?response_type=code&redirect_uri=YOUR_URL&client_id=YOUR_APPLICATION_ID&state=RANDOM_STRING

2. If the user, denies access, the application will not be authorized to access the user's account. The OAuth flow will then redirect the user back to your application, using the redirect_uri parameter. An additional descriptive parameter (error_description) will be added to let you know that the user denied access.

   http://YOUR_URL?error=access_denied&error_description=Access+denied

3. If the user clicks Allow, the user will be redirected back to your application. A code will be passed along as a query parameter.

   Parameter	Description
   code	The code which needs to be exchanged for a token via the token exchange endpoint.
   state	The state parameter that was sent with the authorizing request, if any.

4. Your application can now use the Token Exchange Endpoint for an Access Token (which usually lasts an hour) and a Refresh Token (which is used to fetch a new Access Token when the current one expires)

   Simply make a POST to https://connect.fusioo.com/oauth/token passing the following parameters:

   Parameter	Description
   grant_type	required - Should be set to authorization_code
   code	required - The code received in the previous response.
   redirect_uri	required - The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
   client_id	required - The Client ID uniquely identifies the application making the request.
   client_secret	required - The Client Secret belonging to your application, found in the integrations page.

5. You will receive an Access Token which you can use to make requests to the API.

   Parameter	Description
   access_token	The token to use in future requests against the API
   expires_in	The number of seconds the access token is valid, usually 3600 (one hour)
   token_type	The type of token, in this case, bearer
   refresh_token	The refresh token is used to get a new access token without needing to redirect or reauthorize the user

6. Once the Access Token expires, the application can exchange the Refresh Token received for a new Access Token. This action will take place without redirecting the user. You should send a POST request to https://connect.fusioo.com/oauth/token passing the following parameters:

   Parameter	Description
   grant_type	required - Should be set to refresh_token
   refresh_token	required - The Refresh Token received with the previous Access Token request.
   client_id	required - The Client ID uniquely identifies the application making the request.
   client_secret	required - The Client Secret belonging to your application, found in the integrations page.

7. You will receive a new Access Token which can be used to make requests to the API.

   Parameter	Description
   access_token	The new access token to use in future requests against the API
   expires_in	The number of seconds the access token is valid, usually 3600 (one hour)
   token_type	The type of token, in this case, bearer
   refresh_token	The new refresh token, which is used to get a new access token without the need to redirect or reauthorize the user

Implicit Grant flow

The implicit grant is similar to the Authorization Code Grant flow, with some differences:

• It is intended to be used for user-agent-based clients (e.g. single page web apps) that cannot protect the client secret because all of the application code and storage is easily accessible.
• Instead of the authorization server returning an authorization code which is exchanged for an access token, the authorization server returns an access token.
• For the Implicit Grant flow, the response_type parameter must be set to token

The flow is performed in 2 steps:

1. Redirect the user to https://connect.fusioo.com/oauth/authorize with the following query string parameters:

   Parameter	Description
   response_type	required - Should be set to token
   redirect_uri	required - The URI to redirect to on success or error. This must match the Redirect URL specified in the application settings.
   client_id	required - The Client ID uniquely identifies the application making the request.
   state	optional - An arbitrary value used by the application to maintain state between the request and callback. The parameter should be used for preventing cross-site request forgery.

   The client secret is not included here. Most of the use cases for implicit grants are mobile or desktop apps, where the secret cannot be protected.

   Full URL example: https://connect.fusioo.com/oauth/authorize?response_type=token&redirect_uri=YOUR_URL&client_id=YOUR_APPLICATION_ID&state=RANDOM_STRING

2. When the user authorizes the application, you will receive a redirect back from the authorization endpoint with the following parameters embedded in the fragment portion (the part following the #) of the URL:

   Parameter	Description
   access_token	This token can then be used to access the API, in this case typically using CORS.
   token_type	Will be set to bearer
   expires_in	The number of seconds the token is valid, usually 3600 (one hour)
   state	The state parameter that was sent with the authorizing request.

   Full URL example: https://YOUR_URL#access_token=ACCESS_TOKEN&token_type=bearer&expires_in=3600&state=RANDOM_STRING

Password Grant flow

This flow is suitable for applications that can ask end-users for their email and password. The user credentials are used in a single request and are exchanged for an access token.

In this flow there are no redirects to the Fusioo authorization page. The user provides the email and password directly to the application.

To use the password grant type, simply make a POST to https://connect.fusioo.com/oauth/token with the following body parameters to the authorization server:

In the response, you will receive an Access Token which you can use to make calls to the API.

Credentials Grant flow

This flow is suitable for internal API applications which will be integrated with other applications (machine-to-machine authentication). The Client Id and Client Secret are used as credentials.

To use the credentials grant type, simply make a POST to https://connect.fusioo.com/oauth/token with the following body parameters to the authorization server:

In the response, you will receive an Access Token (valid for 10 years) which you can use to make calls to the API.