# Microsoft services

# Setting up custom OAuth keys

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.

If you are using connectors for Microsoft Teams, OneDrive, OneDrive for Business, or SharePoint Online, configure Azure app credentials for admin accounts.

# Configuring Azure app credentials for admin accounts

If the OAuth keys you are creating are intended for authenticating admin accounts for the following services, additional steps are required:

Microsoft Teams
OneDrive
OneDrive for Business
SharePoint Online
Follow the steps described here to allow your app to authenticate admin accounts:
1. 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
```
1. 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>"
  }
]
```
1. 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 permissions (scopes)

Add permissions for the Microsoft service you are using in Azure Active Directory. Under Manage > API permissions, click Add a permission.

The permissions listed here allow for the full functionality of Kloudless' API. Remove any permissions your app does not need access to based on your usage of the Kloudless API, and add any additional permissions your app may require; for example, if your app is accessing additional data via the pass-through API which requires permissions beyond those listed here.

The permissions required by the Kloudless API for each Microsoft service are listed here:

Microsoft Teams
OneDrive
OneDrive for Business
Outlook Calendar
Outlook Mail
SharePoint Online

# Microsoft Teams

# 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

# Additional steps for Microsoft Teams admins

To enable Activity Monitoring, the Kloudless Microsoft Teams connector subscribes to resources which requires access to protected Microsoft Teams APIs. See the Activity Monitoring section of the Microsoft Teams connector guide for more information on how to request access to protected APIs.

# OneDrive

For apps authenticating OneDrive users, add the following Delegated permissions for Microsoft Graph:

# Microsoft Graph (Delegated permissions)
    offline_access
    profile
    openid
    Files.ReadWrite.All
    User.Read

# OneDrive for Business

# Authenticating non-admin users

For apps authenticating OneDrive for Business non-admin users, add the following Delegated Permissions for Microsoft Graph and SharePoint:

# Microsoft Graph (Delegated permissions)
    offline_access
    Files.ReadWrite.All
    Sites.Manage.All
    User.Read

# SharePoint (Delegated permissions)
    AllSites.Manage
    AllSites.Read
    MyFiles.Write

# Authenticating admin users

For apps authenticating OneDrive for Business admin users, add the following Application permissions for Azure Active Directory Graph, Microsoft Graph, Office 365 Management APIs, and SharePoint:

# Azure Active Directory Graph (Application permissions)
	Directory.ReadWrite.All

# Microsoft Graph (Application permissions)
	Directory.ReadWrite.All
    Files.ReadWrite.All
	Group.ReadWrite.All
    Sites.ReadWrite.All
	User.ReadWrite.All

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

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

# Outlook Calendar

# Authenticating non-admin users

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

# Microsoft Graph (Delegated permissions)
    email
    offline_access
    openid
    profile
    Calendars.ReadWrite.Shared
    Calendars.ReadWrite
    Contacts.Read
    Contacts.Read.Shared
    MailboxSettings.Read
    User.Read
    User.ReadBasic.All

# Authenticating admin users

For apps authenticating Outlook Calendar admin users, add the following Application permissions and Delegated permissions for Microsoft Graph:

# Microsoft Graph (Application permissions)
    Calendar.ReadWrite
    Contacts.Read
    MailboxSettings.ReadWrite
    User.Read.All

# Microsoft Graph (Delegated Permissions)
    email
    offline_access
    openid
    profile

# Outlook Mail

# Authenticating non-admin users

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

# Microsoft Graph (Delegated permissions)
    email
    offline_access
    openid
    profile
    Contacts.Read
    Contacts.Read.Shared
    Mail.ReadWrite
    Mail.Send
    MailboxSettings.Read
    User.Read
    User.ReadBasic.All

# Authenticating admin users

For apps authenticating Outlook Mail admin users, add the following Application permissions and Delegated permissions for Microsoft Graph:

# Microsoft Graph (Delegated permissions)
    email
    offline_access
    openid
    profile
# Microsoft Graph (Application Permissions)
    MailboxSettings.Read
    User.Read.All
    Mail.Send
    Mail.ReadWrite

# SharePoint Online

# Authenticating non-admin users

For apps authenticating non-admin SharePoint users, add the following Delegated Permissions for Microsoft Graph and SharePoint:

# Microsoft Graph (Delegated permissions)
    offline_access
    Files.ReadWrite.All
    Sites.Manage.All
    User.Read

# SharePoint (Delegated permissions)
    AllSites.Manage
    AllSites.Read
    MyFiles.Write

# Authenticating admin users

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

# Azure Active Directory Graph (Application permissions)
	Directory.ReadWrite.All

# Microsoft Graph (Application permissions)
	Directory.ReadWrite.All
    Files.ReadWrite.All
	Group.ReadWrite.All
    Sites.ReadWrite.All
	User.ReadWrite.All

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

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

# White-labeling your app

You can customize what your users see when signing in by navigating to Manage > Company branding. Upload a logo, background image, and modify sign in page text to fit your brand.

# Admin approval warning

Some Azure tenant admins restrict their users from granting access to their data to unapproved third-party applications. If your users see a warning message preventing them from connecting to your app without their admin's permission, direct the user to request access using one of the listed methods:

If the user's admin has configured the admin consent workflow , the user can simply request the admin to approve access to the app while attempting to signing in.
Manually request admin approval by directing admins to a URL to grant access to their users' data.

Using this method, the user's admin will be prompted to grant access to your app when accessing this URL. For more details on this method, see Microsoft's documentation on granting tenant-wide admin consent.

# Microsoft service connector guides

For details on working with a specific connector, see our individual connector guides for the following Microsoft services:

← Google services ID Types at Kloudless →