Microsoft Azure Bot Registration (including OAuth) - Microsoft Azure Bot Registration (including OAuth) - Alfresco - Alfresco Collaboration Connector for Teams - Alfresco/Alfresco-Collaboration-Connector-for-Teams/2.0/Alfresco-Collaboration-Connector-for-Teams/Install/Microsoft-Azure-Bot-Registration-including-OAuth - 2.0 - 2.0

Alfresco Collaboration Connector for Teams
Platform
Alfresco
Product
Alfresco Collaboration Connector for Teams
Release
2.0
License
ft:lastPublication
2026-07-16T22:00:44.862000
ft:locale
en-US

Microsoft Teams and Azure services can interact with Teams Extensions and Bots hosted outside of Azure only when they are registered in Azure. See more details in the official Microsoft docs.

Note: The payment plan is subject to your choice (below it says to change the plan to ‘Free’, but that is not necessary.

To register the Microsoft Azure Bot and configure the OAuth connection to the Alfresco Digital Workspace (ADW) follow these steps:

  1. Sign in to the Microsoft Azure Portal:
    • If you see a Quick Start page, then remove it by clicking the X to the right.
    Note: The logged in user must have permission to register bots in Azure Active Directory (AAD).
  2. Register the Microsoft Azure Bot:
    1. Click the Create a resource item under Azure services to start Azure bot registration.
    2. Type Azure Bot in the search input field and choose the Azure Bot item.
    3. Click Create.
    4. In the Bot handle field type a unique name for your Bot (cannot be changed later on). Such as alfresco-teams-integration.
    5. Select desired subscription and resource group. Both are required.
    6. Click Change plan.
    7. Select Free.
    8. Let Azure create a Microsoft App ID for you.
    9. Click Review + create (optionally you can add tags to your Bot).
    10. If all pre-checks passed click Create.
    11. Azure will deploy your registration.
    12. When complete, click on Go to resource.
    13. Click on the Configuration menu item to the left under Settings.
    14. Set Messaging endpoint to https://{my.domain}/{teams-service-path}/api/messages. This is the URL that the Collaboration Connector for Teams is exposed on.

      For example: https://develop.mycompany.com/ms-teams-service/api/messages

    15. Copy your Microsoft App ID. For example: 9af7ae3a-1798-4de7-a992-c3ac489e5324. We later refer to this app identifier as MS_BOT_APP_ID.
    16. Click Apply to save configuration.
  3. Configure the OAuth connection to the ADW.

    Click on Add OAuth Connection Settings, a window will appear on the right side of the screen.

    A full example on how to set up all the values can be found in the following table:

    Property Description Value
    Name The name of your connection Typically this is set to alfresco - when changed it must be reflected in microsoft.app.oauth.connection-name app property when running Alfresco Collaboration Connector for Teams.
    Service Provider Identity provider type From the drop-down list, select Oauth 2 Generic Provider
    Client ID Refers to the name of the OAuth client in Keycloak (OAuth) configuration in the Identity Service. Typically alfresco
    Client secret OAuth client secret (if client access is not public), otherwise this field must be filled but the value is irrelevant random string
    Scope List Delimiter The character to use between scope values (often a space or comma) , <enter comma>
    Authorization URL Template Authorization endpoint URL https://{my.domain}/auth/realms/alfresco/protocol/openid-connect/auth
    Authorization URL Query String The query string to append to the authorization URL, templated with any wanted parameters: {ClientId} {ClientSecret} {RedirectUrl} {Scopes} {State} ?client_id={ClientId}&redirect_uri={RedirectUrl}&scope={Scopes}&response_type=code&state={State}
    Token URL Template Token endpoint URL https://{my.domain}/auth/realms/alfresco/protocol/openid-connect/token
    Token URL Query String Template Body to send for the token exchange ? <enter question mark>
    Token Body Template Body to send for the token exchange code={Code}&grant_type=authorization_code&redirect_uri={RedirectUrl}&client_id={ClientId}&client_secret={ClientSecret}
    Refresh URL Template Token refresh endpoint URL https://{my.domain}/auth/realms/alfresco/protocol/openid-connect/token
    Refresh URL Query String Template The query string to append to the refresh URL, templated with any wanted parameters: {ClientId} {ClientSecret} {RedirectUrl} {Scopes} {State} ? <enter question mark>
    Refresh Body Template Body to send with the token refresh refresh_token={RefreshToken}&redirect_uri={RedirectUrl}&grant_type=refresh_token&client_id={ClientId}&client_secret={ClientSecret}
    Token Exchange URL Used for SSO in Azure AD v2 Leave blank
    Scopes Comma separated list of the API permissions you granted earlier to the Azure AD authentication app openid
  4. Click Save to validate and store the OAuth configuration.
  5. Test the ADW Connection:
    1. Click on your newly created connection and then click Test Connection.
    2. Enter username and password and click Sign in.
  6. Retrieve bot Secret.

    If you already had a bot secret but lost it, then skip this section and proceed directly to 6. Already had a bot secret.

    This secret is important and is not to be confused with the Oath client secret used above. It is one of the mandatory properties when starting the Collaboration Connector for Teams bot service.

    1. In the top-most search bar type in vault and click on Key vaults.
    2. Click on the item with a name starting with bot-secrets-*.
    3. Choose Secrets (vertical) tab.
    4. The following message is displayed: The operation “List” is not enabled in this key vault’s access policy.
    5. Go to Access Policies (vertical tab) and click on Add Access Policy. The easiest way to add it is to choose from a template (‘Configure from template’) named ‘Key, secret, & certificate Management’ (or choose from other, or configure manually). You also need to add a principal responsible for this policy. Don’t forget to Save Access policies settings.
      You should now be able to access data on Secrets (vertical) tab.
    6. Choose the secret that relates to your bot.
    7. Click Show Secret Value button on bottom of the screen and copy the secret value for reference. We later refer to this secret as MS_BOT_APP_CLIENT_SECRET_VALUE.
  7. (Optional) If you already had a bot secret:
    1. Go to the Microsoft Azure Portal.
    2. Click on your bot name.
    3. Then click Configuration in the left menu.
    4. Click Manage in > Microsoft App ID (Manage).
    5. Click new client secret. Note, if one already exists delete it unless you already have the value, because you can not get it again.
    6. Give it a description, such as “My secret”.
    7. Click add.
      Now your secret value should be visible. Copy and keep it safe as you only get one chance to see its value.