# Service Account OAuth Flow

Aurinko provides multiple Unified OAuth Flows backed by providers’ OAuth2 (i.e. Google, Office 365, Zoho Mail, Salesforce, HubSpot, SugarCRM) or by secure password-based authentication (i.e. MS Exchange, IMAP accounts).

## Service Account OAuth Flow

***

This flow is for gaining admin/app-level access, usually requiring a Google/Office 365 admin authorization. See the following instructions related to service accounts: [Service accounts](https://docs.aurinko.io/authentication/service-accounts), [Setting up G Suite service account](http://helpdocs.yoxel.com/salesforce/setting-up-g-suite-service-account), and [Setting up Office 365 daemon app registration](https://docs.aurinko.io/authentication/service-accounts/setting-up-office-365-daemon-app-registration).

The flow produces an Aurinko <mark style="color:red;">`service account`</mark> 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>

1. **Authorization request**

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

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:

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

***Redirect URI: Redirect page vs. Custom domain alias***

In case your Microsoft app registration requires redirect URIs to be under a domain you own the default Aurinko's Redirect URI <https://api.aurinko.io/v1/auth/callback> may not work for you in production.

<div data-full-width="true"><figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2Fgn5rJlaiSaXP99oUQgz6%2Fimage.png?alt=media&#x26;token=f6297fb6-ad96-4c75-b66f-e0cec10c5c9c" alt=""><figcaption></figcaption></figure></div>

You have two options:

* Contact us about provisioning a domain alias for your Aurinko app so you can use a URL like <mark style="color:red;">`https://aurinko.mydomain/v1/auth/callback`</mark>
* Create your **intermediate redirect** page to use for redirecting all calls 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>. See the corresponding OAuth flow in the following diagram:

<figure><img src="https://3933352743-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0ua36KLVlbUN5bA2bgiq%2Fuploads%2FyONhydXgh8BGx7h3QRCe%2FSlide%2016_9%20-%204.jpg?alt=media&#x26;token=cf718678-02f2-45f7-967e-7807782b3d4b" alt=""><figcaption></figcaption></figure>

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.

* **Authorization Code Grant** (<mark style="color:red;">`responseType=code`</mark>)

  If your authentication was 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 account (see [Authentication](https://apirefs.aurinko.io/#section/Authentication) details).