Redigera

Dela via

Enable single sign-on for Teams app

Microsoft Teams provides single sign-on (SSO) function for an app to obtain signed in Teams user token to access Microsoft Graph and other APIs. Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) streamlines the process by incorporating certain Microsoft Entra workflows and integrations into straightforward, high-level APIs. As a result, you can effortlessly incorporate SSO capabilities into your Teams app. For more information, see authenticate users in Microsoft Teams.

Key configurations

To enable SSO, configure your Teams app as follows:

  • Microsoft Entra app manifest: Ensure to define URIs, including the URI that identifies the Microsoft Entra authentication app and the redirect URI that returns the token.

  • Teams app manifest: Connect your SSO app to your Teams app by incorporating the correct configuration.

  • Agents Toolkit configuration and infra files: Ensure the necessary configurations are in place to enable SSO for your Teams app.

  • SSO app information in Agents Toolkit configuration files: Ensure the authentication app registers on the backend service and Agents Toolkit initiates it during the debugging or previewing of the Teams app.

Create Microsoft Entra app manifest

  1. Download the Microsoft Entra app manifest template.

  2. Add the downloaded app manifest template code to ./aad.manifest.json file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see app manifest.

Update Teams app manifest

In the ./appPackages/manifest.json file, add the following code:

"webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
}

webApplicationInfo provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app.

Note

You can use {{ENV_NAME}} to reference variables in env/.env.{TEAMSFX_ENV} file.

Update Agents Toolkit configuration files

  1. Locate your Agents Toolkit configuration files, such as ./m365agents.yml and ./m365agents.local.yml. Update the required configurations related to Microsoft Entra in these files.

  2. Add the aadApp/create action under provision in ./m365agents.yml and ./m365agents.local.yml to create new Microsoft Entra app used for SSO:

    - uses: aadApp/create
  with:
    name: "YOUR_AAD_APP_NAME"
    generateClientSecret: true
    signInAudience: "AzureADMyOrg"
  writeToEnvironmentFile:
      clientId: AAD_APP_CLIENT_ID
      clientSecret: SECRET_AAD_APP_CLIENT_SECRET
      objectId: AAD_APP_OBJECT_ID
      tenantId: AAD_APP_TENANT_ID
      authority: AAD_APP_OAUTH_AUTHORITY

    Note

    Replace the name value with the desired name for your Teams app.

    For more information, see aadApp/create.

  3. Add the aadApp/update action under provision in ./m365agents.yml and ./m365agents.local.yml to update your Microsoft Entra app:

    - uses: aadApp/update
  with:
    manifestPath: "./aad.manifest.json"
    outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json"

    Note

    • Update the manifestPath value to the relative path of the Microsoft Entra app manifest template aad.manifest.json, if you've changed the file's path.
    • In a local setup, position the aad/update after the file/createOrUpdateEnvironmentFile action. This is required because aad/update uses the output from file/createOrUpdateEnvironmentFile.

    For more information, see aadApp/update

  4. For a React project, update cli/runNpmCommand under deploy.

  5. If you're building a tab app using the React framework in CLI, find the cli/runNpmCommand action with build app in the m365agents.yml file and add the following environment variables:

    env:
  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html

  6. If you're building a tab app with React framework, find the file/createOrUpdateEnvironmentFile action for deployment in m365agents.local.yml file and add the following environment variables:

    envs:
  ...
  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html

Update source code

With the above changes implemented, your environment is prepared. You can now update your code to incorporate SSO into your Teams app.

Vanilla JavaScript

For a tab app that doesn't uses React, use the following code as a basic example to obtain the SSO token:

function getSSOToken() {
  return new Promise((resolve, reject) => {
    microsoftTeams.authentication.getAuthToken()
      .then((token) => resolve(token))
      .catch((error) => reject("Error getting token: " + error));
  });
}

function getBasicUserInfo() {
  getSSOToken().then((ssoToken) => {
    const tokenObj = JSON.parse(window.atob(ssoToken.split(".")[1]));
    console.log(`username: ${tokenObj.name}`);
    console.log(`user email: ${tokenObj.preferred_username}`);
  });
}

React

For React projects, ensure the following environment variables are set in your deployment process:

To update your source code, follow these steps:

  1. Move the auth-start.html and auth-end.html files from the auth/public folder to the public/ folder. These HTML files serve the purpose of handling authentication redirects.

  2. Move sso folder under auth/ to src/sso/.

    1. InitTeamsFx: This file executes a function that initializes the TeamsFx SDK. After the SDK initialization, it opens the GetUserProfile component.
    2. GetUserProfile: This file executes a function to retrieve user information by invoking the Microsoft Graph API.

  3. Import and add InitTeamsFx in Welcome.*.

For more information, see SSO enabled tab app.

Debug your app

To debug your app, select the F5 key. Agents Toolkit uses the Microsoft Entra manifest to register an SSO-enabled app. For more information, see debug your Teams app locally.

Customize Microsoft Entra apps

Teams app manifest enables you to customize different aspects of your app registration. You can update the manifest as required.

To include additional API permissions to access your desired APIs, see edit Microsoft Entra manifest.

To view your Microsoft Entra app in Azure portal, see edit Microsoft Entra manifest.

See also