User management

Workspace addons like Office addins, Google addons, Teams/Slack apps are quite different from regular web apps because they run in a user context of another app with special access to the hosting app API. The addon users don't need to signup for a new account they need to be able to use their existing Id. That is why Aurinko user management is essentially based on openid, or a trusted 3rd party oauth2 authentication (i.e. your CRM platform login).

Office addins / Teams app tabs

Office addins are essentially JavaScript/HTML code that runs in an IFRAME of a browser. Aurinko implements user session for these addins using a session cookie.

A recommended way for an Office addin using Aurinko to verify a user identity and initialize a user session (to login) is to go through standard steps of an oauth2 flow, at minimum with the "openid" scope. The following example is for an authorization flow in a popup window that an Outlook addin or Teams tab could use:

curl -X GET -G https:/api.aurinko.io/v1/auth/authorize \
    -d clientId='{APPLICATION_ID}' \
    -d serviceType='Office365' \
    -d scopes='Mail.Read Mail.Send' \
    -d userAccount='primary' \
    -d returnUrl='https://static.mydomain.com/outlook_auth_callback.html'

userAccount = primary is the key parameter here which turns this account authorization into user session initialization (user login). Upon successful authentication and authorization the redirect to returnUrl will result in setting a session cookie which will allow your app to stay recognized by Aurinko until the user logs out.

In addition to the login Aurinko gets access to Graph API with the following scopes: Mail.Read, Mail.Send. This will allow your app to work with the Office 365 account while the user is not using your addon.

To test if the current user is already authenticated with Aurinko (logged in) call Aurinko user API:

curl -X GET -G https://api.aurinko.io/v1/user

For a logged in user the request will return the user info and its active Aurinko accounts:

{
  "id": "3df3ce21-07c0-4cec-a8de-ed4c570ee15c",
  "appId": 1,
  "email": "",
  "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
  "trustedIdentity": true,
  "accounts": [
    {
      "id": 2739,
      "serviceType": "Office365",
      "type": "primary",
      "active": true,
      "daemon": false,
      "loginString": "",
      "email": "",
      "name": "Addin User",
      "authUserId": "abcdabcb-ad8d-4bee-bd69-787675478785",
      "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
      "authObtainedAt": "2021-03-21T16:58:56.823Z"
    }
  ]
}

Otherwise, 401 Unauthorized status will be returned.

Google workspace addons

Google workspace addons are server based code (AppScript) that runs on Google servers producing pages to be shown by the Google addon engine. The AppScript code runs in a trusted context meaning your code can trust the user id provided by the addon API. Aurinko implements user sessions for these addons using a special authorization header X-Aurinko-Session.

Because the code runs on servers in a safe trusted context you can use Aurinko account management API methods with app id/secret. The simplest way to register the current addon user with your Aurinko app is the following:

curl -u ClientId:Secret -X POST https:/api.aurinko.io/v1//am/accounts?userAccount=primary \
	-d '{
        	"serviceType": "Google",
    		"loginString": "{userEmail}",
    		"email": "{userEmail}",
    		"authOrgId": "{emailDomain}",
    		"active": true
	}'

Response:

{
  "userId": "7082f6ab-6339-4b6a-85f9-afb16515c906",
  "userSession": "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InJtYiI6InRydWUiLCJjbGllbnRJZCI6ImUyNGIwNGZjNmRhYjdjODI3ODEzZGEzODFiNGJmMDZkIiwiaWF0IjoiMTYxNDY5NTQ0OSIsInR5cGUiOiJ0b2tlbiIsImVuZFVzZXJJZCI6IjcwODJmNmFiLTYzMzktNGI2YS04NWY5LWFmYjE2NTE1YzkwNiJ9LCJuYmYiOjE2MTQ2OTU0NDksImlhdCI6MTYxNDY5NTQ0OX0.jfpK11tI1QWpfivpu7MP_YksIXnKSMqSD9IMfd0Y2fY"
}

Store userId and userSession in AppScript storage so that your code could verify login status after reloading.

Once a user is provisioned your addon can add other secondary accounts using OAuth2 flow in a popup window. Contact us at [email protected] to arrange adding a connector for your system, i.e. {MyCRM}.

curl -X GET -G https:/api.aurinko.io/v1/auth/authorize \
	-d clientId='{APPLICATION_ID}' \
	-d serviceType='{MyCRM}' \
	-d state='{addonState}'
	-d userAccount=secondary \
	-d responseType='none' \
	-d userId='{AurinkoUserId}'
	-d returnUrl='{addonReturnUrl}' \
	-d timestamp='{currentTimestamp}' \
	-d userSignature='{signature}'

Use userAccount=secondary, userId from the the previous step, and sign the request. For more details see Google workspace addons.

Slack apps

Slack apps are server based code that runs on your servers producing formatted messages to be shown by Slack. Your code most probably runs in a trusted context, meaning, your code can trust the user id provided by Slack API. Aurinko will automatically provision users for your app upon receiving certain events directed at your app, i.e. command, app_home_visited, app invited to a channel