# Kloudless API interaction

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

# Setting up OAuth Keys for Microsoft Teams

To set up OAuth keys for Microsoft Teams, sign in to your Kloudless Account and go to the Third Party Services Configuration section. Navigate to the section for Microsoft Teams and click on the link to configure your own keys.

You can create an Azure application and retrieve OAuth credentials in the Azure Portal. More information on how to register your application is available on this quick-start guide by Microsoft. Follow the steps below to set up a new Azure Application with the right permissions and authentication credentials.

  • Select 'New Registration' under the App Registrations page of the Azure Portal, and choose an app name.
  • Under "Supported Account Types", select the option to authenticate accounts in any Azure AD directory (multi-tenant), but not personal accounts (Skype, Xbox).
  • Under "Redirect URL", choose "Web", and set the Redirect URL to the redirect URL shown on the Kloudless "Custom OAuth Keys" page linked above.

Once the app is registered, perform the following steps:

  • Use the Application ID as the Client ID in Kloudless platform.
  • Generate a new client secret for your application and include it as the Client Secret in Kloudless platform. You can generate a client secret on the "Certificates and secrets" page for this Azure App Registration.
  • If the connector's purpose is to obtain org-wide access to data by authenticating admin accounts, check "ID tokens" in the "Implicit grant" section of the "Authentication" page for this Azure App Registration.

Next, configure API permissions for the Azure app as detailed below.

# Required Scopes

If the Application is intended to authenticate regular users, add the following Microsoft Graph Delegated Permissions on the "API permissions" page for the Azure App:

  • Channel.ReadBasic.All
  • ChannelMessage.Send
  • ChannelMessage.Delete
  • ChannelMessage.Edit
  • Chat.ReadWrite
  • Files.ReadWrite.All
  • Team.Create
  • Team.ReadBasic.All
  • User.Read
  • User.ReadBasic.All

If the Application is instead intnded to authenticate admin accounts, add the following Application Permissions on the "API permissions" page for the Azure App:

  • Microsoft Graph:
    • 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.ReadWrite.All
    • User.ReadBasic.All
  • Office 365 Management APIs:
    • ActivityFeed.Read
  • Sharepoint
    • Sites.FullControl.All
    • TermStore.ReadWrite.All
    • User.ReadWrite.All

The Application permission "ChannelMessage.Read.All" is a protected permission. Refer to the Activity Monitoring section below for information on how to request access to this Azure app permission.

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

# Configuring Azure App Credentials when authenticating Admin Accounts

These extra steps are required if the keys are intended to authenticate Admin Accounts:

  • Generate a self-signed certificate with the following command (feel free to customize the $SUBJ environment variable with your own organization's details):
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 and add an entry to the keysCredentials list that defines the configuration for certificate authorization. Run this Python script to generate the values required for the entry.
  • An entry has the structure below, as shown by the Python script:
"keyCredentials": [
  {
    "customKeyIdentifier": "<Custom Key Identifier>",
    "keyId": "<Custom generated GUID>",
    "type": "AsymmetricX509Cert",
    "usage": "Verify",
    "value": "<base64 encoded certificate>"
  }
]
  • Once the Azure app’s Manifest is saved, Kloudless will need the private key information. In the Custom OAuth Keys form, enter in the following information and click Save:
    • Client ID
    • Client Secret
    • Custom Key Identifier
    • Upload the private key
    • Azure Directory ID (Optional)

# Connecting to Microsoft Teams

Microsoft Teams uses standard OAuth 2.0 authentication. You can test this via 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

# 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 private member-to-member conversations ("chats" in Microsoft terminology) due to Microsoft Graph API security restrictions.
  • Listing Conversation Messages will return 403 errors for regular accounts due to this capability first requiring admins to grant access to the app.
  • Listing folders for regular 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.
  • If a Conversation name has been 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.

# Activity Monitoring

If an end-user connects an Admin Account, the 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 applicable firewall rules are configured to allow external access to the API server.

The Kloudless Microsoft Teams connector attempts to subscribe to two resources:

  • /teams/allMessages
  • /chats/allMessages

Both resources require protected permissions , so a request form must be completed to request access to them. Special licenses may also be required as well.

# Support

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