All articles on building an Azure Bot Services deployment with SSO
- Azure Bot Services: Advanced deployment with SSO (Microsoft Teams): Intro
- Azure Bot Services: Advanced deployment with SSO (Microsoft Teams): AAD Portal
- Azure Bot Services: Advanced deployment with SSO (Microsoft Teams): Azure Portal
- Azure Bot Services: Advanced deployment with SSO (Microsoft Teams): Apps Developer Portal
- Azure Bot Services: Advanced deployment with SSO (Microsoft Teams): SSO and Graph API Nodes
Create an App Registration in Azure Active Directory
To create the App Registration in Azure Active Directory (Azure AD), follow these steps:
- Log in to the Azure Active Directory admin center and select Azure Active Directory. You need an account with the appropriate rights to access Azure Active Directory (Azure AD). If you don't already have an account, you can create one for free with some free resources during the first 30 days. Once you have logged in, you can manage your Azure AD settings.
- In the Manage section, select App registrations.
- Click + New registration.
- Enter a Name for your application. Users of your app might see this name, and you can change it later.
- Choose one of the options in the Supported account types:
- Single Tenant — only users with Teams hosted in the same Azure Tenant can access the bot.
- Multi-Tenant — any customer or partner can access the bot.
- In the Redirect URI section, select Single-page application (SPA) and add a redirect to ensure authentication requests get authenticated by Microsoft. Use one of these URIs:
- Single Tenant — https://login.microsoftonline.com/<tenantID>/oauth2/v2.0/token, where tenantID is Directory (tenant) ID.
- Multi-Tenant — https://token.botframework.com/.auth/web/redirect
- Select Register to create the app registration. After that, the App Registration overview page will be opened.
- Copy and save:
- Application (client) ID to the text file as Client ID.
- Directory (tenant) ID to the text file as Tenant ID. When building a multi-tenant app registration, this is not required.
Configure the App Registration
In the Manage section, you need to configure the following settings:
- Certificates & secrets
- API permissions
- Expose an API
1. Check and configure the following settings:
- Redirect URIs:
- Single Tenant — use the https://login.microsoftonline.com/<tenantID>/oauth2/v2.0/token format, where tenantID is Directory (tenant) ID.
- Multi-Tenant — use the https://token.botframework.com/.auth/web/redirect format.
- Front-channel logout URL — add the Endpoint URL you previously copied from the Cognigy.AI Azure Bot Services Endpoint.
- Account Type — should already be set to the type you selected earlier.
2. Click Save if you made some changes.
(Optional) URI migration warning
If you have used a Web type of application before, you can see the following URI migration warning:
To migrate to the single-page application (SPA) platform configuration, follow these steps:
- In the warning, click → (blue arrow).
- In the Migrate URIs window, select URIs from the list.
- Click Configure.
- Deactivate the following settings:
- Access tokens (used for implicit flows).
- ID tokens (used for implicit and hybrid flows).
If you see the Disable Implicit Grant note, click Disable.
- Save changes.
Once changes are applied, you will see the following result:
Certificates & Secrets
For SSO, you need to create a secret. To do that, follow these steps:
- Click + New client secret.
- On the Add new client window, add a secret name and select an expiration key date.
- Click Save.
- Copy the secret value by clicking the copy icon, then save this value to the text file. Note that you have only one opportunity to save it, as it won’t be readable afterward. If you lose the secret value, you need to create a new secret later.
SSO enables us to receive a token that can be used with the Graph API to trigger a lot of different services or retrieve data, for example, reading the user’s name or his emails.
You need to specify all permissions that are mandatory for executing tasks. There are two different types of permissions available:
- User-approved permissions — include permissions to retrieve the username and job title. For these, a single-user approval is sufficient.
- Admin-approved permissions — include permissions that might have an impact on your organization.
Note: Depending on the configured rights in your Microsoft Teams organization and Azure, admin approval might be required even though the selected rights are marked as if they don't. This will likely occur if you request permissions from a user, and when giving consent, a pop-up menu states that the app needs to be approved by an administrator. Admins can then approve these requests by using this link. It might also be mandatory to verify a publisher domain and create a Microsoft Partner Center ID (MPC ID). This can be done in the Branding section in the sidebar.
In this tutorial, we only focus on user-approved permissions.
To add new permission:
- Click + Add a permission.
- Click the Microsoft Grap card.
- Select Delegated permissions for SSO.
- Select all permissions that you want to grant the SSO bot. We recommend saving permissions with names, as you will use them later. We will refer to them as Permissions. We always include the name string, such as email or openid, regardless of the naming convention to prevent confusion.
- Check openid as it’s mandatory for SSO authentication.
- Save changes by clicking Add permissions.
- Click Grant admin consent for to approve the permissions. Each permission will get a green checkmark in the Status column.
Expose an API
Configure the following settings:
- Modify a value in the Application ID URI field. This value must be api://botid-<client-id> where the client-id is the Client ID you previously copied and saved.
- Click +Add a scope.
- Enter a Scope name. The Scope name can be chosen freely.
- In the Who can consent? setting, toggle on Admins and users.
- Fill out all other mandatory fields. They will be displayed when adding the Teams app to Teams.
- Save changes by clicking Add scope.
- Click +Add a client application.
- Add additional Client IDs:
- 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (required for MS Teams Web Client).
- 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (required for MS Teams Mobile & Desktop Client).
The Manifest is the configuration file that automatically gets created and reflects all changes you made to the configuration. Microsoft has reduced the number of possible settings in the menus.
Modify the following values in JSON:
- AccessTokenAcceptedVersion — null > 2
- Oauth2RequirePostResponse — false > true
- SignInUrl — null > previously copied Endpoint URL from the Cognigy.AI Azure Bot Services Endpoint
Save changes. Your App registration has been completed.