# Account OAuth Flow

## Account OAuth Flow

***

This is a standard flow for getting access to a remote account. To enable Google and Office 365 OAuth flow for production, please see the following instructions [Office365 OAuth Setup](https://docs.aurinko.io/authentication/office-365-oauth-setup) and [Google OAuth Setup](https://docs.aurinko.io/authentication/google-oauth-setup).

This flow uses user-delegated authorization and produces an Aurinko account and an access token.

Some key terms you'll encounter while integrating with Aurinko's OAuth2 flow:

#### **Final Callback URL (returnUrl)**

The final callback URL, also known as <mark style="color:red;">`returnUrl`</mark>, is the URL provided by your application and specified when calling the <mark style="color:red;">`/authorize`</mark> API method within Aurinko. This is where Aurinko will redirect the user after successful authorization. It's crucial to register this URL within the Aurinko settings for your application.

#### Intermediate Redirect URL

The intermediate redirect URL is a temporary landing page used during the OAuth2 flow. By default, Aurinko uses <mark style="color:red;">`https://api.aurinko.io/v1/auth/callback`</mark> for this purpose. However, developers have the flexibility to customize this URL within the Aurinko settings for their application.

The following diagram shows a custom OAuth flow with your own intermediate redirect URL.&#x20;

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FXza4jMOfFbd7cR60UbWt%2Fimage.png?alt=media&#x26;token=1c642f17-a7bb-4677-9d07-8f7019faa8ad" alt=""><figcaption></figcaption></figure>

We recommend this flow because Google app registrations allow only authorized redirect URIs under a domain you own so Aurinko's default Redirect URI <mark style="color:red;">`https://api.aurinko.io/v1/auth/callback`</mark> won't work for you in production.

Create a dedicated **intermediate redirect** page that will be redirecting all callback requests to Aurinko's <mark style="color:red;">`https://api.aurinko.io/v1/auth/callback`</mark> with the URL parameters <mark style="color:red;">`state`</mark>, <mark style="color:red;">`code`</mark>, and <mark style="color:red;">`scope`</mark>. \
\
Specify the page url in the Aurinko app settings (override the default url).

<div align="left" data-full-width="true"><figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FLazr82BfU4D4nOYNkLCt%2Fimage.png?alt=media&#x26;token=f34dff2e-0d5a-434b-abec-6f22fd197079" alt=""><figcaption></figcaption></figure></div>

1. #### [Authorization request](#user-content-fn-1)[^1]

From your application, redirect users to <mark style="color:red;">`https://api.aurinko.io/v1/auth/authorize`</mark>, with the query parameters detailed in [/auth/authorize](https://apirefs.aurinko.io/#tag/Auth/operation/authorize). You'll need to set the <mark style="color:red;">`responseType=code`</mark>.

{% hint style="info" %}
Note: <mark style="color:red;">`responseType=token`</mark> for client-side flows (corresponding to the OAuth's implicit grant) is supported but is not recommended!
{% endhint %}

You'll also need to determine what permissions your application will request from users, and update the <mark style="color:red;">`scopes`</mark> query parameter accordingly. Aurinko provides granular authentication scopes that empower users with control over what level of access your application has to their data. See supported [Authentication scopes](https://docs.aurinko.io/authentication/authentication-scopes) for details.

Here's an example of what this URL might look like once you've included all the correct query parameters:

```html
https://api.aurinko.io/v1/auth/authorize?clientId={appClientId}&
      &serviceType=Google
      &scopes=Mail.Read%20Mail.Send
      &responseType=code
      &returnUrl=...
      &state={myCustomState}
```

2. User Consent

Aurinko will present your user with the correct sign-in form based on the requested service type (Google, Office365, EWS). For Exchange users, the user has to enter a login name and an Exchange server URL.

3. Getting the token

Once the user has signed in and authorized your app's access, their browser will be redirected to the <mark style="color:red;">`returnUrl`</mark> you provided.

* **Implicit Grant** (<mark style="color:red;">`responseType=token`</mark>)

  If the authentication is successful Aurinko will include the hash fragment <mark style="color:red;">`#accessToken={accessToken}`</mark> with the account access token. That's it!

  *Example redirect URL*: <mark style="color:red;">`https://your-app.com/callback?#accessToken={token}&state={state}&status=success`</mark>

  We recommend storing the `accessToken` and then removing it from the hash fragment with JavaScript. This is the token you will provide as an <mark style="color:red;">`HTTP Bearer Auth`</mark> to make API calls on behalf of the user.
* **Authorization Code Grant** (<mark style="color:red;">`responseType=code`</mark>)

  If the authentication is successful Aurinko will include the `code` parameter in the query string.

  *Example redirect URL*: <mark style="color:red;">`https://your-app.com/callback?code={code}&state={state}&status=success`</mark>

  Make an HTTP POST call to <mark style="color:red;">`https://api.aurinko.io/v1/auth/token/{code}`</mark> to exchange the <mark style="color:red;">`code`</mark> for an <mark style="color:red;">`access_token`</mark>.

```bash
    curl -u ClientId:Secret -X POST https://api.aurinko.io/v1/auth/token/{code}
```

*Response:*

```json
{
	"accountId": 123,
	"accessToken": "aurinko-account-token",
}
```

\
See [/auth/token](https://apirefs.aurinko.io/#tag/Auth/operation/getAccessTokenByCode) for details. Make sure to securely store the <mark style="color:red;">`accessToken`</mark> and provide it as the <mark style="color:red;">`HTTP Bearer Auth`</mark> token to make API calls on behalf of the user (see [Authentication](https://apirefs.aurinko.io/#section/Authentication) details).

[^1]: