Microsoft Teams | Kloudless API Guide

# Kloudless API interaction

Connector Category: Chat
Unified APIs Supported: Chat, Storage, Team

# Setting up OAuth Keys for Microsoft Teams

To configure custom OAuth keys for your Kloudless application:

Register an Azure application in the Azure portal and retrieve OAuth credentials.
Configure your credentials in the Custom OAuth Keys page of your Kloudless Developer portal.

# Registering an Azure application

First, you'll need to register your application in the Azure Portal.

Log in to Azure Active Directory in the Azure Portal.
Under Manage, select App registrations and then New registration.
Fill in a Name for your app (this can be changed later). Under Supported account types, select the option Accounts in any organizational directory (Any Azure AD directory - Multitenant).

Do not select the option that includes personal Microsoft accounts (e.g. Skype, Xbox).
Under Redirect URI (optional), select Web from the dropdown and provide the redirect URI listed for the connector your are using in the Custom OAuth Keys page.

Additional details about each step can be found in Microsoft's quickstart on registering an application with the Microsoft Identity platform.

# Configuring credentials with Kloudless

Once your app is registered, you will have a client ID and will be able to generate a new client secret.

In the Azure Portal's Overview tab, you will now be able see the Application (client) ID field for the app you registered. Configure this client ID in your Kloudless Developer Portal's Custom OAuth keys page.

Find your Application (client) ID in the Azure Portal by searching for and selecting your app in Manage > App registrations, then navigating to the Overview tab.
Generate a new client secret. Under Manage, select Certificates & secrets, then New client secret. Configure this client secret in the Custom OAuth keys page.

If your app is authenticating admin accounts to obtain org-wide access to data, complete these additional steps:

Under Manage > Authentication, in the Implicit grant section, select ID tokens.

Configure Azure app credentials for admin accounts.

Then, configure API permissions for the Azure app as detailed in the required scopes section.

# Configuring Azure app credentials for admin accounts

Follow the steps described here to allow your app to authenticate admin accounts:

Generate a self-signed certificate with the following command (customize the $SUBJ environment variable with your own organization's details if needed):

SUBJ="/C=AU/ST=Some-State/L=/O=An Org/OU=/CN=ADomain";
openssl req -x509 -subj "$SUBJ" -newkey rsa:4096 -keyout key.pem -out cert.pem -nodes -days 18250

Update the Azure app's Manifest (Manage > Manifest) and add an entry to the keyCredentials list that defines the configuration for certificate authorization. Use the Python keyCredentials script to generate entry values with the following structure:

"keyCredentials": [
  {
    "customKeyIdentifier": "<Custom Key Identifier>",
    "keyId": "<Custom generated GUID>",
    "type": "AsymmetricX509Cert",
    "usage": "Verify",
    "value": "<base64 encoded certificate>"
  }
]

In the Custom OAuth keys page of your Kloudless Developer Portal, provide the following information:
- Client ID
- Client Secret
- Custom Key Identifier
- Private key passphrase
- The private key file
- Azure Directory ID (optional)

# Required Scopes

# Authenticating non-admin users

For apps authenticating non-admin Microsoft teams users, add the following Delegated permissions for Microsoft Graph:

# Microsoft Graph (Delegated permissions)
    Channel.ReadBasic.All
    ChannelMessage.Send
    ChannelMessage.Delete
    ChannelMessage.Edit
    Chat.ReadWrite
    Files.ReadWrite.All
    Team.Create
    Team.ReadBasic.All
    User.Read
    User.ReadBasic.All

# Authenticating admin users

For apps authenticating Microsoft Teams admin users, add the following Application permissions for Microsoft Graph, Office 365 Management APIs, and SharePoint:

# Microsoft Graph (Application permissions)
    Channel.Create
    Channel.ReadBasic.All
    ChannelMember.ReadWrite.All
    ChannelMessage.Read.All
    ChannelMessage.Send
    ChannelSettings.ReadWrite.All
    Chat.ReadWrite.All
    Directory.AccessAsUser.All
    Directory.ReadWrite.All
    Group.ReadWrite.All
    GroupMember.ReadWrite.All
    Team.ReadBasic.All
    TeamSettings.ReadWrite.All
    User.ReadBasic.All
    User.ReadWrite.All

# Office 365 Management APIs (Application permissions)
    ActivityFeed.Read

# SharePoint (Application permissions)
    Sites.FullControl.All
    TermStore.ReadWrite.All
    User.ReadWrite.All

Kloudless requires access to some protected APIs in Microsoft Teams which require additional steps beyond granting permissions before they can be accessed. See the Activity Monitoring section for details on how your app can gain access to these protected APIs.

Feel free to customize the list above if other permissions are required, or if some permissions are unnecessary based on your usage of the Kloudless API. Note that permissions can only be customized via the Azure App Registry as mentioned above, rather than dynamically as part of the Kloudless OAuth flow.

# Connecting to Microsoft Teams

Microsoft Teams uses standard OAuth 2.0 authentication. You can test out connecting a user account with the Kloudless API Explorer.

# Supported API endpoints

The Microsoft Teams connector currently supports a subset of endpoints in the Kloudless Chat, Storage, Team, and Activity API:

Chat
- GET /messaging/conversation
- GET /messaging/conversation/{conversation_id}
- GET /messaging/conversation/{conversation_id}/messages
- GET /messaging/conversation/{conversation_id}/messages/{message_id}
Team
- GET /team/users
- GET /team/groups
- GET /team/groups/{group_id}/members
Storage
- GET /storage/files/{file_id}
- GET /storage/files/{file_id}/contents
- GET /storage/folders/{folder_id}
- GET /storage/folders/{folder_id}/contents
Activity
- GET /subscriptions
- POST /subscriptions
- GET /subscriptions/{subscription_id}
- PATCH /subscriptions/{subscription_id}
- DELETE /subscriptions/{subscription_id}
- GET /subscriptions/{subscription_id}/activity

# Activity Monitoring

If an end-user connects an admin account, your Kloudless application can monitor the tenant for activity such as new messages and files.

Activity monitoring relies on notifications from Microsoft servers. Self-hosted Kloudless servers must therefore ensure that firewall rules are configured to allow external access to the API server.

The Kloudless Microsoft Teams connector subscribes to two resources:

/teams/getAllMessages
/chats/getAllMessages

Both resources require access to protected Microsoft Teams APIs in Microsoft Graph, so a request form must be completed to access them. Special licenses may also be required.

# Limitations

Due to Microsoft Graph API limitations, Kloudless Activity Monitoring is only available for admin accounts. In addition, only a single admin account per tenant can monitor activity in that tenant for each unique Microsoft Application (custom OAuth key).
Listing Conversations in admin Kloudless accounts will not include "chats" (private member-to-member conversations) due to Microsoft Graph API security restrictions.
Listing Conversation Messages will return 403 errors for non-admin accounts due to the requirement that admins must grant access to the app.
Listing folders for non-admin accounts will only include folders for teams and channels that the user is a member of.
Kloudless Groups for Microsoft Teams are a subset of Office 365 groups.
- See Microsoft's documentation on teams and groups for more details.
If a Conversation name has changed, it may still return its old name when retrieving metadata for the folder via the Storage API. This is due to a Graph API limitation that prevents updated channel metadata from being returned.

# Support

Please contact us at support@kloudless.com with any questions you may have. We'd be happy to help you get set up.

← Microsoft Dynamics OneDrive →