Aurinko provides a Unified OAuth Flow that is 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).

In this article we’ll explain three types of OAuth flows supported by Aurinko:

  1. Account - User delegated authorization that produces an Aurinko account and an access token.
  2. Service Account - Admin/Org-level authorization that produces an Aurinko service account and an access token.
  3. User Session - User delegated authorization that produces an Aurinko User, its primary account, and a user session token or cookie.

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 and Google OAuth Setup.

1. Authorization request

From your application, redirect users to https://api.aurinko.io/v1/auth/authorize, with the query parameters detailed in /auth/authorize. You’ll need to set the responseType=code.

Note: responseType=token for client-side flows (corresponding to the OAuth’s implicit grant) is supported but is not recommended!

You’ll also need to determine what permissions your application will request from users, and update the scopes 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 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/authorize?clientId={appClientId}&
      &serviceType=Google
      &scopes=Mail.Read%20Mail.Send
      &responseType=code
      &returnUrl=...
      &state={myCustomState}

Redirect URI: Redirect page vs. Custom domain alias

Google app registrations allow only authorized redirect URIs under a domain you own so the default Aurinko’s Redirect URI https://api.aurinko.io/v1/auth/callback won’t work for you in production.

You have two options:

  • Contact us about provisioning a domain alias for your Aurinko app so you can use a url like https://aurinko.mydomain/v1/auth/callback

  • Create your redirect page to use for redirecting all calls to Aurinko’s https://api.aurinko.io/v1/auth/callback with the URL parameters state, code, and scope.

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 returnUrl you provided.

  • Implicit Grant (responseType=token)

    If the authentication is successful Aurinko will include the hash fragment #accessToken={accessToken} with the account access token. That’s it!

    Example redirect URL: https://your-app.com/callback?#accessToken={token}&state={state}&status=success

    We recommend storing the accessToken and then removing it from the hash fragment with JavaScript. This is the token you will provide as an HTTP Bearer Auth to make API calls on behalf of the user.

  • Authorization Code Grant (responseType=code)

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

    Example redirect URL: https://your-app.com/callback?code={code}&state={state}&status=success

    Make an HTTP POST call to https://api.aurinko.io/v1/auth/token/{code} to exchange the code for an access_token.

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

    Response:

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

    See /auth/token for details. Make sure to securely store the accessToken and provide it as the HTTP Bearer Auth token to make API calls on behalf of the user (see Authentication details).

Service Account OAuth Flow


This is a flow to get admin/app-level access, usually requiring a Google/Office 365 admin authorization. See the following instructions related to service accounts: Service accounts, Setting up G Suite service account, and Setting up Office 365 daemon app registration.

1. Authorization request

From your application, redirect users to https://api.aurinko.io/v1/auth/authorizeDaemon, with the query parameters detailed in /auth/authorizeDaemon. You’ll have to set responseType=code.

You’ll also need to determine what permissions your application will request from users, and update the scopes 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 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.

You have two options:

  • Contact us about provisioning a domain alias for your Aurinko app so you can use a URL like https://aurinko.mydomain/v1/auth/callback

  • Create your redirect page to use for redirecting all calls to Aurinko’s https://api.aurinko.io/v1/auth/callback with the URL parameters state, code, and scope.

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 returnUrl you provided.

  • Authorization Code Grant (responseType=code)

    If your authentication was successful Aurinko will include the code parameter in the query string.

    Example redirect URL: https://your-app.com/callback?code={code}&state={state}&status=success

    Make an HTTP POST call to https://api.aurinko.io/v1/auth/token/{code} to exchange the code for an access_token.

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

    Response:

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

    See /auth/token for details. Make sure to securely store the accessToken and provide it as the HTTP Bearer Auth token to make API calls on behalf of the account (see Authentication details).

User OAuth Flow


Aurinko also provides a variation of the OAuth flow for managing application users (user sessions). In addition to an account token your app will get a user session token userSession or an httpOnly cookie will be set which can be used to access the app user session and all its linked accounts. Two main operations are supported:

  1. Authorizing a primary account and initializing a user session (use &accountRole=primary parameter)
  2. Authorizing a secondary account for an existing user (use &accountRole=secondary parameter)


1. Authorization request

From your application, redirect users to https://api.aurinko.io/v1/auth/authorizeUser, with the query parameters used by the Account OAuth and specify the additional &accountRole=primary parameter. Set responseType to code or cookie (default value if not set).

Here’s an example authorization request for creating a user :

https://api.aurinko.io/v1/auth/authorizeUser?clientId={appClientId}
    &accountRole=primary
    &serviceType=Google
    &scopes=Mail.Read%20Mail.Send
    &returnUrl=...
    &state={state} 

Adding a secondary account (assuming the user session cookie is already set):

https://api.aurinko.io/v1/auth/authorizeUser?clientId={appClientId}
    &accountRole=secondary
    &serviceType=Hubspot
    &returnUrl=...
    &state={state} 

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 user session

Once the user has signed in and authorized your app’s access, their browser will be redirected to the returnUrl you provided.

  • Cookie Mode (responseType=cookie)

    If your authentication was successful Aurinko will set a secure httpOnly session cookie before redirecting to you returnUrl.

    Example redirect URL: https://your-app.com/callback?state={state}&status=success

  • Authorization Code Mode (responseType=code)

    If your authentication was successful Aurinko will include the code parameter in the query string.

    Example redirect URL: https://your-app.com/callback?code={code}&state={state}&status=success

    Make an HTTP POST call to https://api.aurinko.io/v1/auth/token/{code)} to exchange the code for a userSession and userId.

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

    Response:

    {
        "accountId": 123,
        "accessToken": "aurinko-access-token",
        "userId": "user-id-xyz",
        "userSession": "user-session-token"
    }
    

See /auth/token for details. Make sure to securely store the userSession and provide it as an API Key in the X-Aurinko-Session header to make API calls on behalf of the user (see Authentication details).