Microsoft Teams apps

Integrate third-party solutions with Teams using Aurinko API. Develop bots and tabs to enhance user experience and access Graph API seamlessly.

Teams apps are integrations built by third parties into Teams by using Microsoft's web-based platform and bot framework. Teams apps can provide many different capabilities but usually most of them provide at least one tab and some bot functionality. Teams tabs are quite similar to Outlook add-ins as essentially they are JavaScript/HTML code that runs in the context of a browser in a sandbox with special access to Teams chat or channel properties. Usually you Teams app provides a tab in which the app can be configured.

Most Teams apps are built to provide convenient integrations to a third party system or service right from Teams, like Customer Relationship Management, Customer Service, Project Management,... and the app developers all end up developing the same or similar elements of their app:

• Provision a backend API that will support the client code.

• Implement user management (login/logout/session) which needs to be correlated with an authenticated Teams user.

• Support one or more 3rd party authorization flows. For example, a user needs to link his or her CRM account, maybe also a cloud file storage.

• Proxy requests to 3rd party API's. Quite often direct API communications from JavaScript are blocked by CORS in browsers.

• Storing various app user configurations.

• Bot functionality or offline account access. Often special workers are implemented to run in background when an app user is offline.

Aurinko aims to provide the necessary backend functionality for these apps so that developers could focus on the client code to create the best user experiences. Here are the steps to start using Aurinko as a backend API for your Teams app:

1. Get your developer API keys and put your app's client id into your client code or better pass it from your manifest file as an url parameter.

2. In most cases you want to provide bot functionality or have offline account access so provision your Azure app registrations.

3. Setup your Teams bot if you plan to provide bot functionality in your Teams app.

Tabs

---

Your Teams app can be configured to provide tabs for channels and/or chats. A tab is usually where a user will activate your app and configure it. Here is how you use Aurinko API from your tabs.

1. After your app client code has initialized in a Teams tab, test if the current user is already authenticated with Aurinko (logged in):

   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": "[email protected]",
       "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
       "trustedIdentity": true,
       "accounts": [
           {
               "id": 2739,
               "serviceType": "Office365",
               "type": "primary",
               "active": true,
               "daemon": false,
               "loginString": "[email protected]",
               "email": "[email protected]",
               "name": "Office User",
               "authUserId": "abcdabcb-ad8d-4bee-bd69-787675478785",
               "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
               "authObtainedAt": "2021-03-21T16:58:56.823Z"
           }
       ]
   }

   Otherwise 401 Unauthorized in which case your app needs to ask the user to login (see next step).

2. Confirm the current Teams user using the OAuth2 authorization flow. This way your app can also get offline access to Graph API and request additional permissions:

   curl -X GET -G https:/api.aurinko.io/v1/auth/authorize \
       -d clientId='{APPLICATION\_ID}' \
       -d serviceType='Office365'  \
       -d nativeScopes=ChannelMessage.Send \
       -d userAccount='primary' \
       -d returnUrl='https://static.mydomain.com/msteams\_auth\_callback.html'

   The important parameter here is userAccount = primary which turns this account authorization into a 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 Teams scope: ChannelMessage.Send. This scope could allow your app to post to private channels, for example.

3. Authorize access to a 3rd party API. 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 userAccount='secondary' \
       -d returnUrl='https://static.mydomain.com/msteams\_auth\_callback.html'

   Upon a successful authentication and authorization an Aurinko account representing your 3rd party API {MyCRM} will be added and your app can issue the following request (or the request from step 3):

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

   The request will return all Aurinko accounts associated with the current user session:

   {
       "id": "3df3ce21-07c0-4cec-a8de-ed4c570ee15c",
       "appId": 1,
       "email": "[email protected]",
       "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
       "trustedIdentity": true,
       "accounts": [
           {
               "id": 2739,
               "serviceType": "Office365",
               "type": "primary",
               "active": true,
               "daemon": false,
               "loginString": "[email protected]",
               "email": "[email protected]",
               "name": "Office User",
               "authUserId": "abcdabcb-ad8d-4bee-bd69-787675478785",
               "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
               "authObtainedAt": "2021-03-21T16:58:56.823Z"
           },
           {
               "id": 2740,
               "serviceType": "{MyCRM}",
               "type": "secondary",
               "active": true,
               "daemon": false,
               "loginString": "[email protected]",
               "email": "[email protected]",
               "name": "Crm User",
               "serverUrl": "https://crm.instance",
               "authUserId": "374",
               "authOrgId": "999",
               "authObtainedAt": "2021-03-21T17:39:10.513Z"
           }
       ]
   }

4. Now your addin can access either Graph API (through Aurinko's unified API) or the 3rd party API. Specify an account id in the special header X-Aurinko-AccountId and use Aurinko Email/Calendar/Contact to access those accounts.

   curl -H 'X-Aurinko-AccountId: 2739' \
       -X GET https:/api.aurinko.io/v1/email/messages
   	

   curl -H 'X-Aurinko-AccountId: 2740' \
       -X GET https:/api.aurinko.io/v1/contacts

5. To manage app configurations use Aurinko's storage API.

   Note: all Teams users in Aurinko are associated with their Office 365 organizations automatically.

   User level properties - receive key/value properties associated with the user.

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

   Org level properties - receive key/value properties associated with the user's Office 365 organization.

   curl -X GET https:/api.aurinko.io/v1/storage/organization

Bots (workers)

---

When developing a bot or a worker for a specific task (i.e. sync or scanner) you need to have a background process that can work with Teams data while its users are offline. Here is how such worker processes can use Aurinko API.

1. Host your worker process anywhere you like. Contact us at [email protected] about activating our pre-built chat sync logic.

2. Have your worker connect to Aurinko API periodically to find out about new app installations (webhooks will be available soon too). Use the following API request to retrieve the list of MsTeamsBot service accounts:

   curl -u ClientId:Secret -X GET https:/api.aurinko.io/v1/svc\_accounts \
       -G -d serviceType='MsTeamsBot'
   {
       "records": [
           {
               "id": 2152,
               "serviceType": "MsTeamsBot",
               "active": true,
               "daemon": true,
               "loginString": "c345743-ecea-47fa-97d4-b4b4b6c70fa52",
               "name": "yoxel.net",
               "authOrgId": "c345743-ecea-47fa-97d4-b4b4b6c70fa52"
           },
           {
               "id": 2262,
               "serviceType": "MsTeamsBot",
               "active": true,
               "daemon": true,
               "loginString": "48f3456a-61d5-4673-8cd2-d24c39ee34f3",
               "name": "team.onmicrosoft.com",
               "authOrgId": "48f3456a-61d5-4673-8cd2-d24c39ee34f3"
           },
           ...
           
       ],
       "totalSize": 5,
       "offset": 0,
       "done": true
   }

3. Receive app configurations using Aurinko's storage API. These could be user or organization level configurations created by your tab.

   User level properties - receive key/value properties associated with the user.

   curl -u ClientId:Secret \
       -X GET https:/api.aurinko.io/v1/storage/user

   Org level properties - receive key/value properties associated with the user's Office 365 organization (see authOrgId in the service account responses).

   curl -u ClientId:Secret \
       -X GET https:/api.aurinko.io/v1/storage/organization/find \
       -G -d provider='Office365' -d xid='48f3456a-61d5-4673-8cd2-d24c39ee34f3'

4. Post messages to Teams using Aurinko's chat API

5. Subscribe to receive events.