diff --git a/AppCreationScripts/Cleanup.ps1 b/AppCreationScripts/Cleanup.ps1 index e5d183d..dcacb41 100644 --- a/AppCreationScripts/Cleanup.ps1 +++ b/AppCreationScripts/Cleanup.ps1 @@ -1,13 +1,13 @@ [CmdletBinding()] param( [PSCredential] $Credential, - [Parameter(Mandatory=$False, HelpMessage='Tenant ID (This is a GUID which represents the "Directory ID" of the AzureAD tenant into which you want to create the apps')] + [Parameter(Mandatory=$False, HelpMessage='Tenant ID (This is a GUID which represents the "Directory ID" of the Microsoft Entra tenant into which you want to create the apps')] [string] $tenantId, [Parameter(Mandatory=$False, HelpMessage='Azure environment to use while running the script (it defaults to AzureCloud)')] [string] $azureEnvironmentName ) -#Requires -Modules AzureAD +#Requires -Modules Microsoft Entra if ($null -eq (Get-Module -ListAvailable -Name "AzureAD")) { @@ -25,11 +25,11 @@ Function Cleanup <# .Description - This function removes the Azure AD applications for the sample. These applications were created by the Configure.ps1 script + This function removes the Microsoft Entra applications for the sample. These applications were created by the Configure.ps1 script #> - # $tenantId is the Active Directory Tenant. This is a GUID which represents the "Directory ID" of the AzureAD tenant - # into which you want to create the apps. Look it up in the Azure portal in the "Properties" of the Azure AD. + # $tenantId is the Active Directory Tenant. This is a GUID which represents the "Directory ID" of the Microsoft Entra tenant + # into which you want to create the apps. Look it up in the Azure portal in the "Properties" of the Microsoft Entra ID. # Login to Azure PowerShell (interactive if credentials are not already provided: # you'll need to sign-in with creds enabling your to create apps in the tenant) diff --git a/AppCreationScripts/Configure.ps1 b/AppCreationScripts/Configure.ps1 index 3afb779..1c8b053 100644 --- a/AppCreationScripts/Configure.ps1 +++ b/AppCreationScripts/Configure.ps1 @@ -7,16 +7,16 @@ param( [string] $azureEnvironmentName ) -#Requires -Modules AzureAD +#Requires -Modules Microsoft Entra <# - This script creates the Azure AD applications needed for this sample and updates the configuration files - for the visual Studio projects from the data in the Azure AD applications. + This script creates the Microsoft Entra applications needed for this sample and updates the configuration files + for the visual Studio projects from the data in the Microsoft Entra applications. - Before running this script you need to install the AzureAD cmdlets as an administrator. + Before running this script you need to install the Microsoft EntraD cmdlets as an administrator. For this: 1) Run Powershell as an administrator - 2) in the PowerShell window, type: Install-Module AzureAD + 2) in the PowerShell window, type: Install-Module Microsoft Entra There are four ways to run this script. For more information, read the AppCreationScripts.md file in the same folder as this script. #> @@ -162,7 +162,7 @@ Function UpdateTextFile([string] $configFilePath, [System.Collections.HashTable] Set-Content -Path $configFilePath -Value $lines -Force } <#.Description - This function creates a new Azure AD scope (OAuth2Permission) with default and provided values + This function creates a new Microsoft Entra scope (OAuth2Permission) with default and provided values #> Function CreateScope( [string] $value, [string] $userConsentDisplayName, [string] $userConsentDescription, [string] $adminConsentDisplayName, [string] $adminConsentDescription) { @@ -179,7 +179,7 @@ Function CreateScope( [string] $value, [string] $userConsentDisplayName, [string } <#.Description - This function creates a new Azure AD AppRole with default and provided values + This function creates a new Microsoft Entra AppRole with default and provided values #> Function CreateAppRole([string] $types, [string] $name, [string] $description) { @@ -206,7 +206,7 @@ $ErrorActionPreference = "Stop" Function ConfigureApplications { <#.Description - This function creates the Azure AD applications for the sample in the provided Azure AD tenant and updates the + This function creates the Microsoft Entra applications for the sample in the provided Microsoft Entra tenant and updates the configuration files in the client and service project of the visual studio solution (App.Config and Web.Config) so that they are consistent with the Applications parameters #> @@ -217,8 +217,8 @@ Function ConfigureApplications $azureEnvironmentName = "AzureCloud" } - # $tenantId is the Active Directory Tenant. This is a GUID which represents the "Directory ID" of the AzureAD tenant - # into which you want to create the apps. Look it up in the Azure portal in the "Properties" of the Azure AD. + # $tenantId is the Active Directory Tenant. This is a GUID which represents the "Directory ID" of the Microsoft Entra tenant + # into which you want to create the apps. Look it up in the Azure portal in the "Properties" of the Microsoft Entra. # Login to Azure PowerShell (interactive if credentials are not already provided: # you'll need to sign-in with creds enabling your to create apps in the tenant) @@ -251,7 +251,7 @@ Function ConfigureApplications # Get the user running the script to add the user as the app owner $user = Get-AzureADUser -ObjectId $creds.Account.Id - # Create the service AAD application + # Create the service Microsoft Entra application Write-Host "Creating the AAD application (auther-server-sample-webApi)" # Get a 2 years application key for the service Application $pw = ComputePassword @@ -313,7 +313,7 @@ Function ConfigureApplications Write-Host "Done creating the service application auther-server-sample-webApi" - # URL of the AAD application in the Azure portal + # URL of the Microsoft Entra application in the Azure portal # Future? $servicePortalUrl = "https://portal.azure.com/#@"+$tenantName+"/blade/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/Overview/appId/"+$serviceAadApplication.AppId+"/objectId/"+$serviceAadApplication.ObjectId+"/isMSAApp/" $servicePortalUrl = "https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/CallAnAPI/appId/"+$serviceAadApplication.AppId+"/objectId/"+$serviceAadApplication.ObjectId+"/isMSAApp/" Add-Content -Value "service$currentAppIdauther-server-sample-webApi" -Path createdApps.html @@ -331,7 +331,7 @@ Function ConfigureApplications Set-AzureADApplication -ObjectId $serviceAadApplication.ObjectId -RequiredResourceAccess $requiredResourcesAccess Write-Host "Granted permissions." - # Create the client AAD application + # Create the client Microsoft Entra application Write-Host "Creating the AAD application auther-server-sample-webClient" # create the application $clientAadApplication = New-AzureADApplication -DisplayName "auther-server-sample-webClient" ` @@ -355,7 +355,7 @@ Function ConfigureApplications Write-Host "Done creating the client application auther-server-sample-webClient" - # URL of the AAD application in the Azure portal + # URL of the Microsoft Entra application in the Azure portal # Future? $clientPortalUrl = "https://portal.azure.com/#@"+$tenantName+"/blade/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/Overview/appId/"+$clientAadApplication.AppId+"/objectId/"+$clientAadApplication.ObjectId+"/isMSAApp/" $clientPortalUrl = "https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/CallAnAPI/appId/"+$clientAadApplication.AppId+"/objectId/"+$clientAadApplication.ObjectId+"/isMSAApp/" Add-Content -Value "client$currentAppId\auther-server-sample-webClient" -Path createdApps.html diff --git a/AppCreationScripts/README.md b/AppCreationScripts/README.md index 27cf37a..5721cd8 100644 --- a/AppCreationScripts/README.md +++ b/AppCreationScripts/README.md @@ -10,8 +10,8 @@ ```PowerShell Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force ``` -3. Make sure to [install AzureAD PowerShell Modules](#install-azuread-powershell-modules) -4. Run the script to create your Azure Active Directory application and configure the code of the sample application accordingly. (Other ways of running the scripts are described below). Please refer to the **sample.json** file to get an overview of changes. +3. Make sure to [install Microsoft Entra PowerShell Modules](#install-azuread-powershell-modules) +4. Run the script to create your Microsoft Entra application and configure the code of the sample application accordingly. (Other ways of running the scripts are described below). Please refer to the **sample.json** file to get an overview of changes. ```PowerShell cd .\AppCreationScripts\ @@ -25,7 +25,7 @@ If you prefer, you can directly go to the following paragraphs: - [Present the scripts](#presentation-of-the-scripts) and explain their [usage patterns](#usage-pattern-for-tests-and-devops-scenarios) for test and DevOps scenarios. - Explain the [pre-requisites](#pre-requisites) -- [Install AzureAD PowerShell modules](#install-azuread-powershell-modules) +- [Install Microsoft Entra PowerShell modules](#install-azuread-powershell-modules) - Explain [four ways of running the scripts](#four-ways-to-run-the-script): - [Interactively](#option-1-interactive) to create the app in your home tenant - [Passing credentials](#option-2-non-interactive) to create the app in your home tenant @@ -37,24 +37,24 @@ If you prefer, you can directly go to the following paragraphs: ### Presentation of the scripts -This sample comes with two PowerShell scripts, which automate the creation of the Azure Active Directory applications, and the configuration of the code for this sample. Once you run them, you will only need to build the solution and you are good to test. +This sample comes with two PowerShell scripts, which automate the creation of the Microsoft Entra applications, and the configuration of the code for this sample. Once you run them, you will only need to build the solution and you are good to test. These scripts are: - `Configure.ps1` which: - - creates Azure Active Directory applications and their related objects (permissions, dependencies, secrets), + - creates Microsoft Entra applications and their related objects (permissions, dependencies, secrets), - changes the configuration files in the C# WebApi and Test MinimalClient JavaScript projects. - - creates a summary file named `createdApps.html` in the folder from which you ran the script, and containing, for each Azure Active Directory application it created: + - creates a summary file named `createdApps.html` in the folder from which you ran the script, and containing, for each Microsoft Entra application it created: - the identifier of the application - the AppId of the application - the url of its registration in the [Azure portal](https://portal.azure.com). -- `Cleanup.ps1` which cleans-up the Azure Active Directory objects created by `Configure.ps1`. Note that this script does not revert the changes done in the configuration files, though. You will need to undo the change from source control (from Visual Studio, or from the command line using, for instance, git reset). +- `Cleanup.ps1` which cleans-up the Microsoft Entra objects created by `Configure.ps1`. Note that this script does not revert the changes done in the configuration files, though. You will need to undo the change from source control (from Visual Studio, or from the command line using, for instance, git reset). ### Usage pattern for tests and DevOps scenarios -The `Configure.ps1` will stop if it tries to create an Azure Active Directory application which already exists in the tenant. For this, if you are using the script to try/test the sample, or in DevOps scenarios, you might want to run `Cleanup.ps1` just before `Configure.ps1`. This is what is shown in the steps below. +The `Configure.ps1` will stop if it tries to create an Microsoft Entra application which already exists in the tenant. For this, if you are using the script to try/test the sample, or in DevOps scenarios, you might want to run `Cleanup.ps1` just before `Configure.ps1`. This is what is shown in the steps below. ## How to use the app creation scripts? @@ -70,11 +70,11 @@ The `Configure.ps1` will stop if it tries to create an Azure Active Directory ap Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process ``` - ### Install AzureAD PowerShell modules + ### Install Microsoft Entra PowerShell modules - The scripts install the required PowerShell module (AzureAD) for the current user if needed. However, if you want to install it for all users on the machine, you can follow the following steps: + The scripts install the required PowerShell module (Microsoft Entra) for the current user if needed. However, if you want to install it for all users on the machine, you can follow the following steps: -4. If you have never done it already, in the PowerShell window, install the AzureAD PowerShell modules. For this: +4. If you have never done it already, in the PowerShell window, install the Microsoft Entra PowerShell modules. For this: 1. Open PowerShell as admin (On Windows, search **Powershell** in the Search bar, right click on it and select **Run as administrator**). @@ -152,7 +152,7 @@ Of course, in real life, you might already get the password as a `SecureString`. if you want to create the apps in a particular tenant, you can use the following option: - open the [Azure portal](https://portal.azure.com) -- Select the Azure Active Directory you are interested in (in the combo-box below your name on the top right of the browser window) +- Select the Microsoft Entra you are interested in (in the combo-box below your name on the top right of the browser window) - Find the "Active Directory" object in this tenant - Go to **Properties** and copy the content of the **Directory Id** property - Then use the full syntax to run the scripts: diff --git a/AppCreationScripts/sample.json b/AppCreationScripts/sample.json index fda7d8f..f1b5476 100644 --- a/AppCreationScripts/sample.json +++ b/AppCreationScripts/sample.json @@ -1,6 +1,6 @@ { "Sample": { - "Title": "A client application that calls an ASP.NET Core Web API protected by Azure AD using OAuth 2.0 access tokens. ", + "Title": "A client application that calls an ASP.NET Core Web API protected by Microsoft Entra using OAuth 2.0 access tokens. ", "Level": 200, "Client": "SPA client application - UI to test Web Api", "Service": "ASP.NET Core Web API", @@ -9,7 +9,7 @@ }, /* - This section describes the Azure AD Applications to configure, and their dependencies + This section describes the Microsoft Entra Applications to configure, and their dependencies */ "AADApps": [ { @@ -55,7 +55,7 @@ /* This section describes how to update the code in configuration files from the apps coordinates, once the apps - are created in Azure AD. + are created in Microsoft Entra ID. Each section describes a configuration file, for one of the apps, it's type (Javascript, JSon, plain text), its location with respect to the root of the sample, and the mappping (which string in the config file is mapped to which value */ diff --git a/MinimalClient/README.md b/MinimalClient/README.md index 3a5dd72..415ea7b 100644 --- a/MinimalClient/README.md +++ b/MinimalClient/README.md @@ -1,11 +1,11 @@ # React single-page application built with MSAL React and Microsoft identity platform to demonstrate the Azure Communication Services Auth sample -This is a very simple client based on the autogenerated react single page app from the Azure Active Directory registered apps QuickStart. This should not be used for production and serves as a sample to see how the backend can be called. +This is a very simple client based on the autogenerated react single page app from the Microsoft Entra registered apps QuickStart. This should not be used for production and serves as a sample to see how the backend can be called. ## Prerequisites - Backend server set up and running. (If deployed to a non-local environment, modify `SERVER_ADDRESS` in [acsAuthApiCaller.js](../MinimalClient/src/acsAuthApiCaller.js)) -- Single page client app registered on Azure Active Directory. +- Single page client app registered on Microsoft Entra ID. - Populate the [authConfig.js](../MinimalClient/src/authConfig.js) file with the `clientId`, `authority`, and `redirectUri` values from the client app registration. ## Running the client @@ -16,14 +16,14 @@ This is a very simple client based on the autogenerated react single page app fr ## Joining a group call as a Communication Identity -1. Click **Sign in** and use the login dialog to log in with a valid Azure AD identity. -1. Click **Join Default Call** to join a call using the displayed randomly generated GUID, or use the **AAD Access Token** to directly call the backend API. +1. Click **Sign in** and use the login dialog to log in with a valid Microsoft Entra identity. +1. Click **Join Default Call** to join a call using the displayed randomly generated GUID, or use the **Microsoft Entra Access Token** to directly call the backend API. 1. To join a call with another device, share the GUID and enter it in the text box of the client wanting to join the same call. ## Joining a Teams meeting as a Teams user -1. Click **Sign in as a Teams user** then use the login dialog to log in with an Azure AD identity with a valid Teams license. +1. Click **Sign in as a Teams user** then use the login dialog to log in with an Microsoft Entra identity with a valid Teams license. 1. Fill in the **Teams Meeting Link** with the link to the meeting you want to join. 1. Click **Join as a Teams user** to join the specified meeting. -1. Alternatively, you can call the `GET /api/token/teams` endpoint with the AAD Access Token in the `Authorization: Bearer ` header and the AAD Token for a Teams user in the `teams-user-aad-token` header to generate a valid Communication Token. +1. Alternatively, you can call the `GET /api/token/teams` endpoint with the Microsoft Entra Access Token in the `Authorization: Bearer ` header and the Microsoft Entra Token for a Teams user in the `teams-user-aad-token` header to generate a valid Communication Token. 1. Or use the generated **Communication Token** to directly call the Calling API. diff --git a/MinimalClient/src/App.jsx b/MinimalClient/src/App.jsx index fa0ed0d..56b74b2 100644 --- a/MinimalClient/src/App.jsx +++ b/MinimalClient/src/App.jsx @@ -12,8 +12,8 @@ import { TestCallTeamsUserContent } from './components/TestCallTeamsUserContent' import { useSessionStorage } from './reactExtensions'; /** - * If a user is authenticated as a regular Azure AD user, the TestCallContent component is rendered. - * If a user is authenticated as a Azure AD user with a valid teams license, the TestCallTeamsUserContent component is rendered. + * If a user is authenticated as a regular Microsoft Entra user, the TestCallContent component is rendered. + * If a user is authenticated as a Microsoft Entra user with a valid teams license, the TestCallTeamsUserContent component is rendered. * Otherwise a message indicating a user is not authenticated is rendered. */ const MainContent = (props) => { diff --git a/MinimalClient/src/components/TestCallTeamsUserContent.jsx b/MinimalClient/src/components/TestCallTeamsUserContent.jsx index ac2c8bc..67eedf4 100644 --- a/MinimalClient/src/components/TestCallTeamsUserContent.jsx +++ b/MinimalClient/src/components/TestCallTeamsUserContent.jsx @@ -32,7 +32,7 @@ export const TestCallTeamsUserContent = () => { }) .catch((error) => console.log(error)); - // Silently acquires an access token which is then used as a payload for the (AAD->ACS) token exchange + // Silently acquires an access token which is then used as a payload for the (Microsoft Entra ID ->ACS) token exchange const teamsAadToken = await instance .acquireTokenSilent({ ...teamsUserRequest, diff --git a/README.md b/README.md index 68f95a2..33c6f42 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,12 @@ Deploy to Azure using instructions [here](./docs/deployment-guides/deploy-and-te In order to properly implement a secure Azure Communication Services solutions, developers must start by putting in place the correct infrastructure to properly generate user and access token credentials for Azure Communication Services. Azure Communication Services is identity-agnostic, to learn more check out our [conceptual documentation](https://docs.microsoft.com/azure/communication-services/concepts/identity-model). -This repository provides a sample of a server implementation of an authentication service for Azure Communication Services. It uses best practices to build a trusted backend service that issues Azure Communication Services credentials and maps them to Azure Active Directory identities. +This repository provides a sample of a server implementation of an authentication service for Azure Communication Services. It uses best practices to build a trusted backend service that issues Azure Communication Services credentials and maps them to Microsoft Entra identities. This sample can help you in the following scenarios: -1. As a developer, you need to enable an authentication flow for joining native Azure Communication Services and/or Teams Interop calling/chat which is done by mapping an Azure Communication Services identity to an Azure Active Directory identity and using this same Azure Communication Services identity for the user to fetch an Azure Communication Services token in every session. -2. As a developer, you need to enable an authentication flow for the Azure Communication Services support for Teams identities which is done by using an M365 Azure Active Directory identity of a Teams' user to fetch an Azure Communication Services token to be able to join Teams calling/chat. +1. As a developer, you need to enable an authentication flow for joining native Azure Communication Services and/or Teams Interop calling/chat which is done by mapping an Azure Communication Services identity to an Microsoft Entra identity and using this same Azure Communication Services identity for the user to fetch an Azure Communication Services token in every session. +2. As a developer, you need to enable an authentication flow for the Azure Communication Services support for Teams identities which is done by using an M365 Microsoft Entra identity of a Teams' user to fetch an Azure Communication Services token to be able to join Teams calling/chat. If you are looking to get started with Azure Communication Services, but are still in learning / prototyping phases, check out our [quickstarts for getting started with azure communication services users and access tokens](https://docs.microsoft.com/azure/communication-services/quickstarts/access-tokens?pivots=programming-language-csharp). @@ -49,7 +49,7 @@ If you are looking to get started with Azure Communication Services, but are sti Additional documentation for this sample can be found on [Microsoft Docs](https://docs.microsoft.com/azure/communication-services/samples/trusted-auth-sample). -Since this sample only focuses on the server APIs, the client application is not part of it. If you want to add the client application to login user using Azure Active Directory, then please follow the MSAL samples [here](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet). +Since this sample only focuses on the server APIs, the client application is not part of it. If you want to add the client application to login user using Microsoft Entra ID, then please follow the MSAL samples [here](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet). Before contributing to this sample, please read our [contribution guidelines](./CONTRIBUTING.md). @@ -57,7 +57,7 @@ Before contributing to this sample, please read our [contribution guidelines](./ To be able to run this sample, you will need to: -- Register a Client and Server (Web API) applications in Azure Active Directory as part of [On Behalf Of workflow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). Follow instructions on how to [set up App Registrations](./docs/deployment-guides/set-up-app-registrations.md) +- Register a Client and Server (Web API) applications in Microsoft Entra ID as part of [On Behalf Of workflow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). Follow instructions on how to [set up App Registrations](./docs/deployment-guides/set-up-app-registrations.md) - Create an Azure Communication Services resource through [Azure Portal](https://portal.azure.com). Follow [Quickstart: Create and manage Communication Services resources](https://docs.microsoft.com/azure/communication-services/quickstarts/create-communication-resource?tabs=windows&pivots=platform-azp) to create an Azure Communication Services resource using Azure Portal. ## Getting Started @@ -69,7 +69,7 @@ If you're wondering where to get started, here are a few scenarios to help you g - [Azure Communication Services Authentication Server Sample Architecture Design](./docs/design-guides/architecture-overview.md). - [Secured Web API Architecture Design](./docs/design-guides/secured-web-api-design.md). - [Identity Mapping Architecture Design](./docs/design-guides/identity-mapping-design-graph-open-extensions.md). - - [Azure Active Directory Token Exchange Architecture Design](./docs/design-guides/token-exchange-design.md). + - [Microsoft Entra Token Exchange Architecture Design](./docs/design-guides/token-exchange-design.md). * "I want to see what this Azure Communication Services Authentication Server sample can do by running it!" * Check out our [local deployment guide](./docs/deployment-guides/deploy-locally.md) guide. * "I want to submit a fix or a feature for this project" @@ -88,21 +88,21 @@ This Azure Communication Services Solutions - Authentication server sample provi 1. Maximum number of extensions values supported per application is 2. - > An application can add [at most two open extensions](https://docs.microsoft.com/graph/extensibility-overview#open-extension-limits) for an Azure Active Directory user. + > An application can add [at most two open extensions](https://docs.microsoft.com/graph/extensibility-overview#open-extension-limits) for an Microsoft Entra user. - > **Resolution:** If more than 2 extensions are required, then Graph Open Extensions cannot be used to persist the Azure Communication Services Identity mapping as in the sample. You need to consider Alternative Identity Mapping as suggested in [Architecture Overview](./docs/design-guides/architecture-overview.md). Otherwise, you can delete the extensions following [Graph Open Extensions Delete API](https://docs.microsoft.com/graph/extensibility-open-users#4-delete-a-users-roaming-profile). You can delete the extension for any user, if you are M365 Tenant/Azure Active Directory Admin. You can use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) to execute for a single user. + > **Resolution:** If more than 2 extensions are required, then Graph Open Extensions cannot be used to persist the Azure Communication Services Identity mapping as in the sample. You need to consider Alternative Identity Mapping as suggested in [Architecture Overview](./docs/design-guides/architecture-overview.md). Otherwise, you can delete the extensions following [Graph Open Extensions Delete API](https://docs.microsoft.com/graph/extensibility-open-users#4-delete-a-users-roaming-profile). You can delete the extension for any user, if you are M365 Tenant/Microsoft Entra Admin. You can use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) to execute for a single user. 2. Provided identity doesn't belong to the resource. > This issue happens if there is mismatch of Azure Communication Services Identity persisted within Graph Open Extensions user instance and the Azure Communication Services resource. > - > The scenario would happen when the Azure Communication Service Identity mapping for a Azure Active Directory user account was created with one Azure Communication Services resource in the deployed sample and the Azure Communication Services resource changed with subsequent deployments. + > The scenario would happen when the Azure Communication Service Identity mapping for a Microsoft Entra user account was created with one Azure Communication Services resource in the deployed sample and the Azure Communication Services resource changed with subsequent deployments. > **Resolution:** Swap the Azure Communication Services resource used in the deployed sample as was used in prior deployment. Otherwise delete the extension within Graph Open extensions using the resolution step for above issue. -3. For troubleshooting Azure Active Directory Token issues, please refer to [Troubleshoot Azure Active Directory Token](https://docs.microsoft.com/azure/databricks/dev-tools/api/latest/aad/troubleshoot-aad-token). +3. For troubleshooting Microsoft Entra Token issues, please refer to [Troubleshoot Microsoft Entra Token](https://docs.microsoft.com/azure/databricks/dev-tools/api/latest/aad/troubleshoot-aad-token). -4. For troubleshooting consent issues during Azure Active Directory authentication flow, please refer to [Unexpected user consent error](https://docs.microsoft.com/azure/active-directory/manage-apps/application-sign-in-unexpected-user-consent-error#requesting-not-authorized-permissions-error), [Unexpected user consent prompt](https://docs.microsoft.com/azure/active-directory/manage-apps/application-sign-in-unexpected-user-consent-prompt). +4. For troubleshooting consent issues during Microsoft Entra authentication flow, please refer to [Unexpected user consent error](https://docs.microsoft.com/azure/active-directory/manage-apps/application-sign-in-unexpected-user-consent-error#requesting-not-authorized-permissions-error), [Unexpected user consent prompt](https://docs.microsoft.com/azure/active-directory/manage-apps/application-sign-in-unexpected-user-consent-prompt). ### Application Troubleshooting diff --git a/docs/README.md b/docs/README.md index 3a346b5..d75b98f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,6 @@ Not sure how to register your apps on Azure? Checkout our [app registrations set - [Architecture Overview](design-guides/architecture-overview.md) - Overview of the Azure Communication Services Authentication Server sample design. - [Endpoints and Responses](design-guides/endpoints-and-responses.md) - What are the endpoints and responses of the Azure Communication Services Authentication Server sample. -- [Identity Mapping Design](design-guides/identity-mapping-design-graph-open-extensions.md) - How to utilize the **Microsoft Graph Open Extensions** to manage Azure Communication Services identities by mapping them 1:1 with Azure Active Directory identities. +- [Identity Mapping Design](design-guides/identity-mapping-design-graph-open-extensions.md) - How to utilize the **Microsoft Graph Open Extensions** to manage Azure Communication Services identities by mapping them 1:1 with Microsoft Entra identities. - [Secured Web API Design](./design-guides/secured-web-api-design.md) - How to protect Web API using the **Authentication Code Grant flow** (Client side excluded from the project) and secure an access token from the Microsoft identity platform using the **On-Behalf-Of flow** (Server side) to make authenticated requests to the downstream services. -- [Token Exchange Design](./design-guides/token-exchange-design.md) - Overview on how the authentication and Azure Active Directory token exchange flow should be implemented using Azure Communication Services sdk to enable M365 users to join Teams meeting as authenticated Team users. +- [Token Exchange Design](./design-guides/token-exchange-design.md) - Overview on how the authentication and Microsoft Entra token exchange flow should be implemented using Azure Communication Services sdk to enable M365 users to join Teams meeting as authenticated Team users. diff --git a/docs/deployment-guides/deploy-and-test-sample-on-azure.md b/docs/deployment-guides/deploy-and-test-sample-on-azure.md index 37d2e81..ad2d6f7 100644 --- a/docs/deployment-guides/deploy-and-test-sample-on-azure.md +++ b/docs/deployment-guides/deploy-and-test-sample-on-azure.md @@ -13,17 +13,17 @@ 3. When the deployment is completed successfully, a few configurations need to be updated on Application settings within Azure App Service using the information from server app registration. You can refer to the [Configure Common Settings page](https://docs.microsoft.com/azure/app-service/configure-common?tabs=portal) to update Application settings within Azure App Service. Edit the values of following keys by visiting the server app registration: - > **Note** If you created the app regsitrations using scripts, then the `AzureActiveDirectory` configuration values could be found from **src/appsettings.json** file within your locally cloned repository. + > **Note** If you created the app regsitrations using scripts, then the `Microsoft Entra` configuration values could be found from **src/appsettings.json** file within your locally cloned repository. - - `AzureActiveDirectory__ClientId`: "" + - `MicrosoftEntra__ClientId`: "" - - `AzureActiveDirectory__ClientSecret`: "" + - `MicrosoftEntra__ClientSecret`: "" - - `AzureActiveDirectory__TenantId`: "" + - `MicrosoftEntra__TenantId`: "" - Record the value of `CommunicationServices__ConnectionString` from automatically created Azure Communication Services resource after first deployment to use for subsequent deployments, if you plan to deploy the sample through Azure Resource Manager Template multiple times. - > :bangbang: For the multiple deployments of the sample, there could be an error of "mismatched Azure Communication Services Identity not belonging to the Azure Communication Services resource" while invoking `/api/token` or `/api/user` endpoints and using same Azure Active Directory user account for signing in on client side. The issue would happen since the Azure Communication Services Identity is specific to an Azure Communication Services resource. So if a different Azure Communication Services resource is used within subsequent deployments (**Note:** The aforementioned Azure Resource Manager template deployment always creates new resources including Azure Communication Services), the persisted Azure Communication Services Identity within Azure Active Directory user instance will not match the Azure Communication Services resource for Azure Active Directory user account. For more information regarding Identity Mapping you can visit [Identity Mapping Design](../design-guides/identity-mapping-design-graph-open-extensions.md). **So, please make sure to use the `ConnectionString` from the same Azure Communication Services in all the deployments if using the same Azure Active Directory instance to sign in**. + > :bangbang: For the multiple deployments of the sample, there could be an error of "mismatched Azure Communication Services Identity not belonging to the Azure Communication Services resource" while invoking `/api/token` or `/api/user` endpoints and using same Microsoft Entra user account for signing in on client side. The issue would happen since the Azure Communication Services Identity is specific to an Azure Communication Services resource. So if a different Azure Communication Services resource is used within subsequent deployments (**Note:** The aforementioned Azure Resource Manager template deployment always creates new resources including Azure Communication Services), the persisted Azure Communication Services Identity within Microsoft Entra user instance will not match the Azure Communication Services resource for Microsoft Entra user account. For more information regarding Identity Mapping you can visit [Identity Mapping Design](../design-guides/identity-mapping-design-graph-open-extensions.md). **So, please make sure to use the `ConnectionString` from the same Azure Communication Services in all the deployments if using the same Microsoft Entra instance to sign in**. **Recommendations** @@ -32,7 +32,7 @@ 2. You can also follow the Troubleshooting section on [README](../../README.md) to resolve the issue of Mismatched Azure Communication Services Identity and Azure Communication Services resource. 3. We have two ways of testing the backend service - - Calling the backend APIs directly with an Azure Active Directory Access Token + - Calling the backend APIs directly with an Microsoft Entra Access Token - Using the MinimalClient Please see the two options in detail here. [Test backend service](../test-tools/test-backend-service.md). diff --git a/docs/deployment-guides/deploy-locally.md b/docs/deployment-guides/deploy-locally.md index 3caaa37..88e28ce 100644 --- a/docs/deployment-guides/deploy-locally.md +++ b/docs/deployment-guides/deploy-locally.md @@ -73,7 +73,7 @@ To be able to run this sample locally, you will first need to follow those [prer Before running the sample, you will need to replace the values in the `appsettings.json` file: 1. Replace `connectionString` and `scopes` for the Communication Services -2. Replace `clientId`, `tenantId` and `clientSecret` for the Azure Active Directory. +2. Replace `clientId`, `tenantId` and `clientSecret` for the Microsoft Entra ID. >**Note:** Values of `clientId`, `tenantId` and `clientSecret` are all from your `auther-server-sample-webApi`. If you created the app registrations in [prerequisites](#prerequisites-to-run-the-sample) using app creation scripts, then you should already have these values updated in your local repository. @@ -98,7 +98,7 @@ In order to run the Azure Communication Services Authentication Server sample, > Note: You can also run the selected project using the Visual Studio. 3. We have two ways of testing the backend service - - Calling the backend APIs directly with an Azure Active Directory Access Token + - Calling the backend APIs directly with an Microsoft Entra Access Token - Using the MinimalClient Please see the two options in detail here. [Test backend service](../test-tools/test-backend-service.md). @@ -106,6 +106,8 @@ In order to run the Azure Communication Services Authentication Server sample, Here is a set of endpoints that can be tested. [API Endpoints](../design-guides/endpoints-and-responses.md). -4. During local development/testing, if the identity mapping needs to be verified in Graph for `/api/user` and `/api/token` endpoint, please use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). Sign in with your Azure Active Directory Identity and verify the response on GET `https://graph.microsoft.com/v1.0/me/extensions` endpoint. +4. During local development/testing, if the identity mapping needs to be verified in Graph for `/api/user` and `/api/token` endpoint, please use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer). Sign in with your Microsoft Entra Identity and verify the response on GET `https://graph.microsoft.com/v1.0/me/extensions` endpoint. >**Note:** Want to contribute to this sample and help us make it even better? Check our [contribution guide](../contribution-guides/1.get-set-up.md). + + diff --git a/docs/deployment-guides/set-up-app-registrations.md b/docs/deployment-guides/set-up-app-registrations.md index 1412db1..36cc5af 100644 --- a/docs/deployment-guides/set-up-app-registrations.md +++ b/docs/deployment-guides/set-up-app-registrations.md @@ -14,13 +14,13 @@ git clone https://github.com/Azure-Samples/communication-services-authentication git clone git@github.com:Azure-Samples/communication-services-authentication-hero-csharp.git ``` -Once the script is run in local environment following the [instructions](../../AppCreationScripts/README.md), the `AzureActiveDirectory` fields are updated in **src/appsettings.json** from service app registration and `msalConfig.auth` fields are updated in **MinimalClient/src/authConfig.js** from client app registration in the cloned repository. +Once the script is run in local environment following the [instructions](../../AppCreationScripts/README.md), the `Microsoft Entra` fields are updated in **src/appsettings.json** from service app registration and `msalConfig.auth` fields are updated in **MinimalClient/src/authConfig.js** from client app registration in the cloned repository. ## Set up App Registrations manually ### Server App Registration -Follow below instructions on how to register your server application with Azure Active Directory [here](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app). +Follow below instructions on how to register your server application with Microsoft Entra ID [here](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app). 1. When registering your server app, use the following information: - give your application a meaningful name as this will be the displayed name of your app, for example `auther-server-sample-webApi`. @@ -47,7 +47,7 @@ Follow below instructions on how to register your server application with Azure 4. On the permission list, scroll to **User** group and expand it, then check **User.Read** and **User.ReadWrite.All**. 5. Now click on the **Add permissions** button at the bottom to save your permissions. 6. Once the permissions are added, click on **Grant admin consent** for the Microsoft Graph API call. - >**Note:** The 'Grant admin consent' step can only be performed by your Azure Active Directory Admin. + >**Note:** The 'Grant admin consent' step can only be performed by your Microsoft Entra Admin. 3. Navigate to and click on the **Expose an API** menu item on the left to open the page where you can declare the parameters to expose this app as an API from which client applications can obtain the [access tokens](https://docs.microsoft.com/azure/active-directory/develop/access-tokens). @@ -74,15 +74,15 @@ Follow below instructions on how to register your server application with Azure ### Client App Registration ->**Note** - This client app registration will be used to manually generate the Azure Active Directory Token required to call Azure Active Directory protected Web API as there is no client application in the sample. +>**Note** - This client app registration will be used to manually generate the Microsoft Entra Token required to call Microsoft Entra protected Web API as there is no client application in the sample. -Follow instructions on how to register your client application with Azure Active Directory [here](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app). +Follow instructions on how to register your client application with Microsoft Entra [here](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app). 1. When registering your client app, use the following information: - give your application a meaningful name as this will be the displayed name of your app, for example `auther-server-sample-webClient`. - select the **Accounts in this organizational directory only ( only - Single tenant)** option for who can use or access this application. - - set the **Redirect URI (optional)** with **Single-page Application (SPA)** as platform and `http://localhost:3000/` as URI. In case of manual generation of Azure Active Directory token for testing Auth Sample Apis, select **Web** as platform instead of **SPA**. + - set the **Redirect URI (optional)** with **Single-page Application (SPA)** as platform and `http://localhost:3000/` as URI. In case of manual generation of Microsoft Entra token for testing Auth Sample Apis, select **Web** as platform instead of **SPA**. >**Note:** clicking on the **Register** button will open your application page once the registration is sucessful. diff --git a/docs/design-guides/architecture-overview.md b/docs/design-guides/architecture-overview.md index d03822b..017033b 100644 --- a/docs/design-guides/architecture-overview.md +++ b/docs/design-guides/architecture-overview.md @@ -11,33 +11,33 @@ - [Other Helpful Links to Explore](#other-helpful-links-to-explore) ## Overview -This sample is primarily focused on building a Trusted Service for Azure Communication Services authentication. It is the Azure Communication Services Authentication Backend Server backed by Azure Active Directory as the Identity Provider and using open source libraries from [Microsoft Identity Platform](https://docs.microsoft.com/azure/active-directory/develop/v2-overview). The sample can be used directly if the below conditions are met, otherwise the sample needs to be adapted as described in our [Guidance section](#guidance): +This sample is primarily focused on building a Trusted Service for Azure Communication Services authentication. It is the Azure Communication Services Authentication Backend Server backed by Microsoft Entra as the Identity Provider and using open source libraries from [Microsoft Identity Platform](https://docs.microsoft.com/azure/active-directory/develop/v2-overview). The sample can be used directly if the below conditions are met, otherwise the sample needs to be adapted as described in our [Guidance section](#guidance): - The sample supports single tenant use case. - >**Note:** You can verify the configuration through app registration used for user sign in flow for Azure Active Directory instance. Go to the specific app registration within Azure Active Directory through [Azure Portal](https://portal.azure.com/) and check the Authentication tab to verify the tenancy configuration. + >**Note:** You can verify the configuration through app registration used for user sign in flow for Microsoft Entra instance. Go to the specific app registration within Microsoft Entra through [Azure Portal](https://portal.azure.com/) and check the Authentication tab to verify the tenancy configuration. -- The sample only supports 1:1 identity mapping between Azure Active Directory user Id and Azure Communication Services user Id. +- The sample only supports 1:1 identity mapping between Microsoft Entra user Id and Azure Communication Services user Id. ## Components ![Diagram](../images/ACS-Authentication-Server-Sample_Overview-Flow.png) As seen from the overview diagram, the key components of the sample are: -1. [Secure Web API backed by Azure Active Directory](./secured-web-api-design.md) +1. [Secure Web API backed by Microsoft Entra](./secured-web-api-design.md) 2. [Identity Mapping leveraging Graph Open Extensions](./identity-mapping-design-graph-open-extensions.md) 3. Azure Communication Identity service which generates an Azure Communication Services identity and access tokens. The sample uses the [Azure Communication Services Identity SDK](https://docs.microsoft.com/azure/communication-services/concepts/sdk-options#sdks). ->**Note:** The `api/token/teams` endpoint does not leverage #2, as the M365 Azure Active Directory Identity is internally mapped to user's Teams Identity within Azure Communication Services, see [Communication for Teams identities documentation](https://docs.microsoft.com/azure/communication-services/concepts/teams-endpoint). +>**Note:** The `api/token/teams` endpoint does not leverage #2, as the M365 Microsoft Entra Identity is internally mapped to user's Teams Identity within Azure Communication Services, see [Communication for Teams identities documentation](https://docs.microsoft.com/azure/communication-services/concepts/teams-endpoint). ### Motivation for leveraging Graph Open Extensions for Identity Mapping -The Azure Communication Services identity for the user could be co-located with the information for the Azure Active Directory user. This optimizes the complexity to maintain additional storage to keep mappings and instead enables developers to keep everything inside of Azure Active Directory. +The Azure Communication Services identity for the user could be co-located with the information for the Microsoft Entra user. This optimizes the complexity to maintain additional storage to keep mappings and instead enables developers to keep everything inside of Microsoft Entra ID. ## Limitations -- An application can add [at most two open extensions](https://docs.microsoft.com/graph/extensibility-overview#open-extension-limits) for an Azure Active Directory user. +- An application can add [at most two open extensions](https://docs.microsoft.com/graph/extensibility-overview#open-extension-limits) for an Microsoft Entra user. - Graph Open Extensions have a [rate limit](https://docs.microsoft.com/graph/throttling#open-and-schema-extensions-service-limits) of 455 requests per 10 seconds. ## Guidance -1. If 1:1 identity model of Azure Active Directory and Azure Communication Services in the sample does not meet your requirement, then you can consider adapting the [IdentityMappingModel class](https://github.com/Azure-Samples/communication-services-authentication-hero-csharp/blob/main/src/Models/IdentityMappingModel.cs) to handle multiple identity mappings. +1. If 1:1 identity model of Microsoft Entra and Azure Communication Services in the sample does not meet your requirement, then you can consider adapting the [IdentityMappingModel class](https://github.com/Azure-Samples/communication-services-authentication-hero-csharp/blob/main/src/Models/IdentityMappingModel.cs) to handle multiple identity mappings. 2. Since Azure Communication Services is a data processor and you are the controller of the user data, you are responsible for ensuring the data privacy compliance. To learn more, please visit [Azure Communication Services privacy concept](https://docs.microsoft.com/azure/communication-services/concepts/privacy). -3. **For information of the users:** When the Azure Active Directory instance is used for 3rd party application sign in with [delegated permissions granted over Graph API](https://docs.microsoft.com/graph/auth/auth-concepts#delegated-and-application-permissions), the 3rd Party application with delegated permissions as `user.read` would also have access to the Azure Communication Services user Id persisted as open extension data of the user. This scenario is possible only if the sample is adapted for Multi Tenancy. -4. You as users of the sample would be data controllers of Azure Communication Services Identity and are hence responsible for handling GDPR compliance. The sample has `api/user` endpoints for user management and is provided as a way to handle Azure Communication Services Identity in the appropriate context. The DELETE `api/user` in sample for an example is responsible for deleting the Azure Communication Services Identity mapping in the Azure Active Directory. +3. **For information of the users:** When the Microsoft Entra instance is used for 3rd party application sign in with [delegated permissions granted over Graph API](https://docs.microsoft.com/graph/auth/auth-concepts#delegated-and-application-permissions), the 3rd Party application with delegated permissions as `user.read` would also have access to the Azure Communication Services user Id persisted as open extension data of the user. This scenario is possible only if the sample is adapted for Multi Tenancy. +4. You as users of the sample would be data controllers of Azure Communication Services Identity and are hence responsible for handling GDPR compliance. The sample has `api/user` endpoints for user management and is provided as a way to handle Azure Communication Services Identity in the appropriate context. The DELETE `api/user` in sample for an example is responsible for deleting the Azure Communication Services Identity mapping in the Microsoft Entra. 5. The sample does not have support for application logging. If you need to enable logging and telemetry on production, please refer to [Logging in .Net Core and ASP.Net core](https://docs.microsoft.com/aspnet/core/fundamentals/logging/?view=aspnetcore-6.0) and [Toubleshoot Diagnostic Logs](https://docs.microsoft.com/azure/app-service/troubleshoot-diagnostic-logs). You can still troubleshoot the Api errors even if logging is not suported in sample, please refer to [Application Toubleshooting](../../README.md#application-troubleshooting) section. ## Alternate Identity Mapping Approach diff --git a/docs/design-guides/endpoints-and-responses.md b/docs/design-guides/endpoints-and-responses.md index 8102e16..983c5ef 100644 --- a/docs/design-guides/endpoints-and-responses.md +++ b/docs/design-guides/endpoints-and-responses.md @@ -13,8 +13,8 @@ The `user` endpoint consists of three operations: The `token` endpoint only consists of two operations: 1. **GET /api/token** - Get / refresh an Azure Communication Services token for an Azure Communication Services user. -2. [**GET /api/token/teams**](./token-exchange-design.md) - Exchange an Azure Active Directory token of a M365 user for an Azure Communication Services token. +2. [**GET /api/token/teams**](./token-exchange-design.md) - Exchange an Microsoft Entra token of a M365 user for an Azure Communication Services token. -> :information_source: Teams users are authenticated via the MSAL library against Azure Active Directory in the client application. Authentication tokens are exchanged for Microsoft 365 Teams token via the Azure Communication Services Identity SDK. Developers are encouraged to implement an exchange of tokens in their backend services as exchange requests are signed by credentials for Azure Communication Services. In backend services, developers can require any additional authentication. Learn more [here](https://docs.microsoft.com/azure/communication-services/concepts/teams-interop#microsoft-365-teams-identity). +> :information_source: Teams users are authenticated via the MSAL library against Microsoft Entra ID in the client application. Authentication tokens are exchanged for Microsoft 365 Teams token via the Azure Communication Services Identity SDK. Developers are encouraged to implement an exchange of tokens in their backend services as exchange requests are signed by credentials for Azure Communication Services. In backend services, developers can require any additional authentication. Learn more [here](https://docs.microsoft.com/azure/communication-services/concepts/teams-interop#microsoft-365-teams-identity). ![Identity Mapping - Disassembly Diagram](../images/ACS-Authentication-Server-sample_Identity-Mapping_Disassembly-Diagram.png) diff --git a/docs/design-guides/identity-mapping-design-graph-open-extensions.md b/docs/design-guides/identity-mapping-design-graph-open-extensions.md index 931d6d5..df3de23 100644 --- a/docs/design-guides/identity-mapping-design-graph-open-extensions.md +++ b/docs/design-guides/identity-mapping-design-graph-open-extensions.md @@ -4,7 +4,7 @@ - [Scenario](#scenario) - [Overview](#overview) -- [1:1 Azure Communication Services Identity and Azure Active Directory user Identity mapping](#11-azure-communication-services-identity-and-azure-active-directory-user-identity-mapping) +- [1:1 Azure Communication Services Identity and Microsoft Entra user Identity mapping](#11-azure-communication-services-identity-and-azure-active-directory-user-identity-mapping) - [Contributing](#contributing) - [More Information](#more-information) @@ -14,11 +14,11 @@ The sample solution focuses on token management for below use cases: - Joining the native Azure Communication Services Chat, Calling / Teams Interop Meetings - Joining the Teams meeting as Authenticated Team's user -The first scenario requires the identity mapping solution leveraged in `/token` and `/user` endpoints (endpoints implemented to support only the first scenario). The Azure Communication Services identity is mapped to Azure Active Directory user instance, so that the same Azure Communication Services identity for the user can be used in multiple sessions. Please refer to the [Azure Communication Services Identity Model](https://docs.microsoft.com/azure/communication-services/concepts/identity-model) +The first scenario requires the identity mapping solution leveraged in `/token` and `/user` endpoints (endpoints implemented to support only the first scenario). The Azure Communication Services identity is mapped to Microsoft Entra user instance, so that the same Azure Communication Services identity for the user can be used in multiple sessions. Please refer to the [Azure Communication Services Identity Model](https://docs.microsoft.com/azure/communication-services/concepts/identity-model) ## Overview -This sample solution demonstrates how to use Microsoft Graph open extensions as the solution of identity mapping storage to build trusted backend service that will manage Azure Communication Services identities by mapping them 1:1 with Azure Active Directory identities (for Teams Interop or native Azure Communication Services calling/chat) and issue Azure Communication Services tokens. For a Azure Active Directory user account, only a single Azure Communication Services Identity specific to a Azure Communication Services resource will be mapped. The Azure Communication Services Identity mapping cannot be updated once written through the sample. However, it is possible to reset the identity mapping of Azure Active Directory account to a different Azure Communication Services Identity by using DELETE `/api/user` endpoint and then recreating the user mapping using POST `/api/user thereafter. +This sample solution demonstrates how to use Microsoft Graph open extensions as the solution of identity mapping storage to build trusted backend service that will manage Azure Communication Services identities by mapping them 1:1 with Microsoft Entra identities (for Teams Interop or native Azure Communication Services calling/chat) and issue Azure Communication Services tokens. For a Microsoft Entra user account, only a single Azure Communication Services Identity specific to a Azure Communication Services resource will be mapped. The Azure Communication Services Identity mapping cannot be updated once written through the sample. However, it is possible to reset the identity mapping of Microsoft Entra account to a different Azure Communication Services Identity by using DELETE `/api/user` endpoint and then recreating the user mapping using POST `/api/user thereafter. >**Note:** > 1. Developers should not use extensions to store sensitive personally identifiable information, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information. @@ -33,7 +33,7 @@ This sample solution demonstrates how to use Microsoft Graph open extensions as ![ Azure Communication Services Authentication Server - Identity Mapping Flow](../images/ACS-Authentication-Server-Sample_Identity-Mapping-Flow.png) -## 1:1 Azure Communication Services Identity and Azure Active Directory user Identity mapping +## 1:1 Azure Communication Services Identity and Microsoft Entra user Identity mapping As displayed in the Azure Communication Services Authentication Server - Identity Mapping overview sequence diagram below, the identity mapping part consists of two endpoints - `/user` and `/token` @@ -59,4 +59,3 @@ For more information, visit the following links: - [Microsoft Graph Extensions Overview](https://docs.microsoft.com/graph/extensibility-overview) - [Add custom data to users using open extensions](https://docs.microsoft.com/graph/extensibility-open-users) - [Microsoft Graph Extensions Known Limitations](https://docs.microsoft.com/graph/known-issues#extensions) - \ No newline at end of file diff --git a/docs/design-guides/secured-web-api-design.md b/docs/design-guides/secured-web-api-design.md index 8397ddb..e560af9 100644 --- a/docs/design-guides/secured-web-api-design.md +++ b/docs/design-guides/secured-web-api-design.md @@ -12,11 +12,11 @@ ## Scenario -In this Azure Communication Services Authentication Server sample, we would protect custom Web APIs using the Microsoft Identity Platform. The Web API, supporting authenticated users with personal Microsoft accounts as well as work and school accounts, will be protected using Azure Active Directory OAuth Bearer Authorization. Further on the API will also call a downstream API (Microsoft Graph) on-behalf of the signed-in user to provide additional value to its apps. +In this Azure Communication Services Authentication Server sample, we would protect custom Web APIs using the Microsoft Identity Platform. The Web API, supporting authenticated users with personal Microsoft accounts as well as work and school accounts, will be protected using Microsoft Entra OAuth Bearer Authorization. Further on the API will also call a downstream API (Microsoft Graph) on-behalf of the signed-in user to provide additional value to its apps. ## Overview -This sample demonstrates how to call a ASP.Net core Web API, protected by [Azure Active Directory](https://azure.microsoft.com/services/active-directory/) using the [OAuth 2.0 Authorization Code Grant flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow). The web API then calls the [Microsoft Graph API](https://developer.microsoft.com/graph) using the [OAuth 2.0 On-Behalf-Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). The web API's call to Microsoft Graph is made using the [Microsoft Graph SDK](https://docs.microsoft.com/graph/sdks/sdks-overview). +This sample demonstrates how to call a ASP.Net core Web API, protected by [Microsoft Entra ID](https://azure.microsoft.com/services/active-directory/) using the [OAuth 2.0 Authorization Code Grant flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow). The web API then calls the [Microsoft Graph API](https://developer.microsoft.com/graph) using the [OAuth 2.0 On-Behalf-Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). The web API's call to Microsoft Graph is made using the [Microsoft Graph SDK](https://docs.microsoft.com/graph/sdks/sdks-overview). > Developers who wish to become more familiar with programming using Microsoft Graph are advised to go through the [An introduction to Microsoft Graph for developers](https://www.youtube.com/watch?v=EBbnpFdB92A) recorded session, and also make requests and see responses against the Microsoft Graph using [Microsoft Graph explorer](https://developer.microsoft.com/graph/graph-explorer). @@ -33,7 +33,7 @@ As displayed in the Azure Communication Services Authentication Server flow diag **Server Side (Steps 3&4 in below dagram):** -1. Once the user is authorized passing the Azure Active Directory token (as would be gained on client side) in Authorization Header of the API call request, the flow acquires another access token on behalf of the signed-in user using the [On-Behalf-Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). +1. Once the user is authorized passing the Microsoft Entra token (as would be gained on client side) in Authorization Header of the API call request, the flow acquires another access token on behalf of the signed-in user using the [On-Behalf-Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). 2. The Web API then uses this new access token to call downstream APIs (Microsoft Graph in this sample). ![OBO Flow](../images/ACS-Authentication-Server-Sample_Secured-Web-API-Flow.png) @@ -117,4 +117,4 @@ For more information, visit the following links: - [Tutorial: Sign in users and call the Microsoft Graph API from a JavaScript single-page app (SPA) using auth code flow](https://docs.microsoft.com/azure/active-directory/develop/tutorial-v2-javascript-auth-code) - [Microsoft identity platform - OAuth 2.0 On-Behalf-Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow) - [Microsoft Authentication Library (MSAL) for .NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/master/README.md) - - [Microsoft identity platform code samples](https://docs.microsoft.com/azure/active-directory/develop/sample-v2-code) \ No newline at end of file + - [Microsoft identity platform code samples](https://docs.microsoft.com/azure/active-directory/develop/sample-v2-code) diff --git a/docs/design-guides/token-exchange-design.md b/docs/design-guides/token-exchange-design.md index 50e6080..e10617e 100644 --- a/docs/design-guides/token-exchange-design.md +++ b/docs/design-guides/token-exchange-design.md @@ -14,7 +14,7 @@ As you may know, Azure Communication Services SDKs has the ability to allow deve ## Overview -In this Azure Communication Services Authentication Server sample, we would describe how developers can authenticate a Microsoft 365 user by using the Microsoft Authentication Library (MSAL) and retrieving a Microsoft Azure Active Directory (Azure AD) user token. They will then exchange that token for an access token of Teams user with the Azure Communication Services Identity SDK. The access token for Teams user can then be used by the Communication Services Calling SDK. +In this Azure Communication Services Authentication Server sample, we would describe how developers can authenticate a Microsoft 365 user by using the Microsoft Authentication Library (MSAL) and retrieving a Microsoft Microsoft Entra user token. They will then exchange that token for an access token of Teams user with the Azure Communication Services Identity SDK. The access token for Teams user can then be used by the Communication Services Calling SDK. In a production environment, it's necessary that you implement this exchange mechanism in a back-end service, because requests for an exchange are signed with a secret. @@ -22,8 +22,8 @@ In a production environment, it's necessary that you implement this exchange mec As displayed in the Azure Communication Services Authentication Server - Token Exchange flow diagram below, the **Token Exchange for single tenant** includes two steps: -1. From the **Client side**, the developer configures the Microsoft Authentication Library (MSAL) to authenticate the Microsoft 365 user using the client application registration that should have been created earlier using [application creation steps](../deployment-guides/set-up-app-registrations.md). This client app registration should have Azure Communication Services **Teams.ManageCalls** and **Teams.ManageChats** permissions and these should have been **granted admin consent**, in order to obtain Microsoft Azure Active Directory (Azure AD) user tokens using **Authorization Code Grant flow**. The [MinimalClient](../../MinimalClient/README.md) added in the sample for testing the backend service APIs with UI, demonstrates the authentication flow using client app registration. -2. From the **Server side**, the developer initializes the **Azure Communication Services Identity SDK** and exchanges the incoming Azure Active Directory user token for the access token of Teams user via the identity SDK. The access token of Teams user is then returned to the client application. In the sample, the `/api/token/teams` implements the suggested server side logic. +1. From the **Client side**, the developer configures the Microsoft Authentication Library (MSAL) to authenticate the Microsoft 365 user using the client application registration that should have been created earlier using [application creation steps](../deployment-guides/set-up-app-registrations.md). This client app registration should have Azure Communication Services **Teams.ManageCalls** and **Teams.ManageChats** permissions and these should have been **granted admin consent**, in order to obtain Microsoft Entra user tokens using **Authorization Code Grant flow**. The [MinimalClient](../../MinimalClient/README.md) added in the sample for testing the backend service APIs with UI, demonstrates the authentication flow using client app registration. +2. From the **Server side**, the developer initializes the **Azure Communication Services Identity SDK** and exchanges the incoming Microsoft Entra user token for the access token of Teams user via the identity SDK. The access token of Teams user is then returned to the client application. In the sample, the `/api/token/teams` implements the suggested server side logic. ![Token Exchange flow](../images/ACS-Authentication-Server-Sample_Token-Exchange-Flow.png) diff --git a/docs/test-tools/generate-aad-token-manually.md b/docs/test-tools/generate-aad-token-manually.md index 9ee0354..ad7633b 100644 --- a/docs/test-tools/generate-aad-token-manually.md +++ b/docs/test-tools/generate-aad-token-manually.md @@ -1,4 +1,4 @@ -# Manually generating Azure Active Directory Token to test secure Azure Communication Services Authentication Server Sample Apis +# Manually generating Microsoft Entra Token to test secure Azure Communication Services Authentication Server Sample Apis **Attention:** Before using this testing approach, please navigate to `auther-server-sample-webClient` app registration on [Azure Portal](https://portal.azure.com); further navigate to **Manifest** and make sure that `replyUrlsWithType[].type` is set to `Web`. If not updated, please update it. @@ -6,7 +6,7 @@ The client app in those requests generally refers the client app registration. You can get the `` from the app registration **Overview** page as well. You can get the `` by navigating to **Authentication** page of the client app registration. You can get `` by navigating to the **Expose an Api** page of server app registartion and expanding the added scope. The full scope name of the server API should be used for the scope parameter in the below requests (e.g.: "api://1234-5678-abcd-efgh...../access_as_user"). -To learn more about manual generation of Azure Active Directory Token, please refer to [Get Azure Active Directory Tokens by using web browser and curl](https://docs.microsoft.com/azure/databricks/dev-tools/api/latest/aad/app-aad-token#get-azure-ad-tokens-by-using-a-web-browser-and-curl). +To learn more about manual generation of Microsoft Entra Token, please refer to [Get Microsoft Entra Tokens by using web browser and curl](https://docs.microsoft.com/azure/databricks/dev-tools/api/latest/aad/app-aad-token#get-azure-ad-tokens-by-using-a-web-browser-and-curl). 1. You will need an access token using client app registration to call the API. In order to get the access token, open your browser in private mode and visit the link below. diff --git a/docs/test-tools/test-backend-service.md b/docs/test-tools/test-backend-service.md index 5754d48..02fa6cb 100644 --- a/docs/test-tools/test-backend-service.md +++ b/docs/test-tools/test-backend-service.md @@ -1,8 +1,8 @@ # Test deployed service -1. Testing Backend APIs directly with an Azure Active Directory Token +1. Testing Backend APIs directly with an Microsoft Entra Token - - [Generate Azure Active Directory token (Refer to steps 1 - 5)](../../MinimalClient/README.md) to call secure Apis of Azure Communication Services Authentication Hero sample. + - [Generate Microsoft Entra token (Refer to steps 1 - 5)](../../MinimalClient/README.md) to call secure Apis of Azure Communication Services Authentication Hero sample. - [You can also generate a token without a client if you prefer.](../test-tools/generate-aad-token-manually.md) *Note that this process can have some complexities setting it up the first time. @@ -17,4 +17,4 @@ > Note: If you are facing issues running the curl command, then try importing (File -> import -> raw text, paste the curl command and continue) the curl command in [Postman](https://www.postman.com/downloads/) and running it there 2. Test the APIs using the MinimalClient (This will test the `GET /api/token`, and `POST /api/user` endpoints) - - Please take a look at the MinimalClient README.md [MinimalClient](../../MinimalClient/README.md) \ No newline at end of file + - Please take a look at the MinimalClient README.md [MinimalClient](../../MinimalClient/README.md) diff --git a/src/Services/ACSService.cs b/src/Services/ACSService.cs index b62e263..3fdd004 100644 --- a/src/Services/ACSService.cs +++ b/src/Services/ACSService.cs @@ -62,10 +62,10 @@ public async Task CreateACSToken(string acsUserId) } /// - /// Exchange an AAD access token of a Teams user for a new Communication Services AccessToken with a matching expiration time. + /// Exchange an Microsoft Entra access token of a Teams user for a new Communication Services AccessToken with a matching expiration time. /// - /// The Azure AD token of the Teams user. - /// Object ID of an Azure AD user (Teams User) to be verified against the OID claim in the Azure AD access token. + /// The Microsoft Entra token of the Teams user. + /// Object ID of an Microsoft Entra user (Teams User) to be verified against the OID claim in the Microsoft Entra access token. /// An ACS access token with the given scope for a given ACS identity. public async Task GetACSTokenForTeamsUser(string teamsUserAadToken, string userObjectId) {