-> API connectors used in this step are in preview. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-|[API connectors](api-connectors-overview.md) | Preview | GA | |

-|[Secure with basic authentication](secure-rest-api.md#http-basic-authentication) | Preview | GA | |

-|[Secure with client certificate authentication](secure-rest-api.md#https-client-certificate-authentication) | Preview | GA | |

-To find the exact location where your data is located per country/country, refer to [where Azure Active Directory data is located](https://aka.ms/aaddatamap)service.

- - `getAuthCode`: A method that creates the URL of the authorization request, letting the user input credentials and consent to the application. It uses the `getAuthCodeUrl` method, which is defined in the [ConfidentialClientApplication](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_node.confidentialclientapplication.html) class.

-For more information, see the [MSAL PublicClientApplication class reference](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_browser.publicclientapplication.html), and [Use the Microsoft Authentication Library (MSAL) to sign in the user](../active-directory/develop/tutorial-v2-javascript-spa.md#use-the-msal-to-sign-in-the-user) articles.

-|token_endpoint_auth_method| No | Specifies how Azure AD B2C sends the authentication header to the token endpoint. Possible values: `client_secret_post` (default), and `client_secret_basic` (public preview), `private_key_jwt` (public preview). For more information, see [OpenID Connect client authentication section](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). |

-

- ```XML

- <ValidationTechnicalProfiles>

- ....

- <ValidationTechnicalProfile ReferenceId="REST-AcquireAccessToken" />

- ....

- </ValidationTechnicalProfiles>

- ```

-

- "total": 300000

-You can request to increase the quota size by [contacting support](find-help-open-support-ticket.md)

-## April 2023

-### Updated articles

-[powershell-gallery]: https://www.powershellgallery.com/

-$currentAssignments = Get-AzureADServiceAppRoleAssignment -ObjectId $sp.ObjectId

-<!-- EXTERNAL LINKS -->

-[naming-prefix]: /windows-server/identity/ad-ds/plan/selecting-the-forest-root-domain#selecting-a-prefix

-> When a directory extension attribute in Azure AD doesn't show up automatically in your attribute mapping drop-down, you can manually add it to the "Azure AD attribute list". When manually adding Azure AD directory extension attributes to your provisioning app, note that directory extension attribute names are case-sensitive. For example: If you have a directory extension attribute named `extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter`, make sure you enter it in the same format as defined in the directory.

-> API-driven inbound provisioning is currently in public preview and is governed by [Preview Terms of Use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-> API-driven inbound provisioning is currently in public preview and is governed by [Preview Terms of Use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-1. Log in to the [Microsoft Entra portal](<https://entra.microsoft.com>).

-1. Log in to [Microsoft Entra portal](https://entra.microsoft.com) with *global administrator* or *application administrator* login credentials.

-1. Log in to Microsoft Entra portal with application administrator role.

-> If you'd like to add only a few additional attributes to the provisioning app, use Microsoft Entra Portal to extend the schema. If you'd like to add more custom attributes (let's say 20+ attributes), then we recommend using the [`UpdateSchema` mode of the CSV2SCIM PowerShell script](inbound-provisioning-api-powershell.md#extending-provisioning-job-schema) which automates the above manual process.

-1. Log in to Microsoft Entra portal (https://entra.microsoft.com) with global administrator or application administrator login credentials.

-You can verify the processing either from the Microsoft Entra portal or using Graph Explorer.

-### Verify processing from Microsoft Entra portal

-1. Log in to [Microsoft Entra portal](https://entra.microsoft.com) with *global administrator* or *application administrator* login credentials.

-You can verify the processing either from the Microsoft Entra portal or using Postman.

-### Verify processing from Microsoft Entra portal

-1. Log in to [Microsoft Entra portal](https://entra.microsoft.com) with *global administrator* or *application administrator* login credentials.

-1. Log in to your Entra portal as *Application Administrator* or *Global Administrator*.

-1. To associate this certificate with a valid service principal, log in to your Entra portal as *Application Administrator*.

-It doesn't refer to the attribute mappings that you perform in the Entra portal provisioning app between source SCIM schema elements and target Azure AD/on-premises AD attributes.

-description: This document describes how to configure Azure AD to provision users into SAP ECC 7.

-# Configuring Azure AD to provision users into SAP ECC 7.0

-The following documentation provides configuration and tutorial information demonstrating how to provision users from Azure AD into SAP ERP Central Component (SAP ECC) 7.0. If you are using other versions such as SAP R/3, you can still use the guides provided in the [download center](https://www.microsoft.com/download/details.aspx?id=51495) as a reference to build your own template and configure provisioning.

-* Failures for exporting changes can vary greatly. Check the [documentation for provisioning logs](../reports-monitoring/concept-provisioning-logs.md#error-codes) for common failures.

-* On-demand provisioning of groups supports updating up to five members at a time

-The only acceptable protocol versions are TLS 1.2 and TLS 1.3. No other SSL/TLS versions are permitted.

-You can use Microsoft Graph and PowerShell to extend the user schema for users in Azure AD. This is necessary if you do not have any users who need that attribute and originate in on-premises Active Directory. (If you do have Active Directory, then continue reading below in the section on how to [use the Azure AD Connect directory extension feature to synchronize the attribute to Azure AD](#create-an-extension-attribute-using-azure-ad-connect).)

-Finally, verify the attribute for the user. To learn more, see [Get a user](/graph/api/user-get).

-Azure AD also supports provisioning users into applications hosted on-premises or in a virtual machine, without having to open up any firewalls. Your application must support [SCIM](https://aka.ms/scimoverview). Or, you must build a SCIM gateway to connect to your legacy application. If so, you can use the Azure AD Provisioning agent to [directly connect](./on-premises-scim-provisioning.md) with your application and automate provisioning and deprovisioning. If you have legacy applications that don't support SCIM and rely on an [LDAP](./on-premises-ldap-connector-configure.md) user store or a [SQL](./tutorial-ecma-sql-connector.md) database, Azure AD can support these applications as well.

-App provisioning lets you:

-6. Add CORS Rules (optional). For more information see [Configuring CORS Rule](/graph/api/resources/corsconfiguration_v2?view=graph-rest-beta).

-Your users wonΓÇÖt notice anything different when they sign in to use your corporate applications. They can still work from anywhere on any device. The Application Proxy connectors direct remote traffic to all apps without regard to their authentication type, so theyΓÇÖll still balance loads automatically.

-This article is for people to publish an application with this scenario for the first time. Besides detailing the publishing steps, it guides you in getting started with both Application Proxy and PingAccess. If youΓÇÖve already configured both services but want a refresher on the publishing steps, skip to the [Add your application to Azure AD with Application Proxy](#add-your-application-to-azure-ad-with-application-proxy) section.

- 1. **Internal URL**: Normally you provide the URL that takes you to the appΓÇÖs sign-in page when youΓÇÖre on the corporate network. For this scenario, the connector needs to treat the PingAccess proxy as the front page of the application. Use this format: `https://<host name of your PingAccess server>:<port>`. The port is 3000 by default, but you can configure it in PingAccess.

- > If this is your first application, use port 3000 to start and come back to update this setting if you change your PingAccess configuration. For subsequent applications, the port will need to match the Listener youΓÇÖve configured in PingAccess. Learn more about [listeners in PingAccess](https://docs.pingidentity.com/access/sources/dita/topic?category=pingaccess&Releasestatus_ce=Current&resourceid=pa_assigning_key_pairs_to_https_listeners).

-1. From the **App registrations** sidebar for your application, select **API permissions** > **Add a permission** > **Microsoft APIs** > **Microsoft Graph**. The **Request API permissions** page for **Microsoft Graph** appears, which contains the APIs for Windows Azure Active Directory.

-## Other access control considerations

-### Require user assignment

-The [Azure AD Exporter](https://github.com/microsoft/azureadexporter) can provide most of the documentation you need:

-> Settings in the legacy multifactor authentication portal for Application Proxy and federation settings might not be exported with the Azure AD Exporter, or with the Microsoft Graph API.

-* [Custom token cache serialization in MSAL for Java](../develop/msal-java-token-cache-serialization.md)

-* [Custom token cache serialization in MSAL for Python](../develop/msal-python-token-cache-serialization.md).

-| Sign-ins by non-compliant devices| High| Sign-in logs| DeviceDetail.isCompliant == false| If requiring sign-in from compliant devices, alert when: any sign in by non-compliant devices, or any access without MFA or a trusted location.<p>If working toward requiring devices, monitor for suspicious sign-ins.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/blob/master/Hunting%20Queries/SigninLogs/SuccessfulSigninFromNon-CompliantDevice.yaml)<br><br>[Sigma rules](https://github.com/SigmaHQ/sigma/tree/master/rules/cloud/azure) |

-| Alert on changes to privileged account permissions| High| Azure AD Audit logs| Category = Role management<br>-and-<br>Activity type = Add eligible member (permanent)<br>-or-<br>Activity type = Add eligible member (eligible)<br>-and-<br>Status = Success or failure<br>-and-<br>Modified properties = Role.DisplayName| This alert is especially for accounts being assigned roles that aren't known or are outside of their normal responsibilities.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/blob/master/Detections/AuditLogs/PrivilegedAccountPermissionsChanged.yaml)<br><br>[Sigma rules](https://github.com/SigmaHQ/sigma/tree/master/rules/cloud/azure) |

-| Elevations| Medium| Azure AD Audit Logs| Service = PIM<br>-and-<br>Category = Role management<br>-and-<br>Activity type = Add member to role completed (PIM activation)<br>-and-<br>Status = Success or failure <br>-and-<br>Modified properties = Role.DisplayName| After a privileged account is elevated, it can now make changes that could affect the security of your tenant. All elevations should be logged and, if happening outside of the standard pattern for that user, should be alerted and investigated if not planned.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/tree/master/Detections/AuditLogs/AccountElevatedtoNewRole.yaml) |

-| Alert on Add changes to privileged account permissions| High| Azure AD Audit logs| Category = Role Management<br>-and-<br>Activity Type ΓÇô Add eligible member (permanent) <br>-and-<br>Activity Type ΓÇô Add eligible member (eligible) <br>-and-<br>Status = Success/failure<br>-and-<br>Modified properties = Role.DisplayName| Monitor and always alert for any changes to privileged role administrator and global administrator. This can be an indication an attacker is trying to gain privilege to modify role assignment settings. If you donΓÇÖt have a defined threshold, alert on 4 in 60 minutes for users and 2 in 60 minutes for privileged accounts.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/blob/master/Detections/AuditLogs/UserAddedtoAdminRole.yaml)<br><br>[Sigma rules](https://github.com/SigmaHQ/sigma/tree/master/rules/cloud/azure) |

-| When only single-factor authentication is required.| Low| Azure AD Sign-ins log| Status = success<br>Authentication requirement = Single-factor authentication| Monitor periodically and ensure expected behavior.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/blob/master/Hunting%20Queries/SigninLogs/UserAccounts-NewSingleFactorAuth.yaml)<br><br>[Sigma rules](https://github.com/SigmaHQ/sigma/tree/master/rules/cloud/azure) |

-| Authentications to MBI and HBI application using single-factor authentication.| Low| Azure AD Sign-ins log| status = success<br>-and-<br>Application ID = \<HBI app\> <br>-and-<br>Authentication requirement = single-factor authentication.| Review and validate this configuration is intentional.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/blob/master/Hunting%20Queries/SigninLogs/UserAccounts-NewSingleFactorAuth.yaml)<br><br>[Sigma rules](https://github.com/SigmaHQ/sigma/tree/master/rules/cloud/azure) |

-| Authentications at days and times of the week or year that countries/regions do not conduct normal business operations.| Low| Azure AD Sign-ins log| Capture interactive authentication occurring outside of normal operating days\time. <br>Status = success<br>Location = \<location\><br>Date\Time = \<not normal working hours\>| Monitor and alert on authentications days and times of the week or year that countries/regions do not conduct normal business operations.<br>[Microsoft Sentinel template](https://github.com/Azure/Azure-Sentinel/blob/master/Hunting%20Queries/SigninLogs/UserAccounts-UnusualLogonTimes.yaml)<br><br>[Sigma rules](https://github.com/SigmaHQ/sigma/tree/master/rules/cloud/azure) |

-> - The Authenticator app may not be supported on beta versions of iOS and Android.

-

-In some rare instances where the relevant Google or Apple service responsible for push notifications is down, users may not receive their push notifications. In these cases users should manually navigate to the Microsoft Authenticator app (or relevant companion app like Outlook), refresh by either pulling down or hitting the refresh button, and approve the request.

-> [!NOTE]

-> If your organization has staff working in or traveling to China, the *Notification through mobile app* method on Android devices doesn't work in that country/region as Google play services(including push notifications) are blocked in the region. However iOS notification do work. For Android devices ,alternate authentication methods should be made available for those users.

-OATH hardware tokens are supported as part of a public preview. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-Then for ContosoΓÇÖs most sensitive resource, the administrator wants to restrict the access to only passwordless authentication methods. The administrator creates a new Conditional Access policy, using the built-in **Passwordless MFA strength**.

-1. Once the user selects certificate-based authentication, the client is redirected to the certauth endpoint, which is [https://certauth.login.microsoftonline.com](https://certauth.login.microsoftonline.com) for Azure Global. For [Azure Government](../../azure-government/compare-azure-government-global-azure.md#guidance-for-developers), the certauth endpoint is [https://certauth.login.microsoftonline.us](https://certauth.login.microsoftonline.us).

- >The network administrator should allow access to the User sign-in page and certauth endpoint for the customerΓÇÖs cloud environment. Disable TLS inspection on the certauth endpoint to make sure the client certificate request succeeds as part of the TLS handshake.

-| 239 | Sao Tome and Principe |

-It might sound alarming to not ask for a user to sign back in, though any violation of IT policies revokes the session. Some examples include a password change, an incompliant device, or an account disable operation. You can also explicitly [revoke users' sessions using PowerShell](/powershell/module/azuread/revoke-azureaduserallrefreshtoken).

-Without any session lifetime settings, there are no persistent cookies in the browser session. Every time a user closes and open the browser, they get a prompt for reauthentication. In Office clients, the default time period is a rolling window of 90 days. With this default Office configuration, if the user has reset their password or there has been inactivity of over 90 days, the user is required to reauthenticate with all required factors (first and second factor).

-Under each sign-in log, go to the **Authentication Details** tab and explore **Session Lifetime Policies Applied**. For more information, see [Authentication details](../reports-monitoring/concept-sign-ins.md#authentication-details).

-| Firefox | &#10060; | &#10060; | &#10060; |

- Click **Authentication details** for [details about the MFA requirements](../reports-monitoring/concept-sign-ins.md#authentication-details).

->This is an important security enhancement for users authenticating via telecom transports. On June 26, the Microsoft managed value of this feature changed from ΓÇÿdisabledΓÇÖ to ΓÇÿenabledΓÇÖ. If you no longer wish for this feature to be enabled, move the state from 'default' toΓÇÿdisabledΓÇÖ or set users to include and exclude groups.

-By default, Authenticator Lite is [Microsoft managed](concept-authentication-default-enablement.md#microsoft-managed-settings). On June 26, the Microsoft managed value of this feature changed from ΓÇÿdisabledΓÇÖ to ΓÇÿenabledΓÇÖ

- 2. On the Enable and Target tab, click Yes and All users to enable the Authenticator policy for everyone or add selected users and groups. Set the Authentication mode for these users/groups to Any or Push.

- Only users who are enabled for Microsoft Authenticator here can be enabled to use Authenticator Lite for sign-in, or excluded from it. Users who aren't enabled for Microsoft Authenticator can't see the feature. Users who have Microsoft Authenticator downloaded on the same device Outlook is downloaded on will not be prompted to register for Authenticator Lite in Outlook. Android users utilizing a personal and work profile on their device may be prompted to register if Authenticator is present on a different profile from the Outlook application.

-<img width="1112" alt="Entra portal Authenticator settings" src="https://user-images.githubusercontent.com/108090297/228603771-52c5933c-f95e-4f19-82db-eda2ba640b94.png">

-1. In the Azure portal, click **Security** > **Authentication methods** > **Registration campaign**.

-1. For **State**, click **Microsoft managed** or **Enabled**. In the following screenshot, the registration campaign is **Microsoft managed**. That setting allows Microsoft to set the default value to be either enabled or disabled. For the registration campaign, the Microsoft managed value is Enabled for voice call and SMS users with free and trial subscriptions. For more information, see [Protecting authentication methods in Azure Active Directory](concept-authentication-default-enablement.md).

-**Phase 3** requires moving all clients that authenticate to the on-premises MFA Server (VPNs, password managers, and so on) to Azure AD federation via SAML/OAUTH. If modern authentication standards arenΓÇÖt supported, you're required to stand up NPS server(s) with the Azure AD MFA extension installed. Once dependencies are migrated, users should no longer use the User portal on the MFA Server, but rather should manage their authentication methods in Azure AD ([aka.ms/mfasetup](https://aka.ms/mfasetup)). Once users begin managing their authentication data in Azure AD, those methods won't be synced back to MFA Server. If you roll back to the on-premises MFA Server after users have made changes to their Authentication Methods in Azure AD, those changes will be lost. After user migrations are complete, change the [federatedIdpMfaBehavior](/graph/api/resources/internaldomainfederation?view=graph-rest-1.0#federatedidpmfabehavior-values&preserve-view=true) domain federation setting. The change tells Azure AD to no longer perform MFA on-premises and to perform _all_ MFA requests with Azure AD MFA, regardless of group membership.

-^*When a PIN is used to provide proof-of-presence functionality, the functional equivalent is provided above. PINs that arenΓÇÖt cryptographically tied to a device don't sufficiently protect against scenarios where a device has been compromised. To protect against these scenarios, including [SIM swap attacks](https://wikipedia.org/wiki/SIM_swap_scam), move users to more secure methods according to Microsoft authentication methods [best practices](concept-authentication-methods.md).

-|**Passed Sessions tab**|All authentication method registration flows are managed by Azure AD and donΓÇÖt require configuration|

-For RADIUS deployments that canΓÇÖt be upgraded, youΓÇÖll need to deploy an NPS Server and install the [Azure AD MFA NPS extension](howto-mfa-nps-extension.md).

-For LDAP deployments that canΓÇÖt be upgraded or moved to RADIUS, [determine if Azure Active Directory Domain Services can be used](../architecture/auth-ldap.md). In most cases, LDAP was deployed to support in-line password changes for end users. Once migrated, end users can manage their passwords by using [self-service password reset in Azure AD](tutorial-enable-sspr.md).

-If you enabled the [MFA Server Authentication provider in AD FS 2.0](./howto-mfaserver-adfs-windows-server.md#secure-windows-server-ad-fs-with-azure-multi-factor-authentication-server) on any relying party trusts except for the Office 365 relying party trust, youΓÇÖll need to upgrade to [AD FS 3.0](/windows-server/identity/ad-fs/deployment/upgrading-to-ad-fs-in-windows-server) or federate those relying parties directly to Azure AD if they support modern authentication methods. Determine the best plan of action for each of the dependencies.

- - If the Windows API doesnΓÇÖt find the user or the SID isnΓÇÖt found in the MFA Server, then it will use the configured Active Directory attribute to find the user in the on-premises Active Directory, and then use the SID to search the MFA Server user list.

-1. You can migrate users even if they are unchanged. By default, the utility is set to **Only migrate users that have changed**. Click **Migrate all users** to re-migrate previously migrated users that are unchanged. Migrating unchanged users can be useful during testing if an administrator needs to reset a userΓÇÖs Azure MFA settings and wants to re-migrate them.

-MFA Methods will be updated based on what was migrated and the default method will be set. MFA Server will track the last migration timestamp and only migrate the user again if the userΓÇÖs MFA settings change or an admin modifies what to migrate in the **Settings** dialog.

-Ensure users know what to expect when they're moved to Azure MFA, including new authentication flows. You may also wish to instruct users to use the Azure AD Combined Registration portal ([aka.ms/mfasetup](https://aka.ms/mfasetup)) to manage their authentication methods rather than the User portal once migrations are complete. Any changes made to authentication methods in Azure AD won't propagate back to your on-premises environment. In a situation where you had to roll back to MFA Server, any changes users have made in Azure AD wonΓÇÖt be available in the MFA Server User portal.

-If you use third-party solutions that depend on Azure MFA Server for authentication (see [Authentication services](#authentication-services)), youΓÇÖll want users to continue to make changes to their MFA methods in the User portal. These changes will be synced to Azure AD automatically. Once you've migrated these third party solutions, you can move users to the Azure AD combined registration page.

-Once you've completed user migrations, and moved all of your [Authentication services](#authentication-services) off of MFA Server, itΓÇÖs time to update your domain federation settings. After the update, Azure AD no longer sends MFA request to your on-premises federation server.

-Users will no longer be redirected to your on-premises federation server for MFA, whether theyΓÇÖre targeted by the Staged Rollout tool or not. Note this can take up to 24 hours to take effect.

-> Sign-in to Azure AD with email as an alternate login ID is a public preview feature of Azure Active Directory. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-To enable **Report suspicious activity** from the Authentication Methods Settings:

-1. Set **Report suspicious activity** to **Enabled**.

-OATH hardware tokens are supported as part of a public preview. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms).

-| Country | Number(s) |

-| Hong Kong | +852 25716964 |

-| Turkey | +90 8505404893 |

-Connect-MgGraph -Scopes UserAuthenticationMethod.ReadWrite.All

-1. Sign in to the [Entra portal](https://entra.microsoft.com/#home).

-| iOS, macOS |ADAL |[GitHub](https://github.com/AzureAD/azure-activedirectory-library-for-objc/releases) |[GitHub](https://github.com/AzureAD/azure-activedirectory-library-for-objc) |[iOS app](../develop/quickstart-v2-ios.md) | [Reference](http://cocoadocs.org/docsets/ADAL/2.5.1/)|

-description: Frequently asked questions (FAQs) about Microsoft Permissions Management.

-## What types of identities are supported by Permissions Management?

-Permissions Management allows users to right-size excessive permissions and automate least privilege policy enforcement with just a few clicks. The solution continuously analyzes historical permission usage data for each identity and gives customers the ability to right-size permissions of that identity to only the permissions that are being used for day-to-day operations. All unused and other risky permissions can be automatically removed.

-## What is the data destruction/decommission process?

-If a customer initiates a free Permissions Management 45-day trial, but does not follow up and convert to a paid license within 45 days of the free trial expiration, we will delete all collected data on or just before 45 days.

-If a customer decides to discontinue licensing the service, we will also delete all previously collected data within 45 days of license termination.

-We also have the ability to remove, export or modify specific data should the Global Administrator using the Entra Permissions Management service file an official Data Subject Request. This can be initiated by opening a ticket in the Azure portal [New support request - Microsoft Entra admin center](https://entra.microsoft.com/#blade/Microsoft_Azure_Support/NewSupportRequestV3Blade/callerName/ActiveDirectory/issueType/technical), or alternately contacting your local Microsoft representative.

-Although Permissions Management supports all resources, Microsoft only requires licenses for certain resources per cloud. To learn more about billable resources, visit [View billable resources listed in your authorization system](product-data-billable-resources.md)

-## How do I figure out how many resources I have?

-To find out how many resources you have across your multicloud infrastructure, select Settings (gear icon) and view the Billable Resources tab in Permissions Management.

- You have now completed onboarding AWS, and Permissions Management has started collecting and processing your data.

- You have now completed onboarding Azure, and Permissions Management has started collecting and processing your data.

-With the controller, you determine what level of access to provide Permissions Management.

-* Enable to grant read and write access to your environment(s). You can manage permissions and remediate through Permissions Management.

-* Disable to grant read-only access to your environment(s).

-> You can enable the controller in AWS if you disabled it during onboarding. Once you enable the controller, you canΓÇÖt disable it at this time.

- You've completed onboarding GCP, and Permissions Management has started collecting and processing your data.

-description: How to create and view rule-based anomalies and anomaly triggers in Permissions Management.

-# Create and view rule-based anomaly alerts and anomaly triggers

-Rule-based anomalies identify recent activity in Permissions Management that is determined to be unusual based on explicit rules defined in the activity trigger. The goal of rule-based anomaly is high precision detection.

-1. In the Permissions Management home page, select **Activity triggers** (the bell icon).

-## Create a rule-based anomaly trigger

-1. In the Permissions Management home page, select **Activity triggers** (the bell icon).

-1. Select **Create Anomaly Trigger**.

-## View a rule-based anomaly trigger

-1. In the Permissions Management home page, select **Activity triggers** (the bell icon).

-description: How to create and view statistical anomalies and anomaly triggers in the Statistical Anomaly tab in Permissions Management.

-# Create and view statistical anomalies and anomaly triggers

-Statistical anomalies can detect outliers in an identity's behavior if recent activity is determined to be unusual based on models defined in an activity trigger. The goal of this anomaly trigger is a high recall rate.

-1. In the Permissions Management home page, select **Activity triggers** (the bell icon).

-## Create a statistical anomaly trigger

-1. In the Permissions Management home page, select **Activity triggers** (the bell icon).

-## View statistical anomaly triggers

-1. In the Permissions Management home page, select **Activity triggers** (the bell icon).

-For more information about these authentication protocols and services, see [Sign-in activity reports in the Azure portal](../reports-monitoring/concept-sign-ins.md#filter-sign-in-activities).

-1. Navigate to the **Azure portal** > **Azure Active Directory** > **Sign-in logs**.

-Filter for devices is an option when creating a Conditional Access policy in the Azure portal or using the Microsoft Graph API.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-Target resources (formerly Cloud apps, actions, and authentication context) are key signals in a Conditional Access policy. Conditional Access policies allow administrators to assign controls to specific applications, actions, or authentication context.

-

-The following key applications are affected by the Office 365 cloud app:

-Other Microsoft admin portals will be added over time.

-> Microsoft Admin Poratls (preview) is not currently supported in Government clouds.

-Traffic forwarding profiles in Global Secure Access enable administrators to define and control how traffic is routed through Microsoft Entra Internet Access and Microsoft Entra Private Access. Traffic forwarding profiles can be assigned to devices and remote networks. For an example of how to configure these traffic profiles in Conditional Access policy, see the article [How to require a compliant network check](../../global-secure-access/how-to-compliant-network.md).

-Authentication contexts are managed in the Azure portal under **Azure Active Directory** > **Security** > **Conditional Access** > **Authentication context**.

-

-Create new authentication context definitions by selecting **New authentication context** in the Azure portal. Organizations are limited to a total of 25 authentication context definitions. Configure the following attributes:

-| Visual Studio Team Services app | Visual Studio Team Services | Windows 10, Windows 8.1, Windows 7, iOS, and Android |

-Find these templates in the **[Microsoft Entra admin center](https://entra.microsoft.com)** > **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access** > **Create new policy from templates**. Select **Show more** to see all policy templates in each category.

-> Conditional Access template policies will exclude only the user creating the policy from the template. If your organization needs to [exclude other accounts](../roles/security-emergency-access.md), you will be able to modify the policy once they are created. Simply navigate to **Microsoft Entra admin center** > **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access** > **Policies**, select the policy to open the editor and modify the excluded users and groups to select accounts you want to exclude.

-If you do find yourself locked out, see [What to do if you're locked out of the Azure portal?](troubleshoot-conditional-access.md#what-to-do-if-youre-locked-out-of-the-azure-portal)

-1. Sign in to the **Azure portal** as at least a Global Reader.

-1. Browse to **Azure Active Directory** > **Sign-ins**.

-# Continuous access evaluation for workload identities (preview)

-The continuous access evaluation for workload identities public preview scope includes support for Microsoft Graph as a resource provider.

-The preview targets service principals for line of business (LOB) applications.

-1. Sign into the Azure portal as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Sign-in logs** > **Service Principal Sign-ins**. You can use filters to ease the debugging process.

-Customers who have configured CAE settings under Security before have to migrate settings to a new Conditional Access policy. Use the steps that follow to migrate your CAE settings to a Conditional Access policy.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Continuous access evaluation**.

-1. You have the option to **Migrate** your policy. This action is the only one that you have access to at this point.

-1. Browse to **Conditional Access** and you find a new policy named **Conditional Access policy created from CAE settings** with your settings configured. Administrators can choose to customize this policy or create their own to replace it.

-> Filter for applications is currently in public preview. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

- For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Enterprise applications**.

-> Token protection is currently in public preview. For more information about previews, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Sign-in logs**.

-Customers interested in the public preview will need to opt-in using the [MAM for Windows Public Preview Sign Up Form](https://aka.ms/MAMforWindowsPublic).

-The following steps help create a Conditional Access policy requiring an app protection policy when using a Windows device. The app protection policy must also be configured and assigned to your users in Microsoft Intune. For more information about how to create the app protection policy, see the article [Preview: App protection policy settings for Windows](/mem/intune/apps/app-protection-policy-settings-windows).

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

- 1. Select **Require app protection policy**

-After confirming your settings using [report-only mode](howto-conditional-access-insights-reporting.md), an administrator can move the **Enable policy** toggle from **Report-only** to **On**.

-When users attempt to sign in to a site that is protected by an app protection policy for the first time, they're prompted: To access your service, app or website, you may need to sign in to Microsoft Edge using `username@domain.com` or register your device with `organization` if you are already signed in.

-> You must *CLEAR THE CHECKBOX* **Allow my organization to manage my device**. Leaving this checked enrolls your device in mobile device maangment (MDM) not mobile application management (MAM).

-After selecting **OK** you may see a progress window while policy is applied. After a few moments you should see a window saying "you're all set", app protection policies are applied.

-If there's a pre-existing, unregistered account, like `user@contoso.com` in Microsoft Edge, or if a user signs in without registering using the Heads Up Page, then the account isn't properly enrolled in MAM. This configuration blocks the user from being properly enrolled in MAM. This is a known issue that is currently being worked on.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **Azure portal**.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Insights and reporting**.

-1. Sign into the **Azure portal** as a Conditional Access Administrator, security administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access**.

-In order to access the workbook, you need the proper Azure AD permissions and Log Analytics workspace permissions. To test whether you have the proper workspace permissions by running a sample log analytics query:

-1. Sign in to the **Azure portal**.

-1. Browse to **Azure Active Directory** > **Log Analytics**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **Azure portal** as a global administrator, security administrator, or Conditional Access administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Authentication methods** > **Authentication strengths**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-> Misconfiguration of a block policy can lead to organizations being locked out of the Azure portal.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access** > **Named locations**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

- > Persistent Browser Session configuration in Azure AD Conditional Access overrides the ΓÇ£Stay signed in?ΓÇ¥ setting in the company branding pane in the Azure portal for the same user if you have configured both policies.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Sign-in logs**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Workbooks**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Named locations**. Here you can create or update trusted IP locations.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-Users will be blocked from accessing company resources when the device type is unknown or unsupported.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-Locations exist in the Azure portal under **Azure Active Directory** > **Security** > **Conditional Access** > **Named locations**. These named network locations may include locations like an organization's headquarters network ranges, VPN network ranges, or ranges that you wish to block. Named locations are defined by IPv4 and IPv6 address ranges or by countries/regions.

-

-

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Named locations**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-description: Learn how Conditional Access is at the heart of the new identity-driven control plane.

-Microsoft is providing Conditional Access templates to organizations in report-only mode starting in January of 2023. We may add more policies as new threats emerge.

-> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE4MwZs]

-Conditional Access policies at their simplest are if-then statements, if a user wants to access a resource, then they must complete an action. Example: A payroll manager wants to access the payroll application and is required to do multifactor authentication to access it.

- - Users attempting to access specific applications can trigger different Conditional Access policies.

- - Signals integration with [Azure AD Identity Protection](../identity-protection/overview-identity-protection.md) allows Conditional Access policies to identify and remediate risky users and sign-in behavior.

-Administrators with the [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator) role can manage policies in Azure AD.

-Conditional Access is found in the Azure portal under **Azure Active Directory** > **Security** > **Conditional Access**.

-Risk-based policies require access to [Identity Protection](../identity-protection/overview-identity-protection.md), which is an Azure AD P2 feature.

-> Be very careful in using block and all apps in a single policy. This could lock admins out of the Azure portal, and exclusions cannot be configured for important endpoints such as Microsoft Graph.

-This article shows how to migrate a classic policy that requires **multifactor authentication** for a cloud app. Although it isn't a prerequisite, we recommend that you read [Migrate classic policies in the Azure portal](policy-migration.md) before you start migrating your classic policies.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. Navigate to **Azure Active Directory** > **Security** > **Conditional Access**.

-For examples of common policies and their configuration in the Azure portal, see the article [Common Conditional Access policies](concept-conditional-access-policy-common.md).

-1. Sign in to the [Azure portal](https://portal.azure.com) as your test user.

-1. Sign in to the [Azure portal](https://portal.azure.com) as a Conditional Access Administrator, Security Administrator, or a Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

- :::image type="content" source="media/require-tou/terms-of-use-azure-ad-conditional-access.png" alt-text="Screenshot of terms of use shown in the Azure portal highlighting the new terms button." lightbox="media/require-tou/terms-of-use-azure-ad-conditional-access.png":::

- :::image type="content" source="media/require-tou/new-terms-of-use-creation.png" alt-text="Screenshot that shows creating a new terms of use policy in the Azure portal." lightbox="media/require-tou/new-terms-of-use-creation.png":::

-1. Navigate to the **Azure portal** > **Security** > **Conditional Access**

-1. Sign in to the **Azure portal** as a Conditional Access Administrator or Security Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. In the **Name** box, enter a name for the terms of use policy used in the Azure portal.

-1. Sign in to Azure and navigate to **Terms of use** at [https://aka.ms/catou](https://aka.ms/catou).

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Security** > **Conditional Access** > **Terms of use**.

-1. Sign in to the **Azure portal** as a Global Administrator, Security Administrator, or Global Reader.

-1. Browse to **Azure Active Directory** > **Sign-ins**.

-## What to do if you're locked out of the Azure portal?

-If you're locked out of the Azure portal due to an incorrect setting in a Conditional Access policy:

-1. Sign in to the **Azure portal** as a Conditional Access Administrator, Security Administrator, or Global Administrator.

-1. Browse to **Azure Active Directory** > **Audit logs**.

-You can find the **What If** tool in the Azure portal under **Azure Active Directory** > **Security** > **Conditional Access** > **What If**.

-Conditional Access policies have historically applied only to users when they access apps and services like SharePoint online or the Azure portal. We're now extending support for Conditional Access policies to be applied to service principals owned by the organization. We call this capability Conditional Access for workload identities.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Sign in to the **[Microsoft Entra admin center](https://entra.microsoft.com)** as a [Conditional Access Administrator](../roles/permissions-reference.md#conditional-access-administrator).

-1. Browse to **Microsoft Entra ID (Azure AD)** > **Protection** > **Conditional Access**.

-1. Under **Grant**, **Block access** is the only available option. Access is blocked when a token request is made from outside the allowed range.

-1. Browse to **Azure Active Directory** > **Sign-in logs** > **Service principal sign-ins**.

-1. Browse to the **Azure portal** > **Azure Active Directory** > **Enterprise Applications**, find the application you registered.

-description: How to configure the permissions you need to access a particular API in your custom developed Azure AD application

-# How to find a specific API needed for a custom-developed application

-Access to APIs require configuration of access scopes and roles. If you want to expose your resource application web APIs to client applications, configure access scopes and roles for the API. If you want a client application to access a web API, configure permissions to access the API in the app registration.

-## Configuring a resource application to expose web APIs

-When you expose your web API, the API be displayed in the **Select an API** list when adding permissions to an app registration. To add access scopes, follow the steps outlined in [Configure an application to expose web APIs](quickstart-configure-app-expose-web-apis.md).

-## Configuring a client application to access web APIs

-When you add permissions to your app registration, you can **add API access** to exposed web APIs. To access web APIs, follow the steps outlined in [Configure a client application to access web APIs](quickstart-configure-app-access-web-apis.md).

-## Next steps

-To delegate identity and access management functions to Azure AD, an application must be registered with an Azure AD tenant. When you register your application with Azure AD, you're creating an identity configuration for your application that allows it to integrate with Azure AD. When you register an app in the Azure portal, you choose whether it's a [single tenant](single-and-multi-tenant-apps.md#who-can-sign-in-to-your-app), or [multi-tenant](single-and-multi-tenant-apps.md#who-can-sign-in-to-your-app), and can optionally set a [redirect URI](reply-url.md). For step-by-step instructions on registering an app, see the [app registration quickstart](quickstart-register-app.md).

-When you've completed the app registration, you have a globally unique instance of the app (the application object) that lives within your home tenant or directory. You also have a globally unique ID for your app (the app/client ID). In the portal, you can then add secrets or certificates and scopes to make your app work, customize the branding of your app in the sign-in dialog, and more.

-If you register an application in the portal, an application object and a service principal object are automatically created in your home tenant. If you register/create an application using the Microsoft Graph APIs, creating the service principal object is a separate step.

-You can use the **App registrations** page in the [Azure portal] to list and manage the application objects in your home tenant.

- When an application is given permission to access resources in a tenant (upon registration or consent), a service principal object is created. When you register an application using the Azure portal, a service principal is created automatically. You can also create service principal objects in a tenant using Azure PowerShell, Azure CLI, Microsoft Graph, and other tools.

-You can use the **Enterprise applications** page in the Azure portal to list and manage the service principals in a tenant. You can see the service principal's permissions, user consented permissions, which users have done that consent, sign in information, and more.

-In the [Azure portal](https://portal.azure.com), navigate to the application registration overview. Select **Managed application in local directory**.

-[Azure portal]: https://portal.azure.com

-Additional Apple's URLs that may need to be allowed are documented here: https://support.apple.com/en-us/HT210060

-| 8 | Permissions | This list contains the permissions being requested by the client application. Users should always evaluate the types of permissions being requested to understand what data the client application will be authorized to access on their behalf if they accept. As an application developer it's best to request access, to the permissions with the least privilege. |

-#Customer intent: As an app developer, I want to learn about authentication flows and application scenarios so I can create applications protected by the Microsoft identity platform.

-# Authentication flows and application scenarios

-Tokens can be acquired from several types of applications, including:

-## Application scenarios

-Applications running on a device without a browser can still call an API on behalf of a user. To authenticate, the user must sign in on another device that has a web browser. This scenario requires that you use the [device code flow](https://aka.ms/msal-net-device-code-flow).

-Some scenarios, like those that involve Conditional Access related to a device ID or a device enrollment, require a broker to be installed on the device. Examples of brokers are Microsoft Company Portal on Android and Microsoft Authenticator on Android and iOS. MSAL can now interact with brokers. For more information about brokers, see [Leveraging brokers on Android and iOS](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/leveraging-brokers-on-Android-and-iOS).

-The individual national clouds and the global Azure cloud are cloud _instances_. Each cloud instance is separate from the others and has its own environment and _endpoints_. Cloud-specific endpoints include OAuth 2.0 access token and OpenID Connect ID token request endpoints, and URLs for app management and deployment, like the Azure portal.

-You can find the authentication endpoints for your application in the Azure portal.

-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.

-1. Select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations**, and then select **Endpoints** in the top menu.

- The **Endpoints** page is displayed showing the authentication endpoints for the application registered in your Azure AD tenant.

-description: An overview of the authentication protocols supported by the Microsoft identity platform

-# Microsoft identity platform authentication protocols

-The Microsoft identity platform supports several of the most widely used authentication and authorization protocols. The topics in this section describe the supported protocols and their implementation in Microsoft identity platform. The topics included a review of supported claim types, an introduction to the use of federation metadata, detailed OAuth 2.0. and SAML 2.0 protocol reference documentation, and a troubleshooting section.

-## Authentication protocols articles and reference

-* [Important Information About Signing Key Rollover in Microsoft identity platform](./signing-key-rollover.md) ΓÇô Learn about Microsoft identity platformΓÇÖs signing key rollover cadence, changes you can make to update the key automatically, and discussion for how to update the most common application scenarios.

-* [Supported Token and Claim Types](id-tokens.md) - Learn about the claims in the tokens that the Microsoft identity platform issues.

-* [OAuth 2.0 in Microsoft identity platform](v2-oauth2-auth-code-flow.md) - Learn about the implementation of OAuth 2.0 in Microsoft identity platform.

-* [OpenID Connect 1.0](v2-protocols-oidc.md) - Learn how to use OAuth 2.0, an authorization protocol, for authentication.

-* [Service to Service Calls with Client Credentials](v2-oauth2-client-creds-grant-flow.md) - Learn how to use OAuth 2.0 client credentials grant flow for service to service calls.

-* [Service to Service Calls with On-Behalf-Of Flow](v2-oauth2-on-behalf-of-flow.md) - Learn how to use OAuth 2.0 On-Behalf-Of flow for service to service calls.

-* [SAML Protocol Reference](./saml-protocol-reference.md) - Learn about the Single Sign-On and Single Sign-out SAML profiles of Microsoft identity platform.

-## See also

-* [Microsoft identity platform overview](v2-overview.md)

-* [Active Directory Code Samples](sample-v2-code.md)

-description: Learn more about how the Azure AD consent framework works to see how you can use it when developing applications on Azure AD

-# How application consent works

-This article is to help you learn more about how the Azure AD consent framework works so you can develop applications more effectively.

-## Recommended documents

-## Next steps

-[AzureAD Microsoft Q&A](/answers/topics/azure-active-directory.html)

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. Go to **Azure Active Directory** and then **Enterprise applications**. Select **New application** and then **Create your own application**.

-This article describes how to configure and setup a custom claims provider with the [token issuance start event](custom-claims-provider-overview.md#token-issuance-start-event-listener) type. This event is triggered right before the token is issued, and allows you to call a REST API to add claims to the token.

-# [Azure portal](#tab/azure-portal)

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. Under **Azure services**, select **Azure Active Directory**.

-1. Ensure your user account has the Global Administrator or Application Administrator and Authentication Extensibility Administrator role. Otherwise, learn how to [assign a role](../roles/manage-roles-portal.md).

-1. From the menu, select **Enterprise applications**.

-1. Under **Manage**, select the **Custom authentication extensions**.

-1. Select **Create a custom authentication extension**.

-Create an Application Registration to authenticate your custom authentication extension to your Azure Function.

-1. Sign in to the [Microsoft Graph Explorer](https://aka.ms/ge) using an account whose home tenant is the tenant you wish to manage your custom authentication extension in.

-1. Set the HTTP method to **POST**.

-1. Paste the URL: `https://graph.microsoft.com/v1.0/applications`

-1. Select **Request Body** and paste the following JSON:

- ```json

- "displayName": "authenticationeventsAPI"

-1. Select **Run Query** to submit the request.

-1. Copy the **Application ID** value (*appId*) from the response. You need this value later, which is referred to as the `{authenticationeventsAPI_AppId}`. Also get the object ID of the app (*ID*), which is referred to as `{authenticationeventsAPI_ObjectId}` from the response.

-Create a service principal in the tenant for the authenticationeventsAPI app registration:

-1. Set the HTTP method to **POST**.

-1. Paste the URL: `https://graph.microsoft.com/v1.0/servicePrincipals`

-1. Select **Request Body** and paste the following JSON:

- ```json

- {

- "appId": "{authenticationeventsAPI_AppId}"

- }

- ```

-1. Select **Run Query** to submit the request.

-1. Set the HTTP method to **PATCH**.

-1. Paste the URL: `https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}`

-1. Select **Request Body** and paste the following JSON:

- Set the application ID URI value in the *identifierUris* property. Replace `{Function_Url_Hostname}` with the hostname of the `{Function_Url}` you recorded earlier.

-

- Set the `{authenticationeventsAPI_AppId}` value with the App ID generated from the app registration created in the previous step.

-

- An example value would be `api://authenticationeventsAPI.azurewebsites.net/f4a70782-3191-45b4-b7e5-dd415885dd80`. Take note of this value as it is used in following steps and is referenced as `{functionApp_IdentifierUri}`.

-

- ```json

- "identifierUris": [

- "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"

- ],

- "api": {

- "requestedAccessTokenVersion": 2,

- "acceptMappedClaims": null,

- "knownClientApplications": [],

- "oauth2PermissionScopes": [],

- "preAuthorizedApplications": []

- },

- "requiredResourceAccess": [

- "resourceAppId": "00000003-0000-0000-c000-000000000000",

- "resourceAccess": [

- {

- "id": "214e810f-fda8-4fd7-a475-29461495eb00",

- "type": "Role"

- }

- ]

- ```

-1. Select **Run Query** to submit the request.

-Next, you register the custom authentication extension. You register the custom authentication extension by associating it with the App Registration for the Azure Function, and your Azure Function endpoint `{Function_Url}`.

-1. Set the HTTP method to **POST**.

-1. Paste the URL: `https://graph.microsoft.com/beta/identity/customAuthenticationExtensions`

-1. Select **Request Body** and paste the following JSON:

- Replace `{Function_Url}` with the hostname of your Azure Function app. Replace `{functionApp_IdentifierUri}` with the identifierUri used in the previous step.

- ```json

-1. Select **Run Query** to submit the request.

-Record the ID value of the created custom claims provider object. The ID is needed in a later step and is referred to as the `{customExtensionObjectId}`.

-After your custom authentication extension is created, you'll be taken to the **Overview** tab of the new custom authentication extension.

-1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to **Azure Active Directory**.

-1. Select **App registrations**, and then select **New registration**.

-In your app registration, under **Overview**, copy the **Application (client) ID**. The app ID is referred to as the `{App_to_enrich_ID}` in later steps.

-# [Azure portal](#tab/azure-portal)

-1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to **Azure Active Directory**.

-1. Select **App registrations**, and find the *My Test application* registration you created.

-First create an event listener to trigger a custom authentication extension using the token issuance start event:

-1. Sign in to the [Microsoft Graph Explorer](https://aka.ms/ge) using an account whose home tenant is the tenant you wish to manage your custom authentication extension in.

-1. Set the HTTP method to **POST**.

-1. Paste the URL: `https://graph.microsoft.com/beta/identity/authenticationEventListeners`

-1. Select **Request Body** and paste the following JSON:

- Replace `{App_to_enrich_ID}` with the app ID of *My Test application* recorded earlier. Replace `{customExtensionObjectId}` with the custom authentication extension ID recorded earlier.

- ```json

-1. Select **Run Query** to submit the request.

-Next, create the claims mapping policy, which describes which claims can be issued to an application from a custom claims provider:

-1. Set the HTTP method to **POST**.

-1. Paste the URL: `https://graph.microsoft.com/v1.0/policies/claimsmappingpolicies`

-1. Select **Request Body** and paste the following JSON:

- ```json

-1. Record the `ID` generated in the response, later it's referred to as `{claims_mapping_policy_ID}`.

-1. Select **Run Query** to submit the request.

-Get the `servicePrincipal` objectId:

-1. Set the HTTP method to **GET**.

-1. Paste the URL: `https://graph.microsoft.com/v1.0/servicePrincipals(appId='{App_to_enrich_ID}')/claimsMappingPolicies/$ref`. Replace `{App_to_enrich_ID}` with *My Test Application* App ID.

-1. Record the `id` value, later it's referred to as `{test_App_Service_Principal_ObjectId}`.

-Assign the claims mapping policy to the `servicePrincipal` of *My Test Application*:

-1. Set the HTTP method to **POST**.

-1. Paste the URL: `https://graph.microsoft.com/v1.0/servicePrincipals/{test_App_Service_Principal_ObjectId}/claimsMappingPolicies/$ref`

-1. Select **Request Body** and paste the following JSON:

- ```json

-1. Select **Run Query** to submit the request.

-1. Go to your Azure AD tenant in which your custom authentication extension is registered, and select **Azure Active Directory** > **App registrations**.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. In the **Enterprise apps** experience for your given application, select on the **Sign-in** logs tab.

-1. Select the latest sign-in log.

-1. Sign in to the [Azure portal](https://portal.azure.com) with your Azure administrator account.

-1. Select **Azure Active Directory** > **App registrations**.

-description: Learn about delegated and application permissions, how they are used by clients and exposed by resources for applications you are developing with Azure AD

-# How to recognize differences between delegated and application permissions

-## Recommended documents

-## Next steps

-[AzureAD Microsoft Q&A](/answers/topics/azure-active-directory.html)

-1. Sign into the [Entra admin portal](https://entra.microsoft.com/).

-1. Select **App registrations** in the left navigation pane, and then the **All applications**.

-1. Sign into the [Entra admin portal](https://entra.microsoft.com/).

-1. In the left navigation pane, select **Roles & admins**.

-View the deployed website on App Service. Navigate to your App Service in Azure portal and select the instance's **Default domain**: `https://pipelinetestwebapp.azurewebsites.net`.

-To verify that access to your app is limited to users in your organization, navigate to your App Service in the [Azure portal](https://portal.azure.com) and select the instance's **Default domain**: `https://pipelinetestwebapp.azurewebsites.net`.

-In the Azure portal, select **Resource groups** from the menu and select the resource group that contains your deployed web app.

-In the [Entra admin center](https://entra.microsoft.com/), select **Applications** > **App registrations** > **All applications**.

-description: Definitions of terms commonly found in Microsoft identity platform documentation, Azure portal, and authentication SDKs like the Microsoft Authentication Library (MSAL).

-You see these terms when you use our documentation, the Azure portal, our authentication libraries, and the Microsoft Graph API. Some terms are Microsoft-specific while others are related to protocols like OAuth or other technologies you use with the Microsoft identity platform.

-A feature provided by the [Azure portal], which produces a JSON representation of the application's identity configuration, used as a mechanism for updating its associated [Application][Graph-App-Resource] and [ServicePrincipal][Graph-Sp-Resource] entities. See [Understanding the Azure Active Directory application manifest][AAD-App-Manifest] for more details.

-When you register/update an application in the [Azure portal], the portal creates/updates both an application object and a corresponding [service principal object](#service-principal-object) for that tenant. The application object _defines_ the application's identity configuration globally (across all tenants where it has access), providing a template from which its corresponding service principal object(s) are _derived_ for use locally at run-time (in a specific tenant).

-Permission requests are configured on the **API permissions** page for an application in the [Azure portal], by selecting the desired "Delegated Permissions" and "Application Permissions" (the latter requires membership in the Global Administrator role). Because a [public client](#client-application) can't securely maintain credentials, it can only request delegated permissions, while a [confidential client](#client-application) has the ability to request both delegated and application permissions. The client's [application object](#application-object) stores the declared permissions in its [requiredResourceAccess property][Graph-App-Resource].

-Roles are resource-defined strings (for example "Expense approver", "Read-only", "Directory.ReadWrite.All"), managed in the [Azure portal] via the resource's [application manifest](#application-manifest), and stored in the resource's [appRoles property][Graph-Sp-Resource]. The Azure portal is also used to assign users to "user" assignable roles, and configure client [application permissions](#permissions) to request "application" assignable roles.

-For a detailed discussion of the application roles exposed by the Microsoft Graph API, see [Graph API Permission Scopes][Graph-Perm-Scopes]. For a step-by-step implementation example, see [Add or remove Azure role assignments using the Azure portal][AAD-RBAC].

-Scopes are resource-defined strings (for example "Mail.Read", "Directory.ReadWrite.All"), managed in the [Azure portal] via the resource's [application manifest](#application-manifest), and stored in the resource's [oauth2Permissions property][Graph-Sp-Resource]. The Azure portal is also used to configure client application [delegated permissions](#permissions) to access a scope.

-When you register/update an application in the [Azure portal], the portal creates/updates both an [application object](#application-object) and a corresponding service principal object for that tenant. The application object _defines_ the application's identity configuration globally (across all tenants where the associated application has been granted access), and is the template from which its corresponding service principal object(s) are _derived_ for use locally at run-time (in a specific tenant).

-Azure AD tenants are created/associated with Azure and Microsoft 365 subscriptions during sign-up, providing Identity & Access Management features for the subscription. Azure subscription administrators can also create additional Azure AD tenants via the Azure portal. See [How to get an Azure Active Directory tenant][AAD-How-To-Tenant] for details on the various ways you can get access to a tenant. See [Associate or add an Azure subscription to your Azure Active Directory tenant][AAD-How-Subscriptions-Assoc] for details on the relationship between subscriptions and an Azure AD tenant, and for instructions on how to associate or add a subscription to an Azure AD tenant.

-[Azure portal]: https://portal.azure.com

-Explore the range of [Azure support options and choose the plan](https://azure.microsoft.com/support/plans) that best fits you. There are two options to create and manage support requests in the Azure portal:

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. In the left pane, select **Azure Active Directory**.

-1. Select **Enterprise applications**, and then select **All applications**.

- :::image type="content" source="media/enterprise-app-role-management/record-objectid.png" alt-text="Screenshot that shows how to locate and record the object identifier for the application.":::

-1. Locate the application in the Azure portal, and then select **Single sign-on** in the left menu.

- :::image type="content" source="media/enterprise-app-role-management/attributes-summary.png" alt-text="Screenshot that shows a display of the list of attributes and claims defined for the application.":::

-1. In the Azure portal, locate the application to which the role was added.

- :::image type="content" source="media/enterprise-app-role-management/assign-role.png" alt-text="Screenshot that shows how to assign a role to a user of an application.":::

-* [Through the Azure portal](#azure-portal)

-### <a name="azure-portal"></a>Using the Azure portal

-Follow these steps in the Azure portal.

-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a> and select the correct Azure AD tenant(not B2C).

-2. Navigate to the **App registrations** section and select your app.

-3. Under **Manage**, select **Branding & properties**.

-4. Fill out the **Terms of service URL** and **Privacy statement URL** fields.

-5. Select **Save**.

- 

-If you prefer to modify the app object JSON directly, you can use the manifest editor in the Azure portal or Application Registration Portal to include links to your app's terms of service and privacy statement.

-This article shows you how to call a protected ASP.NET Core web API using Client URL (cURL). cURL is a command line tool that developers use to transfer data to and from a server. In this article, you'll register a web app and a web API in a tenant on the Azure portal. The web app is used to get an access token generated by the Microsoft identity platform. Next, you'll use the token to make an authorized call to the web API using cURL.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations > New registration**.

-1. Select **Home** to return to the home page. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations** > **New registration**.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. If access to multiple tenants is available, use the Directories + subscriptions filter :::image type="icon" source="media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you want to register the application.

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations** > **New registration**.

-When registration is complete, the Azure portal displays the app registration's **Overview** pane. Record the **Directory (tenant) ID** and the **Application (client) ID** to be used in later steps.

-1. From the **Overview** pane in the Azure portal, under **Manage**, select **Certificates & secrets** > **Client secrets** > **New client secret**.

-1. From the **Overview** pane of your web application in the Azure portal (*web-app-that-calls-web-api*), under **Manage**, select **API permissions** > **Add a permission** > **My APIs**.

-You may also notice the **User.Read** permission for the Microsoft Graph API. This permission is added automatically when you register an app in the Azure portal.

- - `{APPLICATION_CLIENT_ID}` is the web API **Application (client) ID** on the app's **Overview** pane **App registrations** in the Azure portal.

- - `{DIRECTORY_TENANT_ID}` is the web API **Directory (tenant) ID** on the app's **Overview** pane **App registrations** in the Azure portal.

- - `{tenant_id}` is the web app **Directory (tenant) ID**. This should be the same value across both of the applications's **Overview** pane **App registrations** in the Azure portal.

- - `{web-app-calls-web-api_application_client_id}` is the **Application (client) ID** on the web app's (*web-app-calls-web-api*) **Overview** pane in the Azure portal.

- - `{web_API_application_client_id}` is the **Application (client) ID** on the web API's (*NewWebAPI1*) **Overview** pane in the Azure portal.

- - `{tenant_id}` is the web app **Directory (tenant) ID**. This should be the same value across both of the applications's **Overview** pane **App registrations** in the Azure portal.

- - `client_id={web-app-calls-web-api_application_client_id}`, and `session_state={web-app-calls-web-api_application_client_id}` is the **Application (client) ID** on the web application's (*web-app-calls-web-api*) **Overview** pane in the Azure portal.

- - `api://{web_API_application_client_id}/Forecast.Read` is the **Application (client) ID** on the web API's (*NewWebAPI1*) **Overview** pane in the Azure portal.

-This article shows you how to call a protected ASP.NET Core web API using [Postman](https://www.postman.com/). Postman is an application that lets you send HTTP requests to a web API to test its authorization and access control (authentication) policies. In this article, you'll register a web app and a web API in a tenant on the Azure portal. The web app is used to get an access token generated by the Microsoft identity platform. Next, you'll use the token to make an authorized call to the web API using Postman.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations > New registration**.

-1. Select **Home** to return to the home page. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations** > **New registration**.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. If access to multiple tenants is available, use the Directories + subscriptions filter :::image type="icon" source="media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you want to register the application.

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations** > **New registration**.

-When registration is complete, the Azure portal displays the app registration's **Overview** pane. Record the **Directory (tenant) ID** and the **Application (client) ID** to be used in later steps.

-1. From the **Overview** pane in the Azure portal, under **Manage**, select **Certificates & secrets** > **Client secrets** > **New client secret**.

-1. From the **Overview** pane of your application in the Azure portal, under **Manage**, select **API permissions** > **Add a permission** > **My APIs**.

-You may also notice the **User.Read** permission for the Microsoft Graph API. This permission is added automatically when you register an app in the Azure portal.

- - `{APPLICATION_CLIENT_ID}` is the web API **Application (client) ID** on the app's **Overview** pane **App registrations** in the Azure portal.

- - `{DIRECTORY_TENANT_ID}` is the web API **Directory (tenant) ID** on the app's **Overview** pane **App registrations** in the Azure portal.

-# How to configure app instance property lock for your applications (Preview)

-To configure an app instance lock using the Azure portal:

-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.

-1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="./media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant that contains the app registration you want to configure.

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations**, and then select the application you want to configure.

- :::image type="content" source="media/howto-configure-app-instance-property-locks/app-instance-lock-configure-overview.png" alt-text="Screenshot of an app registration's app instance lock in the Azure portal.":::

- :::image type="content" source="media/howto-configure-app-instance-property-locks/app-instance-lock-configure-properties.png" alt-text="Screenshot of an app registration's app instance property lock context pane in the Azure portal.":::

-In an elevated PowerShell prompt, run the following command and leave the PowerShell console session open. Replace `{certificateName}` with the name that you wish to give to your certificate.

-In the following sections, you learn how to modify your app's registration in the Azure portal to change who, or what types of accounts, can access the application.

-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.

-1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="./media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which the app is registered.

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations**, select your application, and then select **Manifest** to use the manifest editor.

-If youΓÇÖre just getting started, check out the [Microsoft identity platform documentation](index.yml) to learn about authentication basics, application scenarios in the Microsoft identity platform, and more.

-> The *Integration assistant* in the Azure portal can help you apply many of these best practices and recommendations. Select any of your [app registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) in the Azure portal, and then select the **Integration assistant** menu item to get started with the assistant.

-. Make sure your name and logo are representative of your company/product so that users can make informed decisions. Ensure that you're not violating any trademarks.

-.

- apps.

- For mobile apps, configure each platform using the application registration experience. In order for your application to take advantage of the Microsoft Authenticator or Microsoft Company Portal for single sign-in, your app needs a ΓÇ£broker redirect URIΓÇ¥ configured. This allows Microsoft to return control to your application after authentication. When configuring each platform, the app registration experience will guide you through the process. Use the quickstart to download a working example. On iOS, use brokers and system webview whenever possible.

- Don't use ΓÇ£prompt=consentΓÇ¥ for every sign-in. Only use prompt=consent if youΓÇÖve determined that you need to ask for consent for additional permissions (for example, if youΓÇÖve changed your appΓÇÖs required permissions).

- Implement a [clean single sign-out experience](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-6-SignOut). ItΓÇÖs a privacy and a security requirement, and makes for a good user experience.

- Test for [Conditional Access policies](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC/1-6-SignOut) that may affect your usersΓÇÖ ability to use your application.

-[auth-fund-01-img]: ./media/identity-videos/aad-auth-fund-01.jpg

-[auth-fund-02-img]: ./media/identity-videos/aad-auth-fund-02.jpg

-[auth-fund-03-img]: ./media/identity-videos/aad-auth-fund-03.jpg

-[auth-fund-04-img]: ./media/identity-videos/aad-auth-fund-04.jpg

-[auth-fund-05-img]: ./media/identity-videos/aad-auth-fund-05.jpg

-[auth-fund-06-img]: ./media/identity-videos/aad-auth-fund-06.jpg

-To view or edit the claims issued in the JWT to the application, open the application in Azure portal. Then select **Single sign-on** blade in the left-hand menu and open the **Attributes & Claims** section.

-1. Sign in to the [Azure portal](https://portal.azure.com).

-1. In the **Attributes & Claims** section, Select **Edit** to edit the claims.

-1. Select the required claim that you want to modify.

- :::image type="content" source="./media/jwt-claims-customization/sso-saml-multiple-claims-transformation.png" alt-text="Screenshot of claims transformation.":::

-| **EndWith()** | Outputs an attribute or constant if the input ends with the specified value. Otherwise, you can specify another output if there's no match.<br/>For example, if you want to emit a claim where the value is the user's employee ID if the employee ID ends with "000", otherwise you want to output an extension attribute. To perform this function, you configure the following values:<br/>*Parameter 1(input)*: user.employeeid<br/>*Value*: "000"<br/>Parameter 2 (output): user.employeeid<br/>Parameter 3 (output if there's no match): user.extensionattribute1 |

-| **StartWith()** | Outputs an attribute or constant if the input starts with the specified value. Otherwise, you can specify another output if there's no match.<br/>For example, if you want to emit a claim where the value is the user's employee ID if the country/region starts with "US", otherwise you want to output an extension attribute. To perform this function, you configure the following values:<br/>*Parameter 1(input)*: user.country<br/>*Value*: "US"<br/>Parameter 2 (output): user.employeeid<br/>Parameter 3 (output if there's no match): user.extensionattribute1 |

-Applications that receive tokens rely on claim values that are authoritatively issued by Azure AD and can't be tampered with. When you modify the token contents through claims customization, these assumptions may no longer be correct. Applications must explicitly acknowledge that tokens have been modified by the creator of the customization to protect themselves from customizations created by malicious actors. This can be done in one the following ways:

-For multi-tenant apps, a custom signing key should be used. Don't set `acceptMappedClaims` in the app manifest. when setting up an app in the Azure portal, you get an app registration object and a service principal in your tenant. That app is using the Azure global sign-in key, which can't be used for customizing claims in tokens. To get custom claims in tokens, create a custom sign-in key from a certificate and add it to service principal. For testing purposes, you can use a self-signed certificate. After configuring the custom signing key, your application code needs to validate the token signing key.

-The following example shows the format of the HTTP PATCH request to add a custom signing key to a service principal. The "key" value in the `keyCredentials` property is shortened for readability. The value is base-64 encoded. For the private key, the property usage is "Sign". For the public key, the property usage is "Verify".

-Use PowerShell to [instantiate an MSAL Public Client Application](msal-net-initializing-client-applications.md#initializing-a-public-client-application-from-code) and use the [Authorization Code Grant](v2-oauth2-auth-code-flow.md) flow to obtain a delegated permission access token for Microsoft Graph. Use the access token to call Microsoft Graph and configure a custom signing key for the service principal. After configuring the custom signing key, your application code needs to [validate the token signing key](#validate-token-signing-key).

-To run this script you need:

-For single tenant apps, you can set the `acceptMappedClaims` property to `true` in the [application manifest](reference-app-manifest.md). As documented on the [apiApplication resource type](/graph/api/resources/apiapplication?view=graph-rest-1.0&preserve-view=true#properties), this allows an application to use claims mapping without specifying a custom signing key.

-description: Describes how to mark an app as publisher verified. When an application is marked as publisher verified, it means that the publisher (application developer) has verified the authenticity of their organization using a Microsoft Partner Network (MPN) account that has completed the verification process and has associated this MPN account with that application registration.

-When an app registration has a verified publisher, it means that the publisher of the app has [verified](/partner-center/verification-responses) their identity using their Microsoft Partner Network (MPN) account and has associated this MPN account with their app registration. This article describes how to complete the [publisher verification](publisher-verification-overview.md) process.

-If you are already enrolled in the Microsoft Partner Network (MPN) and have met the [pre-requisites](publisher-verification-overview.md#requirements), you can get started right away:

-1. Click **Add MPN ID to verify publisher** and review the listed requirements.

-1. Enter your MPN ID and click **Verify and save**.

-1. Sign in using [multi-factor authentication](../fundamentals/concept-fundamentals-mfa-get-started.md) to an organizational (Azure AD) account authorized to make changes to the app you want to mark as Publisher Verified and on the MPN Account in Partner Center.

- - The user in Partner Center must have the following [roles](/partner-center/permissions-overview): MPN Admin, Accounts Admin, or a Global Administrator (a shared role mastered in Azure AD).

-1. Ensure that either the publisher domain or a DNS-verified [custom domain](../fundamentals/add-custom-domain.md) on the tenant matches the domain of the email address used during the verification process for your MPN account.

-1. Click **Add MPN ID to verify publisher** near the bottom of the page.

-1. Enter the **MPN ID** for:

- - A valid Microsoft Partner Network account that has completed the verification process.

-description: Learn about Microsoft Identity Web, an authentication and authorization library for ASP.NET Core applications that integrate with Azure Active Directory, Azure AD B2C, and Microsoft Graph and other web APIs.

-# Customer intent: As an application developer, I want to learn how to add authentication to ASP.NET Core web apps and authorization to protected web APIs.

-# Microsoft Identity Web authentication library

-Microsoft Identity Web is a set of ASP.NET Core libraries that simplifies adding authentication and authorization support to web apps and web APIs integrating with the Microsoft identity platform. It provides a single-surface API convenience layer that ties together ASP.NET Core, its authentication middleware, and the [Microsoft Authentication Library (MSAL) for .NET](https://github.com/azuread/microsoft-authentication-library-for-dotnet). It can be installed via NuGet or by using a Visual Studio project template to create a new app project

-## Supported application scenarios

-When building ASP.NET Core web apps or web APIs that use Azure Active Directory (Azure AD) or Azure AD B2C for identity and access management (IAM), Microsoft Identity Web is recommended for these scenarios:

-## Install from NuGet

-Microsoft Identity Web is available on NuGet as a set of packages that provide modular functionality based on application requirements. Use the .NET CLI's `dotnet add` command or Visual Studio's **NuGet Package Manager** to install the appropriate packages:

-## Install by using a Visual Studio project template

-Several project templates that use *Microsoft.Identity.Web* are included in .NET SDK versions 6.0 and above.

-### .NET 6.0+ - Project templates included

-The Microsoft Identity Web project templates are included in .NET SDK versions 6.0 and above.

-In the following example, .NET CLI command creates a Blazor Server project that includes Microsoft Identity Web.

-```dotnetcli

-dotnet new blazorserver --auth SingleOrg --calls-graph --client-id "00000000-0000-0000-0000-000000000000" --tenant-id "11111111-1111-1111-1111-111111111111" --output my-blazor-app

-```

-Don't append a `2` to the application type argument, `blazorserver` in the example, because templates included in .NET SDK 6.0+ are being used.

-## Next steps

-To see Microsoft Identity Web in action, try our Blazor Server tutorial:

-[Tutorial: Create a Blazor Server app that uses the Microsoft identity platform for authentication](tutorial-blazor-server.md)

-The Microsoft Identity Web wiki on GitHub contains extensive reference documentation for various aspects of the library. For example, certificate usage, incremental consent, and Conditional Access reference can be found here:

-<!-- LINKS -->

-<!-- [miw-certs]: microsoft-identity-web-certificates.md -->

-<!-- [miw-certs-decrypt]: microsoft-identity-web-certificates.md#decryption-certificates -->

-<!-- [miw-inc-consent-ca-header]: microsoft-identity-web-consent-conditional-access.md#handling-incremental-consent-or-conditional-access-in-web-apis -->

-<!-- [miw-inc-consent-ca]: microsoft-identity-web-consent-conditional-access.md -->

-[scenario-api-call-api]: scenario-web-api-call-api-call-api.md#option-1-call-microsoft-graph-with-the-sdk

-[scenario-api-call-graph]: scenario-web-api-call-api-call-api.md#option-1-call-microsoft-graph-with-the-sdk

-[scenario-api-validation]: scenario-protected-web-api-verification-scope-app-roles.md

-description: Learn how to migrate your Azure Active Directory Authentication Library (ADAL) Java app to the Microsoft Authentication Library (MSAL).

-#Customer intent: As a Java application developer, I want to learn how to migrate my v1 ADAL app to v2 MSAL.

-# ADAL to MSAL migration guide for Java

-This article highlights changes you need to make to migrate an app that uses the Azure Active Directory Authentication Library (ADAL) to use the Microsoft Authentication Library (MSAL).

-Both the Microsoft Authentication Library for Java (MSAL4J) and Azure AD Authentication Library for Java (ADAL4J) are used to authenticate Azure AD entities and request tokens from Azure AD. Until now, most developers have worked with Azure AD for developers platform (v1.0) to authenticate Azure AD identities (work and school accounts) by requesting tokens using Azure AD Authentication Library (ADAL).

-MSAL offers the following benefits:

-MSAL for Java is the auth library we recommend you use with the Microsoft identity platform. No new features will be implemented on ADAL4J. All efforts going forward are focused on improving MSAL.

-You can learn more about MSAL and get started with an [overview of the Microsoft Authentication Library](msal-overview.md).

-## Scopes not resources

-ADAL4J acquires tokens for resources whereas MSAL for Java acquires tokens for scopes. Many MSAL for Java classes require a scopes parameter. This parameter is a list of strings that declare the desired permissions and resources that are requested. See [Microsoft Graph's scopes](/graph/permissions-reference) to see example scopes.

-You can add the `/.default` scope suffix to the resource to help migrate your apps from the ADAL to MSAL. For example, for the resource value of `https://graph.microsoft.com`, the equivalent scope value is `https://graph.microsoft.com/.default`. If the resource isn't in the URL form, but a resource ID of the form `XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX`, you can still use the scope value as `XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default`.

-For more details about the different types of scopes, refer

-[Permissions and consent in the Microsoft identity platform](./permissions-consent-overview.md) and the [Scopes for a Web API accepting v1.0 tokens](./msal-v1-app-scopes.md) articles.

-## Core classes

-In ADAL4J, the `AuthenticationContext` class represents your connection to the Security Token Service (STS), or authorization server, through an Authority. However, MSAL for Java is designed around client applications. It provides two separate classes: `PublicClientApplication` and `ConfidentialClientApplication` to represent client applications. The latter, `ConfidentialClientApplication`, represents an application that is designed to securely maintain a secret such as an application identifier for a daemon app.

-The following table shows how ADAL4J functions map to the new MSAL for Java functions:

-| ADAL4J method| MSAL4J method|

-||-|

-|acquireToken(String resource, ClientCredential credential, AuthenticationCallback callback) | acquireToken(ClientCredentialParameters)|

-|acquireToken(String resource, ClientAssertion assertion, AuthenticationCallback callback)|acquireToken(ClientCredentialParameters)|

-|acquireToken(String resource, AsymmetricKeyCredential credential, AuthenticationCallback callback)|acquireToken(ClientCredentialParameters)|

-|acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback)| acquireToken(UsernamePasswordParameters)|

-|acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback)|acquireToken(IntegratedWindowsAuthenticationParameters)|

-|acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback)| acquireToken(OnBehalfOfParameters)|

-|acquireTokenByAuthorizationCode() | acquireToken(AuthorizationCodeParameters) |

-| acquireDeviceCode() and acquireTokenByDeviceCode()| acquireToken(DeviceCodeParameters)|

-|acquireTokenByRefreshToken()| acquireTokenSilently(SilentParameters)|

-## IAccount instead of IUser

-ADAL4J manipulated users. Although a user represents a single human or software agent, it can have one or more accounts in the Microsoft identity system. For example, a user may have several Azure AD, Azure AD B2C, or Microsoft personal accounts.

-MSAL for Java defines the concept of Account via the `IAccount` interface. This is a breaking change from ADAL4J, but it's a good one because it captures the fact that the same user can have several accounts, and perhaps even in different Azure AD directories. MSAL for Java provides better information in guest scenarios because home account information is provided.

-## Cache persistence

-ADAL4J didn't have support for token cache.

-MSAL for Java adds a [token cache](msal-acquire-cache-tokens.md) to simplify managing token lifetimes by automatically refreshing expired tokens when possible and preventing unnecessary prompts for the user to provide credentials when possible.

-## Common Authority

-In v1.0, if you use the `https://login.microsoftonline.com/common` authority, users can sign in with any Azure Active Directory (Azure AD) account (for any organization).

-If you use the `https://login.microsoftonline.com/common` authority in v2.0, users can sign in with any Azure AD organization, or even a Microsoft personal account (MSA). In MSAL for Java, if you want to restrict login to any Azure AD account, use the `https://login.microsoftonline.com/organizations` authority (which is the same behavior as with ADAL4J). To specify an authority, set the `authority` parameter in the [PublicClientApplication.Builder](https://javadoc.io/doc/com.microsoft.azure/msal4j/1.0.0/com/microsoft/aad/msal4j/PublicClientApplication.Builder.html) method when you create your `PublicClientApplication` class.

-## v1.0 and v2.0 tokens

-The v1.0 endpoint (used by ADAL) only emits v1.0 tokens.

-The v2.0 endpoint (used by MSAL) can emit v1.0 and v2.0 tokens. A property of the application manifest of the web API enables developers to choose which version of token is accepted. See `accessTokenAcceptedVersion` in the [application manifest](./reference-app-manifest.md) reference documentation.

-For more information about v1.0 and v2.0 tokens, see [Azure Active Directory access tokens](./access-tokens.md).

-## ADAL to MSAL migration

-In ADAL4J, the refresh tokens were exposed--which allowed developers to cache them. They would then use `AcquireTokenByRefreshToken()` to enable solutions such as implementing long-running services that refresh dashboards on behalf of the user when the user is no longer connected.

-MSAL for Java doesn't expose refresh tokens for security reasons. Instead, MSAL handles refreshing tokens for you.

-MSAL for Java has an API that allows you to migrate refresh tokens you acquired with ADAL4j into the ClientApplication: [acquireToken(RefreshTokenParameters)](https://javadoc.io/static/com.microsoft.azure/msal4j/1.0.0/com/microsoft/aad/msal4j/PublicClientApplication.html#acquireToken-com.microsoft.aad.msal4j.RefreshTokenParameters-). With this method, you can provide the previously used refresh token along with any scopes (resources) you desire. The refresh token will be exchanged for a new one and cached for use by your application.

-The following code snippet shows some migration code in a confidential client application:

-```java

-String rt = GetCachedRefreshTokenForSignedInUser(); // Get refresh token from where you have them stored

-Set<String> scopes = Collections.singleton("SCOPE_FOR_REFRESH_TOKEN");

-RefreshTokenParameters parameters = RefreshTokenParameters.builder(scopes, rt).build();

-PublicClientApplication app = PublicClientApplication.builder(CLIENT_ID) // ClientId for your application

- .authority(AUTHORITY) //plug in your authority

- .build();

-IAuthenticationResult result = app.acquireToken(parameters);

-```

-The `IAuthenticationResult` returns an access token and ID token, while your new refresh token is stored in the cache.

-The application will also now contain an IAccount:

-```java

-Set<IAccount> accounts = app.getAccounts().join();

-```

-To use the tokens that are now in the cache, call:

-```java

-SilentParameters parameters = SilentParameters.builder(scope, accounts.iterator().next()).build();

-IAuthenticationResult result = app.acquireToken(parameters);

-```

-description: Learn how to migrate your Azure Active Directory Authentication Library (ADAL) Python app to the Microsoft Authentication Library (MSAL) for Python.

-#Customer intent: As a Python application developer, I want to learn how to migrate my v1 ADAL app to v2 MSAL.

-# ADAL to MSAL migration guide for Python

-This article highlights changes you need to make to migrate an app that uses the Azure Active Directory Authentication Library (ADAL) to use the Microsoft Authentication Library (MSAL).

-You can learn more about MSAL and get started with an [overview of the Microsoft Authentication Library](msal-overview.md).

-## Difference highlights

-ADAL works with the Azure Active Directory (Azure AD) v1.0 endpoint. The Microsoft Authentication Library (MSAL) works with the Microsoft identity platform--formerly known as the Azure Active Directory v2.0 endpoint. The Microsoft identity platform differs from Azure AD v1.0 in that it:

-Supports:

- - OAuth v2.0

- - OpenID Connect (OIDC)

-For more information about MSAL, see [MSAL overview](./msal-overview.md).

-### Scopes not resources

-ADAL Python acquires tokens for resources, but MSAL Python acquires tokens for scopes. The API surface in MSAL Python doesn't have resource parameter anymore. You would need to provide scopes as a list of strings that declare the desired permissions and resources that are requested. To see some example of scopes, see [Microsoft Graph's scopes](/graph/permissions-reference).

-You can add the `/.default` scope suffix to the resource to help migrate your apps from the v1.0 endpoint (ADAL) to the Microsoft identity platform (MSAL). For example, for the resource value of `https://graph.microsoft.com`, the equivalent scope value is `https://graph.microsoft.com/.default`. If the resource isn't in the URL form, but a resource ID of the form `XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX`, you can still use the scope value as `XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default`.

-For more details about the different types of scopes, refer to [Permissions and consent in the Microsoft identity platform](./permissions-consent-overview.md) and the [Scopes for a Web API accepting v1.0 tokens](./msal-v1-app-scopes.md) articles.

-### Error handling

-ADAL for Python uses the exception `AdalError` to indicate that there's been a problem. MSAL for Python typically uses error codes, instead. For more information, see [MSAL for Python error handling](msal-error-handling-python.md).

-### API changes

-The following table lists an API in ADAL for Python, and the one to use in its place in MSAL for Python:

-| ADAL for Python API | MSAL for Python API |

-| -- | - |

-| [AuthenticationContext](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext) | [PublicClientApplication](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.__init__) or [ConfidentialClientApplication](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.__init__) |

-| N/A | [PublicClientApplication.acquire_token_interactive()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_interactive) |

-| N/A | [ConfidentialClientApplication.initiate_auth_code_flow()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.initiate_auth_code_flow) |

-| [acquire_token_with_authorization_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_authorization_code) | [ConfidentialClientApplication.acquire_token_by_auth_code_flow()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_by_auth_code_flow) |

-| [acquire_token()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token) | [PublicClientApplication.acquire_token_silent()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_silent) or [ConfidentialClientApplication.acquire_token_silent()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_silent) |

-| [acquire_token_with_refresh_token()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_refresh_token) | These two helpers are intended to be used during [migration](#migrate-existing-refresh-tokens-for-msal-python) only: [PublicClientApplication.acquire_token_by_refresh_token()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_by_refresh_token) or [ConfidentialClientApplication.acquire_token_by_refresh_token()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_by_refresh_token) |

-| [acquire_user_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_user_code) | [initiate_device_flow()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.initiate_device_flow) |

-| [acquire_token_with_device_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_device_code) and [cancel_request_to_get_token_with_device_code()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.cancel_request_to_get_token_with_device_code) | [acquire_token_by_device_flow()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_by_device_flow) |

-| [acquire_token_with_username_password()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_username_password) | [acquire_token_by_username_password()](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.acquire_token_by_username_password) |

-| [acquire_token_with_client_credentials()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_client_credentials) and [acquire_token_with_client_certificate()](https://adal-python.readthedocs.io/en/latest/#adal.AuthenticationContext.acquire_token_with_client_certificate) | [acquire_token_for_client()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_for_client) |

-| N/A | [acquire_token_on_behalf_of()](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.acquire_token_on_behalf_of) |

-| [TokenCache()](https://adal-python.readthedocs.io/en/latest/#adal.TokenCache) | [SerializableTokenCache()](https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache) |

-| N/A | Cache with persistence, available from [MSAL Extensions](https://github.com/marstr/original-microsoft-authentication-extensions-for-python) |

-## Migrate existing refresh tokens for MSAL Python

-MSAL abstracts the concept of refresh tokens. MSAL Python provides an in-memory token cache by default so that you don't need to store, lookup, or update refresh tokens. Users will also see fewer sign-in prompts because refresh tokens can usually be updated without user intervention. For more information about the token cache, see [Custom token cache serialization in MSAL for Python](msal-python-token-cache-serialization.md).

-The following code will help you migrate your refresh tokens managed by another OAuth2 library (including but not limited to ADAL Python) to be managed by MSAL for Python. One reason for migrating those refresh tokens is to prevent existing users from needing to sign in again when you migrate your app to MSAL for Python.

-The method for migrating a refresh token is to use MSAL for Python to acquire a new access token using the previous refresh token. When the new refresh token is returned, MSAL for Python will store it in the cache.

-Since MSAL Python 1.3.0, we provide an API inside MSAL for this purpose.

-Please refer to the following code snippet, quoted from

-[a completed sample of migrating refresh tokens with MSAL Python](https://github.com/AzureAD/microsoft-authentication-library-for-python/blob/1.3.0/sample/migrate_rt.py#L28-L67)

-```python

-import msal

-def get_preexisting_rt_and_their_scopes_from_elsewhere():

- # Maybe you have an ADAL-powered app like this

- # https://github.com/AzureAD/azure-activedirectory-library-for-python/blob/1.2.3/sample/device_code_sample.py#L72

- # which uses a resource rather than a scope,

- # you need to convert your v1 resource into v2 scopes

- # See https://learn.microsoft.com/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources

- # You may be able to append "/.default" to your v1 resource to form a scope

- # See https://learn.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#the-default-scope

- # Or maybe you have an app already talking to the Microsoft identity platform,

- # powered by some 3rd-party auth library, and persist its tokens somehow.

- # Either way, you need to extract RTs from there, and return them like this.

- return [

- ("old_rt_1", ["scope1", "scope2"]),

- ("old_rt_2", ["scope3", "scope4"]),

- ]

-# We will migrate all the old RTs into a new app powered by MSAL

-app = msal.PublicClientApplication(

- "client_id", authority="...",

- # token_cache=... # Default cache is in memory only.

- # You can learn how to use SerializableTokenCache from

- # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache

- )

-# We choose a migration strategy of migrating all RTs in one loop

-for old_rt, scopes in get_preexisting_rt_and_their_scopes_from_elsewhere():

- result = app.acquire_token_by_refresh_token(old_rt, scopes)

- if "error" in result:

- print("Discarding unsuccessful RT. Error: ", json.dumps(result, indent=2))

-print("Migration completed")

-```

-In MSAL 1.x, you created a application instance by initializing a [UserAgentApplication][msal-js-useragentapplication] as follows:

-[msal-js-useragentapplication]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal.useragentapplication.html

-[msal-js-publicclientapplication]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_browser.publicclientapplication.html

-You can use [keytool](https://manpages.debian.org/buster/openjdk-11-jre-headless/keytool.1.en.html) to generate a Base64-encoded signature hash using your app's signing keys, and then use the Azure portal to generate your redirect URI using that hash.

-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.

-1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="/azure/active-directory/develop/media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you registered your application.

-1. Search for and select **Azure Active Directory**.

-1. Under **Manage**, select **App registrations**.

-1. Under **Manage**, select **App registrations**, then select your application.

-1. Under **Manage**, select **Authentication** > **Add a platform** > **Android**.

-The Azure portal generates the redirect URI for you and displays it in the **Android configuration** pane's **Redirect URI** field.

-For more iOS details, see [Migrate iOS applications that use Microsoft Authenticator from ADAL.NET to MSAL.NET](msal-net-migration-ios-broker.md) and [Leveraging the broker on iOS](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Leveraging-the-broker-on-iOS).

- - [Logging in MSAL for Java](msal-logging-java.md)

- - [Logging in MSAL for Python](msal-logging-python.md)

-Learn about [instantiating client applications by using MSAL.NET](msal-net-initializing-client-applications.md) and [instantiating client applications by using MSAL.js](msal-js-initializing-client-applications.md).

-In MSAL.js, you instantiate the [PublicClientApplication](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_browser.publicclientapplication.html) class instead. Like ADAL.js, the constructor expects a [configuration object](#configure-msal) that contains the `clientId` parameter at minimum. See for more: [Initialize MSAL.js](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/initialization.md)

-description: Learn how to handle errors and exceptions, Conditional Access claims challenges, and retries in MSAL.NET.

-# Handle errors and exceptions in MSAL.NET

-## Error handling in MSAL.NET

-### Exception types

-[MsalClientException](/dotnet/api/microsoft.identity.client.msalexception) is thrown when the library itself detects an error state, such as a bad configuration.

-[MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) is thrown when the Identity Provider (Azure AD) returns an error. It's a translation of the server error.

-[MsalUIRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) is type of [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) and indicates that user interaction is required, for example because MFA is required or because the user has changed their password and a token can't be acquired silently.

-### Processing exceptions

-When processing .NET exceptions, you can use the exception type itself and the `ErrorCode` member to distinguish between exceptions. `ErrorCode` values are constants of type [MsalError](/dotnet/api/microsoft.identity.client.msalerror).

-You can also have a look at the fields of [MsalClientException](/dotnet/api/microsoft.identity.client.msalexception), [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception), and [MsalUIRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception).

-If [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) is thrown, try [Authentication and authorization error codes](reference-error-codes.md) to see if the code is listed there.

-If [MsalUIRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) is thrown, it's an indication that an interactive flow needs to happen for the user to resolve the issue. In public client apps such as desktop and mobile app, this is resolved by calling `AcquireTokenInteractive`, which displays a browser. In confidential client apps, web apps should redirect the user to the authorization page, and web APIs should return an HTTP status code and header indicative of the authentication failure (401 Unauthorized and a WWW-Authenticate header).

-### Common .NET exceptions

-Here are the common exceptions that might be thrown and some possible mitigations:

-| Exception | Error code | Mitigation|

-| | | |

-| [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS65001: The user or administrator hasn't consented to use the application with ID '{appId}' named '{appName}'. Send an interactive authorization request for this user and resource.| Get user consent first. If you aren't using .NET Core (which doesn't have any Web UI), call (once only) `AcquireTokeninteractive`. If you're using .NET core or don't want to do an `AcquireTokenInteractive`, the user can navigate to a URL to give consent: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read`. to call `AcquireTokenInteractive`: `app.AcquireTokenInteractive(scopes).WithAccount(account).WithClaims(ex.Claims).ExecuteAsync();`|

-| [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS50079: The user is required to use [multi-factor authentication (MFA)](../authentication/concept-mfa-howitworks.md).| There's no mitigation. If MFA is configured for your tenant and Azure Active Directory (Azure AD) decides to enforce it, fall back to an interactive flow such as `AcquireTokenInteractive`.|

-| [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) |AADSTS90010: The grant type isn't supported over the */common* or */consumers* endpoints. Use the */organizations* or tenant-specific endpoint. You used */common*.| As explained in the message from Azure AD, the authority needs to have a tenant or otherwise */organizations*.|

-| [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) | AADSTS70002: The request body must contain the following parameter: `client_secret or client_assertion`.| This exception can be thrown if your application wasn't registered as a public client application in Azure AD. In the Azure portal, edit the manifest for your application and set `allowPublicClient` to `true`. |

-| [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)| `unknown_user Message`: Couldn't identify logged in user| The library was unable to query the current Windows logged-in user or this user isn't AD or Azure AD joined (work-place joined users aren't supported). Mitigation 1: on UWP, check that the application has the following capabilities: Enterprise Authentication, Private Networks (Client and Server), User Account Information. Mitigation 2: Implement your own logic to fetch the username (for example, john@contoso.com) and use the `AcquireTokenByIntegratedWindowsAuth` form that takes in the username.|

-| [MsalClientException](/dotnet/api/microsoft.identity.client.msalclientexception)|integrated_windows_auth_not_supported_managed_user| This method relies on a protocol exposed by Active Directory (AD). If a user was created in Azure AD without AD backing ("managed" user), this method will fail. Users created in AD and backed by Azure AD ("federated" users) can benefit from this non-interactive method of authentication. Mitigation: Use interactive authentication.|

-### `MsalUiRequiredException`

-One of common status codes returned from MSAL.NET when calling `AcquireTokenSilent()` is `MsalError.InvalidGrantError`. This status code means that the application should call the authentication library again, but in interactive mode (AcquireTokenInteractive or AcquireTokenByDeviceCodeFlow for public client applications, do have a challenge in Web apps). This is because additional user interaction is required before authentication token can be issued.

-Most of the time when `AcquireTokenSilent` fails, it is because the token cache doesn't have tokens matching your request. Access tokens expire in 1 hour, and `AcquireTokenSilent` will try to fetch a new one based on a refresh token (in OAuth2 terms, this is the "Refresh Token' flow). This flow can also fail for various reasons, for example if a tenant admin configures more stringent login policies.

-The interaction aims at having the user do an action. Some of those conditions are easy for users to resolve (for example, accept Terms of Use with a single click), and some can't be resolved with the current configuration (for example, the machine in question needs to connect to a specific corporate network). Some help the user setting-up multi-factor authentication, or install Microsoft Authenticator on their device.

-### `MsalUiRequiredException` classification enumeration

-MSAL exposes a `Classification` field, which you can read to provide a better user experience. For example to tell the user that their password expired or that they'll need to provide consent to use some resources. The supported values are part of the [`UiRequiredExceptionClassification`](/dotnet/api/microsoft.identity.client.uirequiredexceptionclassification) enum:

-| Classification | Meaning | Recommended handling |

-|-|-|-|

-| BasicAction | Condition can be resolved by user interaction during the interactive authentication flow. | Call AcquireTokenInteractively(). |

-| AdditionalAction | Condition can be resolved by additional remedial interaction with the system, outside of the interactive authentication flow. | Call AcquireTokenInteractively() to show a message that explains the remedial action. Calling application may choose to hide flows that require additional_action if the user is unlikely to complete the remedial action. |

-| MessageOnly | Condition can't be resolved at this time. Launching interactive authentication flow will show a message explaining the condition. | Call AcquireTokenInteractively() to show a message that explains the condition. AcquireTokenInteractively() will return UserCanceled error after the user reads the message and closes the window. Calling application may choose to hide flows that result in message_only if the user is unlikely to benefit from the message.|

-| ConsentRequired | User consent is missing, or has been revoked. | Call AcquireTokenInteractively() for user to give consent. |

-| UserPasswordExpired | User's password has expired. | Call AcquireTokenInteractively() so that user can reset their password. |

-| PromptNeverFailed| Interactive Authentication was called with the parameter prompt=never, forcing MSAL to rely on browser cookies and not to display the browser. This has failed. | Call AcquireTokenInteractively() without Prompt.None |

-| AcquireTokenSilentFailed | MSAL SDK doesn't have enough information to fetch a token from the cache. This can be because no tokens are in the cache or an account wasn't found. The error message has more details. | Call AcquireTokenInteractively(). |

-| None | No further details are provided. Condition may be resolved by user interaction during the interactive authentication flow. | Call AcquireTokenInteractively(). |

-## .NET code example

-```csharp

-AuthenticationResult res;

-try

-{

- res = await application.AcquireTokenSilent(scopes, account)

- .ExecuteAsync();

-}

-catch (MsalUiRequiredException ex) when (ex.ErrorCode == MsalError.InvalidGrantError)

-{

- switch (ex.Classification)

- {

- case UiRequiredExceptionClassification.None:

- break;

- case UiRequiredExceptionClassification.MessageOnly:

- // You might want to call AcquireTokenInteractive(). Azure AD will show a message

- // that explains the condition. AcquireTokenInteractively() will return UserCanceled error

- // after the user reads the message and closes the window. The calling application may choose

- // to hide features or data that result in message_only if the user is unlikely to benefit

- // from the message

- try

- {

- res = await application.AcquireTokenInteractive(scopes).ExecuteAsync();

- }

- catch (MsalClientException ex2) when (ex2.ErrorCode == MsalError.AuthenticationCanceledError)

- {

- // Do nothing. The user has seen the message

- }

- break;

- case UiRequiredExceptionClassification.BasicAction:

- // Call AcquireTokenInteractive() so that the user can, for instance accept terms

- // and conditions

- case UiRequiredExceptionClassification.AdditionalAction:

- // You might want to call AcquireTokenInteractive() to show a message that explains the remedial action.

- // The calling application may choose to hide flows that require additional_action if the user

- // is unlikely to complete the remedial action (even if this means a degraded experience)

- case UiRequiredExceptionClassification.ConsentRequired:

- // Call AcquireTokenInteractive() for user to give consent.

-

- case UiRequiredExceptionClassification.UserPasswordExpired:

- // Call AcquireTokenInteractive() so that user can reset their password

-

- case UiRequiredExceptionClassification.PromptNeverFailed:

- // You used WithPrompt(Prompt.Never) and this failed

-

- case UiRequiredExceptionClassification.AcquireTokenSilentFailed:

- default:

- // May be resolved by user interaction during the interactive authentication flow.

- res = await application.AcquireTokenInteractive(scopes)

- .ExecuteAsync(); break;

- }

-}

-```

-When calling an API requiring Conditional Access from MSAL.NET, your application will need to handle claim challenge exceptions. This will appear as an [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) where the [Claims](/dotnet/api/microsoft.identity.client.msalserviceexception.claims) property won't be empty.

-To handle the claim challenge, you'll need to use the `.WithClaim()` method of the [`PublicClientApplicationBuilder`](/dotnet/api/microsoft.identity.client.publicclientapplicationbuilder) class.

-### HTTP error codes 500-600

-MSAL.NET implements a simple retry-once mechanism for errors with HTTP error codes 500-600.

-[MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) surfaces `System.Net.Http.Headers.HttpResponseHeaders` as a property `namedHeaders`. You can use additional information from the error code to improve the reliability of your applications. In the case described, you can use the `RetryAfterproperty` (of type `RetryConditionHeaderValue`) and compute when to retry.

-Here's an example for a daemon application using the client credentials flow. You can adapt this to any of the methods for acquiring a token.

-```csharp

-bool retry = false;

-do

-{

- TimeSpan? delay;

- try

- {

- result = await publicClientApplication.AcquireTokenForClient(scopes, account).ExecuteAsync();

- }

- catch (MsalServiceException serviceException)

- {

- if (serviceException.ErrorCode == "temporarily_unavailable")

- {

- RetryConditionHeaderValue retryAfter = serviceException.Headers.RetryAfter;

- if (retryAfter.Delta.HasValue)

- {

- delay = retryAfter.Delta;

- }

- else if (retryAfter.Date.HasValue)

- {

- delay = (retryAfter.Date.Value ΓÇô DateTimeOffset.Now).TotalMilliseconds;

- }

- }

- }

- // . . .

- if (delay.HasValue)

- {

- Thread.Sleep((int)delay.Value.TotalMilliseconds); // sleep or other

- retry = true;

- }

-} while (retry);

-```

-## Next steps

-Consider enabling [Logging in MSAL.NET](msal-logging-dotnet.md) to help you diagnose and debug issues.

-description: Learn how to handle errors and exceptions, Conditional Access claims challenges, and retries in MSAL4J applications.

-# Handle errors and exceptions in MSAL for Java

-## Error handling in MSAL for Java

-In MSAL for Java, there are three types of exceptions: `MsalClientException`, `MsalServiceException`, and `MsalInteractionRequiredException`; all which inherit from `MsalException`.

-### MsalServiceException

-`MsalServiceException` exposes HTTP headers returned in the requests to the STS. Access them via `MsalServiceException.headers()`

-### MsalInteractionRequiredException

-One of common status codes returned from MSAL for Java when calling `AcquireTokenSilently()` is `InvalidGrantError`. This means that additional user interaction is required before an authentication token can be issued. Your application should call the authentication library again, but in interactive mode by sending `AuthorizationCodeParameters` or `DeviceCodeParameters` for public client applications.

-Most of the time when `AcquireTokenSilently` fails, it's because the token cache doesn't have a token matching your request. Access tokens expire in one hour, and `AcquireTokenSilently` will try to get a new one based on a refresh token. In OAuth2 terms, this is the Refresh Token flow. This flow can also fail for various reasons such as when a tenant admin configures more stringent login policies.

-Some conditions that result in this error are easy for users to resolve. For example, they may need to accept Terms of Use or the request can't be fulfilled with the current configuration because the machine needs to connect to a specific corporate network.

-MSAL exposes a `reason` field, which you can use to provide a better user experience. For example, the `reason` field may lead you to tell the user that their password expired or that they'll need to provide consent to use some resources. The supported values are part of the `InteractionRequiredExceptionReason` enum:

-| Reason | Meaning | Recommended Handling |

-||--|--|

-| `BasicAction` | Condition can be resolved by user interaction during the interactive authentication flow. | Call `acquireToken` with interactive parameters. |

-| `AdditionalAction` | Condition can be resolved by additional remedial interaction with the system outside of the interactive authentication flow. | Call `acquireToken` with interactive parameters to show a message that explains the remedial action to take. The calling app may choose to hide flows that require additional action if the user is unlikely to complete the remedial action. |

-| `MessageOnly` | Condition can't be resolved at this time. Launch interactive authentication flow to show a message explaining the condition. | Call `acquireToken` with interactive parameters to show a message that explains the condition. `acquireToken` will return the `UserCanceled` error after the user reads the message and closes the window. The app may choose to hide flows that result in message if the user is unlikely to benefit from the message. |

-| `ConsentRequired`| User consent is missing, or has been revoked. |Call `acquireToken` with interactive parameters so that the user can give consent. |

-| `UserPasswordExpired` | User's password has expired. | Call `acquireToken` with interactive parameter so the user can reset their password. |

-| `None` | Further details are provided. The condition may be resolved by user interaction during the interactive authentication flow. | Call `acquireToken` with interactive parameters. |

-### Code Example

-```java

- IAuthenticationResult result;

- try {

- PublicClientApplication application = PublicClientApplication

- .builder("clientId")

- .b2cAuthority("authority")

- .build();

- SilentParameters parameters = SilentParameters

- .builder(Collections.singleton("scope"))

- .build();

- result = application.acquireTokenSilently(parameters).join();

- }

- catch (Exception ex){

- if(ex instanceof MsalInteractionRequiredException){

- // AcquireToken by either AuthorizationCodeParameters or DeviceCodeParameters

- } else{

- // Log and handle exception accordingly

- }

- }

-```

-## Next steps

-Consider enabling [Logging in MSAL for Java](msal-logging-java.md) to help you diagnose and debug issues.

-The methods for pop-up experience (`loginPopup`, `acquireTokenPopup`) return promises, so you can use the promise pattern (.then and .catch) to handle them as shown:

-description: Learn how to handle errors and exceptions, Conditional Access claims challenges, and retries in MSAL for Python applications.

-# Handle errors and exceptions in MSAL for Python

-## Error handling in MSAL for Python

-In MSAL for Python, most errors are conveyed as a return value from the API call. The error is represented as a dictionary containing the JSON response from the Microsoft identity platform.

-* A successful response contains the `"access_token"` key. The format of the response is defined by the OAuth2 protocol. For more information, see [5.1 Successful Response](https://tools.ietf.org/html/rfc6749#section-5.1)

-* An error response contains `"error"` and usually `"error_description"`. The format of the response is defined by the OAuth2 protocol. For more information, see [5.2 Error Response](https://tools.ietf.org/html/rfc6749#section-5.2)

-When an error is returned, the `"error"` key contains a machine-readable code. If the `"error"` is, for example, an `"interaction_required"`, you may prompt the user to provide additional information to complete the authentication process. If the `"error"` is `"invalid_grant"`, you may prompt the user to reenter their credentials. The following snippet is an example of error handling in MSAL for Python.

-```python

-from msal import ConfidentialClientApplication

-authority_url = "https://login.microsoftonline.com/your_tenant_id"

-client_id = "your_client_id"

-client_secret = "your_client_secret"

-scopes = ["https://graph.microsoft.com/.default"]

-app = ConfidentialClientApplication(client_id, authority=authority_url, client_credential=client_secret)

-result = app.acquire_token_silent(scopes=scopes, account=None)

-if not result:

- result = app.acquire_token_silent(scopes=scopes)

-if "access_token" in result:

- print("Access token: %s" % result["access_token"])

-else:

- print("Error: %s" % result.get("error"))

-```

-When an error is returned, the `"error_description"` key also contains a human-readable message, and there is typically also an `"error_code"` key which contains a machine-readable Microsoft identity platform error code. For more information about the various Microsoft identity platform error codes, see [Authentication and authorization error codes](./reference-error-codes.md).

-In MSAL for Python, exceptions are rare because most errors are handled by returning an error value. The `ValueError` exception is only thrown when there's an issue with how you're attempting to use the library, such as when API parameter(s) are malformed.

-## Retrying after errors and exceptions

-MSAL makes HTTP calls to the Azure AD service, and occasionally failures can occur.

-For example the network can go down or the server is overloaded.

-MSAL Python 1.11+ automatically performs one retry attempt for you.

-You may customize this behavior by following

-[this instruction](https://msal-python.readthedocs.io/en/latest/#msal.ConfidentialClientApplication.params.http_client).

-### HTTP 429

-When the Service Token Server (STS) is overloaded with too many requests,

-it returns HTTP error 429 with a hint about how long until you can try again in the `Retry-After` response field.

-Your app was expected to throttle the subsequent requests, and only retry after the specified period.

-That was not an easy task.

-MSAL Python 1.16+ made it easy for you, in that your app could blindly retry in any given time

-(say, whenever the end user clicks the sign-in button again),

-MSAL Python 1.16+ would automatically throttle those retry attempts by returning same error response from an HTTP cache,

-and only sending out a real HTTP call when that call is attempted after the specified period.

-By default, this throttle mechanism works by saving throttle information into a built-in in-memory HTTP cache.

-You may provide your own `dict`-like object as the HTTP cache, which you can control how to persist its content.

-See [MSAL Python's API document](https://msal-python.readthedocs.io/en/latest/#msal.PublicClientApplication.params.http_cache)

-for more details.

-## Next steps

-Consider enabling [Logging in MSAL for Python](msal-logging-python.md) to help you diagnose and debug issues.

-> Public preview is provided without a service-level agreement and isn't recommended for production workloads. Some features might be unsupported or have constrained capabilities. For more information, see [Supplemental terms of use for Microsoft Azure previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).

-description: Learn about Active Directory Federation Services (AD FS) support in the Microsoft Authentication Library for Java (MSAL4j).

-#Customer intent: As an application developer, I want to learn about AD FS support in MSAL for Java so I can decide if this platform meets my application development needs and requirements.

-# Active Directory Federation Services support in MSAL for Java

-Active Directory Federation Services (AD FS) in Windows Server enables you to add OpenID Connect and OAuth 2.0 based authentication and authorization to your Microsoft Authentication Library for Java (MSAL for Java) app. Once integrated, your app can authenticate users in AD FS, federated through Azure AD. For more information about scenarios, see [AD FS Scenarios for Developers](/windows-server/identity/ad-fs/ad-fs-development).

-An app that uses MSAL for Java will talk to Azure Active Directory (Azure AD), which then federates to AD FS.

-MSAL for Java connects to Azure AD, which signs in users that are managed in Azure AD (managed users) or users managed by another identity provider such as AD FS (federated users). MSAL for Java doesn't know that a user is federated. It simply talks to Azure AD.

-The [authority](msal-client-application-configuration.md#authority) you use in this case is the usual authority (authority host name + tenant, common, or organizations).

-## Acquire a token interactively for a federated user

-When you call `ConfidentialClientApplication.AcquireToken()` or `PublicClientApplication.AcquireToken()` with `AuthorizationCodeParameters` or `DeviceCodeParameters`, the user experience is typically:

-1. The user enters their account ID.

-2. Azure AD briefly displays "Taking you to your organization's page", and the user is redirected to the sign-in page of the identity provider. The sign-in page is usually customized with the logo of the organization.

-The supported AD FS versions in this federated scenario are:

-## Acquire a token via username and password

-When you acquire a token using `ConfidentialClientApplication.AcquireToken()` or `PublicClientApplication.AcquireToken()` with `IntegratedWindowsAuthenticationParameters` or `UsernamePasswordParameters`, MSAL for Java gets the identity provider to contact based on the username. MSAL for Java gets a [SAML 1.1 token](reference-saml-tokens.md) token from the identity provider, which it then provides to Azure AD which returns the JSON Web Token (JWT).

-## Next steps

-For the federated case, see [Configure Azure Active Directory sign-in behavior for an application by using a Home Realm Discovery policy](../manage-apps/configure-authentication-for-federated-users-portal.md)

-description: Learn how to view and remove accounts from the token cache using the Microsoft Authentication Library for Java.

-#Customer intent: As an application developer using the Microsoft Authentication Library for Java (MSAL4J), I want to learn how to get and remove accounts stored in the token cache.

-# Get and remove accounts from the token cache using MSAL for Java

-MSAL for Java provides an in-memory token cache by default. The in-memory token cache lasts the duration of the application instance.

-## See which accounts are in the cache

-You can check what accounts are in the cache by calling `PublicClientApplication.getAccounts()` as shown in the following example:

-```java

-PublicClientApplication pca = new PublicClientApplication.Builder(

- labResponse.getAppId()).

- authority(TestConstants.ORGANIZATIONS_AUTHORITY).

- build();

-Set<IAccount> accounts = pca.getAccounts().join();

-```

-## Remove accounts from the cache

-To remove an account from the cache, find the account that needs to be removed and then call `PublicClientApplication.removeAccount()` as shown in the following example:

-```java

-Set<IAccount> accounts = pca.getAccounts().join();

-IAccount accountToBeRemoved = accounts.stream().filter(

- x -> x.username().equalsIgnoreCase(

- UPN_OF_USER_TO_BE_REMOVED)).findFirst().orElse(null);

-pca.removeAccount(accountToBeRemoved).join();

-```

-## Learn more

-If you are using MSAL for Java, learn about [Custom token cache serialization in MSAL for Java](msal-java-token-cache-serialization.md).

-description: Learn how to serialize the token cache for MSAL for Java

-#Customer intent: As an application developer using the Microsoft Authentication Library for Java (MSAL4J), I want to learn how to persist the token cache so that it is available to a new instance of my application.

-# Custom token cache serialization in MSAL for Java

-To persist the token cache between instances of your application, you will need to customize the serialization. The Java classes and interfaces involved in token cache serialization are the following:

-Below is a naive implementation of custom serialization of token cache serialization/deserialization. Do not copy and paste this into a production environment.

-```Java

-static class TokenPersistence implements ITokenCacheAccessAspect {

-String data;

-TokenPersistence(String data) {

- this.data = data;

-}

-@Override

-public void beforeCacheAccess(ITokenCacheAccessContext iTokenCacheAccessContext) {

- iTokenCacheAccessContext.tokenCache().deserialize(data);

-}

-@Override

-public void afterCacheAccess(ITokenCacheAccessContext iTokenCacheAccessContext) {

- data = iTokenCacheAccessContext.tokenCache().serialize();

-}

-```

-```Java

-// Loads cache from file

-String dataToInitCache = readResource(this.getClass(), "/cache_data/serialized_cache.json");

-ITokenCacheAccessAspect persistenceAspect = new TokenPersistence(dataToInitCache);

-// By setting *TokenPersistence* on the PublicClientApplication, MSAL will call *beforeCacheAccess()* before accessing the cache and *afterCacheAccess()* after accessing the cache.

-PublicClientApplication app =

-PublicClientApplication.builder("my_client_id").setTokenCacheAccessAspect(persistenceAspect).build();

-```

-## Learn more

-Learn about [Get and remove accounts from the token cache using MSAL for Java](msal-java-get-remove-accounts-token-cache.md).

-Initialize the MSAL 1.x authentication context by instantiating a [UserAgentApplication][msal-js-useragentapplication] with a configuration object. The minimum required configuration property is the `clientID` of your application, shown as **Application (client) ID** on the **Overview** page of the app registration in the Azure portal.

-For authentication methods with redirect flows ([loginRedirect][msal-js-loginredirect] and [acquireTokenRedirect][msal-js-acquiretokenredirect]) in MSAL.js 1.2.x or earlier, you must explicitly register a callback for success or error through the `handleRedirectCallback()` method. Explicitly registering the callback is required in MSAL.js 1.2.x and earlier because redirect flows don't return promises like the methods with a pop-up experience do. Registering the callback is _optional_ in MSAL.js version 1.3.x and later.

-[msal-js-acquiretokenredirect]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal.useragentapplication.html#acquiretokenredirect

-[msal-js-configuration]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal.html#configuration

-[msal-js-handleredirectpromise]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_browser.publicclientapplication.html#handleredirectpromise

-[msal-js-loginredirect]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal.useragentapplication.html#loginredirect

-[msal-js-publicclientapplication]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_browser.publicclientapplication.html

-[msal-js-useragentapplication]: https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal.useragentapplication.html

-description: Learn how to log errors and exceptions in MSAL.NET

-# Logging in MSAL.NET

-## Configure logging in MSAL.NET

-In MSAL, logging is set at application creation using the `.WithLogging` builder modifier. This method takes optional parameters:

-### IIdentityLogger Interface

-```CSharp

-namespace Microsoft.IdentityModel.Abstractions

-{

- public interface IIdentityLogger

- {

- //

- // Summary:

- // Checks to see if logging is enabled at given eventLogLevel.

- //

- // Parameters:

- // eventLogLevel:

- // Log level of a message.

- bool IsEnabled(EventLogLevel eventLogLevel);

- //

- // Summary:

- // Writes a log entry.

- //

- // Parameters:

- // entry:

- // Defines a structured message to be logged at the provided Microsoft.IdentityModel.Abstractions.LogEntry.EventLogLevel.

- void Log(LogEntry entry);

- }

-}

-```

-> [!NOTE]

-> Partner libraries (`Microsoft.Identity.Web`, `Microsoft.IdentityModel`) provide implementations of this interface already for various environments (in particular ASP.NET Core)

-### IIdentityLogger Implementation

-The following code snippets are examples of such an implementation. If you use the .NET core configuration, environment variable driven logs levels can be provided for free, in addition to the configuration file based log levels.

-#### Log level from configuration file

-It's highly recommended to configure your code to use a configuration file in your environment to set the log level as it will enable your code to change the MSAL logging level without needing to rebuild or restart the application. This is critical for diagnostic purposes, enabling us to quickly gather the required logs from the application that is currently deployed and in production. Verbose logging can be costly so it's best to use the *Information* level by default and enable verbose logging when an issue is encountered. [See JSON configuration provider](/aspnet/core/fundamentals/configuration#json-configuration-provider) for an example on how to load data from a configuration file without restarting the application.

-#### Log Level as Environment Variable

-Another option we recommended is to configure your code to use an environment variable on the machine to set the log level as it will enable your code to change the MSAL logging level without needing to rebuild the application. This is critical for diagnostic purposes, enabling us to quickly gather the required logs from the application that is currently deployed and in production.

-See [EventLogLevel](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/blob/dev/src/Microsoft.IdentityModel.Abstractions/EventLogLevel.cs) for details on the available log levels.

-Example:

-```CSharp

- class MyIdentityLogger : IIdentityLogger

- {

- public EventLogLevel MinLogLevel { get; }

- public MyIdentityLogger()

- {

- //Try to pull the log level from an environment variable

- var msalEnvLogLevel = Environment.GetEnvironmentVariable("MSAL_LOG_LEVEL");

- if (Enum.TryParse(msalEnvLogLevel, out EventLogLevel msalLogLevel))

- {

- MinLogLevel = msalLogLevel;

- }

- else

- {

- //Recommended default log level

- MinLogLevel = EventLogLevel.Informational;

- }

- }

- public bool IsEnabled(EventLogLevel eventLogLevel)

- {

- return eventLogLevel <= MinLogLevel;

- }

- public void Log(LogEntry entry)

- {

- //Log Message here:

- Console.WriteLine(entry.message);

- }

- }

-```

-Using `MyIdentityLogger`:

-```CSharp

- MyIdentityLogger myLogger = new MyIdentityLogger(logLevel);

- var app = ConfidentialClientApplicationBuilder

- .Create(TestConstants.ClientId)

- .WithClientSecret("secret")

- .WithExperimentalFeatures() //Currently an experimental feature, will be removed soon

- .WithLogging(myLogger, piiLogging)

- .Build();

-```

-> [!TIP]

- > See the [MSAL.NET wiki](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki) for samples of MSAL.NET logging and more.

-## Next steps

-For more code samples, refer to [Microsoft identity platform code samples](sample-v2-code.md).

-description: Learn how to log errors and exceptions in MSAL for Java

-# Logging in MSAL for Java

-## MSAL for Java logging

-MSAL for Java allows you to use the logging library that you're already using with your app, as long as it's compatible with SLF4J. MSAL for Java uses the [Simple Logging Facade for Java](http://www.slf4j.org/) (SLF4J) as a simple facade or abstraction for various logging frameworks, such as [java.util.logging](https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html), [Logback](http://logback.qos.ch/) and [Log4j](https://logging.apache.org/log4j/2.x/). SLF4J allows the user to plug in the desired logging framework at deployment time and automatically binds to Logback at deployment time. MSAL logs will be written to the console.

-This article shows how to enable MSAL4J logging using the logback framework in a spring boot web application. You can refer to the [code sample](https://github.com/Azure-Samples/ms-identity-java-webapp/tree/master/msal-java-webapp-sample) for reference.

-1. To implement logging, include the `logback` package in the *pom.xml* file.

- ```xml

- <dependency>

- <groupId>ch.qos.logback</groupId>

- <artifactId>logback-classic</artifactId>

- <version>1.2.3</version>

- </dependency>

- ```

-2. Navigate to the *resources* folder, and add a file called *logback.xml*, and insert the following code. This will append logs to the console. You can change the appender `class` to write logs to a file, database or any appender of your choosing.

- ```xml

- <?xml version="1.0" encoding="UTF-8"?>

- <configuration>

- <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">

- <encoder>

- <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>

- </encoder>

- </appender>

- <root level="debug">

- <appender-ref ref="STDOUT" />

- </root>

- </configuration>

- ```

-3. Next, you should set the *logging.config* property to the location of the *logback.xml* file before the main method. Navigate to *MsalWebSampleApplication.java* and add the following code to the `MsalWebSampleApplication` public class.

- ```java

- @SpringBootApplication

- public class MsalWebSampleApplication {

- static { System.setProperty("logging.config", "C:\Users\<your path>\src\main\resources\logback.xml"); }

- public static void main(String[] arrgs) {

- // Console.log("main");

- // System.console().printf("Hello");

- // System.out.printf("Hello %s!%n", "World");

- System.out.printf("%s%n", "Hello World");

- SpringApplication.run(MsalWebSampleApplication.class, args);

- }

- }

- ```

-

-In your tenant, you'll need separate app registrations for the web app and the web API. For app registration and exposing the web API scope, follow the steps in the scenario [A web app that authenticates users and calls web APIs](./scenario-web-app-call-api-overview.md).

-For instructions on how to bind to other logging frameworks, see the [SLF4J manual](http://www.slf4j.org/manual.html).

-### Personal and organization information

-By default, MSAL logging doesn't capture or log any personal or organizational data. In the following example, logging personal or organizational data is off by default:

-```java

- PublicClientApplication app2 = PublicClientApplication.builder(PUBLIC_CLIENT_ID)

- .authority(AUTHORITY)

- .build();

-```

-Turn on personal and organizational data logging by setting `logPii()` on the client application builder. If you turn on personal or organizational data logging, your app must take responsibility for safely handling highly-sensitive data and complying with any regulatory requirements.

-In the following example, logging personal or organizational data is enabled:

-```java

-PublicClientApplication app2 = PublicClientApplication.builder(PUBLIC_CLIENT_ID)

- .authority(AUTHORITY)

- .logPii(true)

- .build();

-```

-## Next steps

-For more code samples, refer to [Microsoft identity platform code samples](sample-v2-code.md).

-description: Learn how to log errors and exceptions in MSAL for Python

-# Logging in MSAL for Python

-## MSAL for Python logging

-Logging in MSAL for Python leverages the [logging module in the Python standard library](https://docs.python.org/3/library/logging.html). You can configure MSAL logging as follows (and see it in action in the [username_password_sample](https://github.com/AzureAD/microsoft-authentication-library-for-python/blob/1.0.0/sample/username_password_sample.py#L31L32)):

-### Enable debug logging for all modules

-By default, the logging in any Python script is turned off. If you want to enable verbose logging for **all** Python modules in your script, use `logging.basicConfig` with a level of `logging.DEBUG`:

-```python

-import logging

-logging.basicConfig(level=logging.DEBUG)

-```

-This will print all log messages given to the logging module to the standard output.

-### Configure MSAL logging level

-You can configure the logging level of the MSAL for Python log provider by using the `logging.getLogger()` method with the logger name `"msal"`:

-```python

-import logging

-logging.getLogger("msal").setLevel(logging.WARN)

-```

-### Configure MSAL logging with Azure App Insights

-Python logs are given to a log handler, which by default is the `StreamHandler`. To send MSAL logs to an Application Insights with an Instrumentation Key, use the `AzureLogHandler` provided by the `opencensus-ext-azure` library.

-To install, `opencensus-ext-azure` add the `opencensus-ext-azure` package from PyPI to your dependencies or pip install:

-```console

-pip install opencensus-ext-azure

-```

-Then change the default handler of the `"msal"` log provider to an instance of `AzureLogHandler` with an instrumentation key set in the `APP_INSIGHTS_KEY` environment variable:

-```python

-import logging

-import os

-from opencensus.ext.azure.log_exporter import AzureLogHandler

-APP_INSIGHTS_KEY = os.getenv('APP_INSIGHTS_KEY')

-logging.getLogger("msal").addHandler(AzureLogHandler(connection_string='InstrumentationKey={0}'.format(APP_INSIGHTS_KEY)))

-```

-### Personal and organizational data in Python

-MSAL for Python does not log personal data or organizational data. There is no property to turn personal or organization data logging on or off.

-You can use standard Python logging to log whatever you want, but you are responsible for safely handling sensitive data and following regulatory requirements.

-For more information about logging in Python, please refer to Python's [Logging: how-to](https://docs.python.org/3/howto/logging.html#logging-basic-tutorial).

-## Next steps

-For more code samples, refer to [Microsoft identity platform code samples](sample-v2-code.md).

-description: Learn how to acquire an access token silently (from the token cache) using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn how how to use the AcquireTokenSilent method so I can acquire tokens from the cache.

-# Get a token from the token cache using MSAL.NET

-When you acquire an access token using the Microsoft Authentication Library for .NET (MSAL.NET), the token is cached. When the application needs a token, it should first attempt to fetch it from the cache.

-You can monitor the source of the tokens by inspecting the [`AuthenticationResult.AuthenticationResultMetadata.TokenSource`](/dotnet/api/microsoft.identity.client.authenticationresultmetadata.tokensource?view=msal-dotnet-latest&preserve-view=true) property.

-## Websites and web APIs

-ASP.NET Core and ASP.NET Classic websites should integrate with [Microsoft.Identity.Web](microsoft-identity-web.md), a wrapper for MSAL.NET. Memory token caching or distributed token caching can be configured as described in [token cache serialization](msal-net-token-cache-serialization.md?tabs=aspnetcore).

-Web APIs on ASP.NET Core should use Microsoft.Identity.Web. Web APIs on ASP.NET classic, use MSAL directly, by calling `AcquireTokenOnBehalfOf` and should configure memory or distributed caching. For more information, see [Token cache serialization in MSAL.NET](msal-net-token-cache-serialization.md?tabs=aspnet). There's no reason to call the `AcquireTokenSilent` API as there's no API to clear the cache. Cache size can be managed by setting eviction policies on the underlying cache store, such as MemoryCache, Redis etc.

-## Web service / Daemon apps

-Applications that request tokens for an app identity, with no user involved, by calling `AcquireTokenForClient` can either rely on MSAL's internal caching, define their own memory token caching or distributed token caching. For instructions and more information, see [Token cache serialization in MSAL.NET](msal-net-token-cache-serialization.md?tabs=aspnet).

-Since no user is involved, there's no reason to call `AcquireTokenSilent`. `AcquireTokenForClient` will look in the cache on its own as there's no API to clear the cache. Cache size is proportional with the number of tenants and resources you need tokens for. Cache size can be managed by setting eviction policies on the underlying cache store, such as MemoryCache, Redis, etc.

-## Desktop, command-line, and mobile applications

-Desktop, command-line, and mobile applications should first call the `AcquireTokenSilent` method to verify if an acceptable token is in the cache. In many cases, it's possible to acquire another token with more scopes based on a token in the cache. It's also possible to refresh a token when it's getting close to expiration (as the token cache also contains a refresh token).

-For authentication flows that require a user interaction, MSAL caches the access, refresh, and ID tokens, and the `IAccount` object, which represents information about a single account. Learn more about [IAccount](/dotnet/api/microsoft.identity.client.iaccount?view=msal-dotnet-latest&preserve-view=true). For application flows, such as [client credentials](msal-authentication-flows.md#client-credentials), only access tokens are cached, because the `IAccount` object and ID token require a user, and the refresh token isn't applicable.

-The recommended pattern is to call the `AcquireTokenSilent` method first. If `AcquireTokenSilent` fails, then acquire a token using other methods.

-In the following example, the application first attempts to acquire a token from the token cache. If a `MsalUiRequiredException` exception is thrown, the application acquires a token interactively.

-```csharp

-var accounts = await app.GetAccountsAsync();

-AuthenticationResult result = null;

-try

-{

- result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())

- .ExecuteAsync();

-}

-catch (MsalUiRequiredException ex)

-{

- // A MsalUiRequiredException happened on AcquireTokenSilent.

- // This indicates you need to call AcquireTokenInteractive to acquire a token

- Debug.WriteLine($"MsalUiRequiredException: {ex.Message}");

- try

- {

- result = await app.AcquireTokenInteractive(scopes)

- .ExecuteAsync();

- }

- catch (MsalException msalex)

- {

- ResultText.Text = $"Error Acquiring Token:{System.Environment.NewLine}{msalex}";

- }

-}

-catch (Exception ex)

-{

- ResultText.Text = $"Error Acquiring Token Silently:{System.Environment.NewLine}{ex}";

- return;

-}

-if (result != null)

-{

- string accessToken = result.AccessToken;

- // Use the token

-}

-```

-### Clearing the cache

-In public client applications, removing accounts from the cache will clear it. However, this doesn't remove the session cookie, which is in the browser.

-```csharp

-var accounts = (await app.GetAccountsAsync()).ToList();

-// clear the cache

-while (accounts.Any())

-{

- await app.RemoveAsync(accounts.First());

- accounts = (await app.GetAccountsAsync()).ToList();

-}

-```

-description: Learn about Active Directory Federation Services (AD FS) support in the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn about AD FS support in MSAL.NET so I can decide if this platform meets my application development needs and requirements.

-# Active Directory Federation Services support in MSAL.NET

-Active Directory Federation Services (AD FS) in Windows Server enables you to add OpenID Connect and OAuth 2.0 based authentication and authorization to applications you are developing. Those applications can, then, authenticate users directly against AD FS. For more information, read [AD FS Scenarios for Developers](/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios).

-Microsoft Authentication Library for .NET (MSAL.NET) supports two scenarios for authenticating against AD FS:

-## MSAL connects to Azure AD, which is federated with AD FS

-MSAL.NET supports connecting to Azure AD, which signs in managed-users (users managed in Azure AD) or federated users (users managed by another identity provider such as AD FS). MSAL.NET does not know about the fact that users are federated. As far as itΓÇÖs concerned, it talks to Azure AD.

-The [authority](msal-client-application-configuration.md#authority) you use in this case is the usual authority (authority host name + tenant, common, or organizations).

-### Acquiring a token interactively

-When you call the `AcquireTokenInteractive` method, the user experience is typically:

-1. The user enters their account ID.

-2. Azure AD displays briefly the message "Taking you to your organization's page".

-3. The user is redirected to the sign-in page of the identity provider. The sign-in page is usually customized with the logo of the organization.

-Supported AD FS versions in this federated scenario are AD FS v2, AD FS v3 (Windows Server 2012 R2), and AD FS v4 (AD FS 2016).

-### Acquiring a token using AcquireTokenByIntegratedAuthentication or AcquireTokenByUsernamePassword

-When acquiring a token using the `AcquireTokenByIntegratedAuthentication` or `AcquireTokenByUsernamePassword` methods, MSAL.NET gets the identity provider to contact based on the username. MSAL.NET receives a [SAML 1.1 token](reference-saml-tokens.md) after contacting the identity provider. MSAL.NET then provides the SAML token to Azure AD as a user assertion (similar to the [on-behalf-of flow](msal-authentication-flows.md#on-behalf-of-obo) to get back a JWT.

-## MSAL connects directly to AD FS

-MSAL.NET supports connecting to AD FS 2019, which is Open ID Connect compliant and understands PKCE and scopes. This support requires that a service pack [KB 4490481](https://support.microsoft.com/help/4490481/windows-10-update-kb4490481) is applied to Windows Server. When connecting directly to AD FS, the authority you'll want to use to build your application is similar to `https://mysite.contoso.com/adfs/`.

-Currently, there are no plans to support a direct connection to:

- If you need to support scenarios requiring a direct connection to AD FS 2016, use the latest version of [Azure Active Directory Authentication Library](../azuread-dev/active-directory-authentication-libraries.md#microsoft-supported-client-libraries). When you have upgraded your on-premises system to AD FS 2019, you'll be able to use MSAL.NET.

-## Next steps

-For the federated case, see [Configure Azure Active Directory sign-in behavior for an application by using a Home Realm Discovery policy](../manage-apps/configure-authentication-for-federated-users-portal.md)

-description: Considerations when using Azure AD B2C with the Microsoft Authentication Library for .NET (MSAL.NET).

-# Customer intent: As an application developer, I want to learn about specific considerations when using Azure AD B2C and MSAL.NET so I can decide if this platform meets my application development needs and requirements.

-# Use MSAL.NET to sign in users with social identities

-You can use MSAL.NET to sign in users with social identities by using [Azure Active Directory B2C (Azure AD B2C)](../../active-directory-b2c/overview.md). Azure AD B2C is built around the notion of policies. In MSAL.NET, specifying a policy translates to providing an authority.

-This article applies to MSAL.NET 3.x. For MSAL.NET 2.x, see [Azure AD B2C specifics in MSAL 2.x](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/AAD-B2C-Specifics-MSAL-2.x) in the MSAL.NET Wiki on GitHub.

-## Authority for an Azure AD B2C tenant and policy

-The authority format for Azure AD B2C is: `https://{azureADB2CHostname}/tfp/{tenant}/{policyName}`

-For more information about Azure AD B2C authorities, see [Set redirect URLs to b2clogin.com](../../active-directory-b2c/b2clogin.md).

-## Instantiating the application

-Provide the authority by calling `WithB2CAuthority()` when you create the application object:

-```csharp

-// Azure AD B2C Coordinates

-public static string Tenant = "fabrikamb2c.onmicrosoft.com";

-public static string AzureADB2CHostname = "fabrikamb2c.b2clogin.com";

-public static string ClientID = "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6";

-public static string PolicySignUpSignIn = "b2c_1_susi";

-public static string PolicyEditProfile = "b2c_1_edit_profile";

-public static string PolicyResetPassword = "b2c_1_reset";

-public static string AuthorityBase = $"https://{AzureADB2CHostname}/tfp/{Tenant}/";

-public static string Authority = $"{AuthorityBase}{PolicySignUpSignIn}";

-public static string AuthorityEditProfile = $"{AuthorityBase}{PolicyEditProfile}";

-public static string AuthorityPasswordReset = $"{AuthorityBase}{PolicyResetPassword}";

-application = PublicClientApplicationBuilder.Create(ClientID)

- .WithB2CAuthority(Authority)

- .Build();

-```

-## Acquire a token to apply a policy

-Acquiring a token for an Azure AD B2C-protected API in a public client application requires you to use the overrides with an authority:

-```csharp

-AuthenticationResult authResult = null;

-IEnumerable<IAccount> accounts = await application.GetAccountsAsync(policy);

-IAccount account = accounts.FirstOrDefault();

-try

-{

- authResult = await application.AcquireTokenSilent(scopes, account)

- .ExecuteAsync();

-}

-catch (MsalUiRequiredException ex)

-{

- authResult = await application.AcquireTokenInteractive(scopes)

- .WithAccount(account)

- .WithParentActivityOrWindow(ParentActivityOrWindow)

- .ExecuteAsync();

-}

-```

-In the preceding code snippet:

-Applying a user flow or custom policy (for example, letting the user edit their profile or reset their password) is currently done by calling `AcquireTokenInteractive`. For these two policies, you don't use the returned token/authentication result.

-## Profile edit policies

-To enable your users to sign in with a social identity and then edit their profile, apply the Azure AD B2C edit profile policy.

-Do so by calling `AcquireTokenInteractive` with the authority for that policy. Because the user is already signed in and has an active cookie session, use `Prompt.NoPrompt` to prevent the account selection dialog from being displayed.

-```csharp

-private async void EditProfileButton_Click(object sender, RoutedEventArgs e)

-{

- IEnumerable<IAccount> accounts = await application.GetAccountsAsync(PolicyEditProfile);

- IAccount account = accounts.FirstOrDefault();

- try

- {

- var authResult = await application.AcquireTokenInteractive(scopes)

- .WithPrompt(Prompt.NoPrompt),

- .WithAccount(account)

- .WithB2CAuthority(AuthorityEditProfile)

- .ExecuteAsync();

- }

- catch

- {

- }

-}

-```

-## Resource owner password credentials (ROPC)

-For more information on the ROPC flow, see [Sign in with resource owner password credentials grant](v2-oauth-ropc.md).

-The ROPC flow is **not recommended** because asking a user for their password in your application isn't secure. For more information about this problem, see [WhatΓÇÖs the solution to the growing problem of passwords?](https://news.microsoft.com/features/whats-solution-growing-problem-passwords-says-microsoft/).

-By using username/password in an ROPC flow, you sacrifice several things:

-### Configure the ROPC flow in Azure AD B2C

-In your Azure AD B2C tenant, create a new user flow and select **Sign in using ROPC** to enable ROPC for the user flow. For more information, see [Configure the resource owner password credentials flow](../../active-directory-b2c/add-ropc-policy.md).

-`IPublicClientApplication` contains the `AcquireTokenByUsernamePassword` method:

-```csharp

-AcquireTokenByUsernamePassword(

- IEnumerable<string> scopes,

- string username,

- SecureString password)

-```

-The `AcquireTokenByUsernamePassword` method takes the following parameters:

-### Limitations of the ROPC flow

-The ROPC flow **only works for local accounts**, where your users have registered with Azure AD B2C using an email address or username. This flow doesn't work when federating to an external identity provider supported by Azure AD B2C (Facebook, Google, etc.).

-## Google auth and embedded webview

-If you're using Google as an identity provider, we recommend you use the system browser as Google doesn't allow [authentication from embedded webviews](https://developers.googleblog.com/2016/08/modernizing-oauth-interactions-in-native-apps.html). Currently, `login.microsoftonline.com` is a trusted authority with Google and will work with embedded webview. However, `b2clogin.com` isn't a trusted authority with Google, so users won't be able to authenticate.

-## Token caching in MSAL.NET

-### Known issue with Azure AD B2C

-MSAL.NET supports a [token cache](/dotnet/api/microsoft.identity.client.tokencache). The token caching key is based on the claims returned by the identity provider (IdP).

-Currently, MSAL.NET needs two claims to build a token cache key:

-Both of these claims may be missing in Azure AD B2C scenarios because not all social identity providers (Facebook, Google, and others) return them in the tokens they return to Azure AD B2C.

-A symptom of such a scenario is that MSAL.NET returns `Missing from the token response` when you access the `preferred_username` claim value in tokens issued by Azure AD B2C. MSAL uses the `Missing from the token response` value for `preferred_username` to maintain cache cross-compatibility between libraries.

-### Workarounds

-#### Mitigation for missing tenant ID

-The suggested workaround is to use [caching by policy](#acquire-a-token-to-apply-a-policy) described earlier.

-Alternatively, you can use the `tid` claim if you're using [custom policies](../../active-directory-b2c/user-flow-overview.md) in Azure AD B2C. Custom policies can return additional claims to your application by using [claims transformation](../../active-directory-b2c/claims-transformation-technical-profile.md).

-#### Mitigation for "Missing from the token response"

-One option is to use the `name` claim instead of `preferred_username`. To include the `name` claim in ID tokens issued by Azure AD B2C, select **Display Name** when you configure your user flow.

-For more information about specifying which claims are returned by your user flows, see [Tutorial: Create user flows in Azure AD B2C](../../active-directory-b2c/tutorial-create-user-flows.md).

-## Next steps

-More details about acquiring tokens interactively with MSAL.NET for Azure AD B2C applications are provided in the following sample.

-| Sample | Platform | Description |

-| -- | | |

-| [active-directory-b2c-xamarin-native](https://github.com/Azure-Samples/active-directory-b2c-xamarin-native) | Xamarin iOS, Xamarin Android, UWP | A Xamarin Forms app that uses MSAL.NET to authenticate users via Azure AD B2C and then access a web API with the tokens returned. |

-description: Learn how to clear the token cache using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn how how to clear the token cache so I can .

-# Clear the token cache using MSAL.NET

-## Web API and daemon apps

-There is no API to remove the tokens from the cache. Cache size should be handled by setting eviction policies on the underlying storage. See [Cache Serialization](msal-net-token-cache-serialization.md?tabs=aspnetcore) for details on how to use a memory cache or distributed cache.

-## Desktop, command line and mobile applications

-When you [acquire an access token](msal-acquire-cache-tokens.md) using the Microsoft Authentication Library for .NET (MSAL.NET), the token is cached. When the application needs a token, it should first call the `AcquireTokenSilent` method to verify if an acceptable token is in the cache.

-Clearing the cache is achieved by removing the accounts from the cache. This does not remove the session cookie which is in the browser, though. The following example instantiates a public client application, gets the accounts for the application, and removes the accounts.

-```csharp

-private readonly IPublicClientApplication _app;

-private static readonly string ClientId = ConfigurationManager.AppSettings["ida:ClientId"];

-private static readonly string Authority = string.Format(CultureInfo.InvariantCulture, AadInstance, Tenant);

-_app = PublicClientApplicationBuilder.Create(ClientId)

- .WithAuthority(Authority)

- .Build();

-var accounts = (await _app.GetAccountsAsync()).ToList();

-// clear the cache

-while (accounts.Any())

-{

- await _app.RemoveAsync(accounts.First());

- accounts = (await _app.GetAccountsAsync()).ToList();

-}

-```

-To learn more about acquiring and caching tokens, read [acquire an access token](msal-acquire-cache-tokens.md).

-description: Learn about signed client assertions support for confidential client applications in the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn how to use client assertions to prove the identity of my confidential client application

-# Confidential client assertions

-In order to prove their identity, confidential client applications exchange a secret with Azure AD. The secret can be:

-This secret can also be a signed assertion directly.

-MSAL.NET has four methods to provide either credentials or assertions to the confidential client app:

-> [!NOTE]

-> While it is possible to use the `WithClientAssertion()` API to acquire tokens for the confidential client, we do not recommend using it by default as it is more advanced and is designed to handle very specific scenarios which are not common. Using the `.WithCertificate()` API will allow MSAL.NET to handle this for you. This api offers you the ability to customize your authentication request if needed but the default assertion created by `.WithCertificate()` will suffice for most authentication scenarios. This API can also be used as a workaround in some scenarios where MSAL.NET fails to perform the signing operation internally. The difference between the two is using the `WithCertificate()` requires the certificate and private key to be available on the machine creating the assertion, and using the `WithClientAssertion()` allows you to compute the assertion somewhere else, like inside the Azure Key Vault or from Managed Identity, or with a Hardware security module.

-### Client assertions

-This is useful if you want to handle the certificate yourself. For example, if you wish to use Azure KeyVault's APIs for signing, which eliminates the need for downloading the certificates. A signed client assertion takes the form of a signed JWT with the payload containing the required authentication claims mandated by Azure AD, Base64 encoded. To use it:

-```csharp

-string signedClientAssertion = ComputeAssertion();

-app = ConfidentialClientApplicationBuilder.Create(config.ClientId)

- .WithClientAssertion(signedClientAssertion)

- .Build();

-```

-You can also use the delegate form, which enables you to compute the assertion just in time:

-```csharp

-string signedClientAssertion = ComputeAssertion();

-app = ConfidentialClientApplicationBuilder.Create(config.ClientId)

- .WithClientAssertion(async (AssertionRequestOptions options) => {

- // use 'options.ClientID' or 'options.TokenEndpoint' to generate client assertion

- return await GetClientAssertionAsync(options.ClientID, options.TokenEndpoint, options.CancellationToken);

- })

- .Build();

-```

-The [claims expected by Azure AD](./certificate-credentials.md) in the signed assertion are:

-Claim type | Value | Description

-aud | `https://login.microsoftonline.com/{tenantId}/v2.0/token` | The "aud" (audience) claim identifies the recipients that the JWT is intended for (here Azure AD) See [RFC 7519, Section 4.1.3](https://tools.ietf.org/html/rfc7519#section-4.1.3). In this case, that recipient is the token endpoint of the identity provider

-exp | 1601519414 | The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. See [RFC 7519, Section 4.1.4](https://tools.ietf.org/html/rfc7519#section-4.1.4). This allows the assertion to be used until then, so keep it short - 5-10 minutes after `nbf` at most. Azure AD does not place restrictions on the `exp` time currently.

-iss | {ClientID} | The "iss" (issuer) claim identifies the principal that issued the JWT, in this case your client application. Use the GUID application ID.

-jti | (a Guid) | The "jti" (JWT ID) claim provides a unique identifier for the JWT. The identifier value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object; if the application uses multiple issuers, collisions MUST be prevented among values produced by different issuers as well. The "jti" value is a case-sensitive string. [RFC 7519, Section 4.1.7](https://tools.ietf.org/html/rfc7519#section-4.1.7)

-nbf | 1601519114 | The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing. [RFC 7519, Section 4.1.5](https://tools.ietf.org/html/rfc7519#section-4.1.5). Using the current time is appropriate.

-sub | {ClientID} | The "sub" (subject) claim identifies the subject of the JWT, in this case also your application. Use the same value as `iss`.

-If you use a certificate as a client secret, the certificate must be deployed safely. We recommend that you store the certificate in a secure spot supported by the platform, such as in the certificate store on Windows or by using Azure Key Vault.

-### Crafting the asssertion

-This is an example using [Microsoft.IdentityModel.JsonWebTokens](https://www.nuget.org/packages/Microsoft.IdentityModel.JsonWebTokens/) to create the assertion for you.

-```csharp

- string GetSignedClientAssertion(X509Certificate2 certificate, string tenantId, string clientId)

- {

- // no need to add exp, nbf as JsonWebTokenHandler will add them by default.

- var claims = new Dictionary<string, object>()

- {

- { "aud", tokenEndpoint },

- { "iss", clientId },

- { "jti", Guid.NewGuid().ToString() },

- { "sub", clientId }

- };

- var securityTokenDescriptor = new SecurityTokenDescriptor

- {

- Claims = claims,

- SigningCredentials = new X509SigningCredentials(certificate)

- };

- var handler = new JsonWebTokenHandler();

- var signedClientAssertion = handler.CreateToken(securityTokenDescriptor);

- }

-```

-Alternatively, if you do not wish to use Microsoft.IdentityModel.JsonWebTokens:

-```csharp

-static string Base64UrlEncode(byte[] arg)

-{

- char Base64PadCharacter = '=';

- char Base64Character62 = '+';

- char Base64Character63 = '/';

- char Base64UrlCharacter62 = '-';

- char Base64UrlCharacter63 = '_';

- string s = Convert.ToBase64String(arg);

- s = s.Split(Base64PadCharacter)[0]; // RemoveAccount any trailing padding

- s = s.Replace(Base64Character62, Base64UrlCharacter62); // 62nd char of encoding

- s = s.Replace(Base64Character63, Base64UrlCharacter63); // 63rd char of encoding

- return s;

-}

-static string GetSignedClientAssertion(X509Certificate2 certificate, string tenantId, string clientId)

-{

- // Get the RSA with the private key, used for signing.

- var rsa = certificate.GetRSAPrivateKey();

- //alg represents the desired signing algorithm, which is SHA-256 in this case

- //x5t represents the certificate thumbprint base64 url encoded

- var header = new Dictionary<string, string>()

- {

- { "alg", "RS256"},

- { "typ", "JWT" },

- { "x5t", Base64UrlEncode(certificate.GetCertHash()) }

- };

- //Please see the previous code snippet on how to craft claims for the GetClaims() method

- var claims = GetClaims(tenantId, clientId);

- var headerBytes = JsonSerializer.SerializeToUtf8Bytes(header);

- var claimsBytes = JsonSerializer.SerializeToUtf8Bytes(claims);

- string token = Base64UrlEncode(headerBytes) + "." + Base64UrlEncode(claimsBytes);

- string signature = Base64UrlEncode(rsa.SignData(Encoding.UTF8.GetBytes(token), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1));

- string signedClientAssertion = string.Concat(token, ".", signature);

- return signedClientAssertion;

-}

-```

-### WithClientClaims

-In some cases, developers want to inject some claims into the assertions, but would still like MSAL to handle the creation of the assertion and the signing.

-`WithClientClaims(X509Certificate2 certificate, IDictionary<string, string> claimsToSign, bool mergeWithDefaultClaims = true)` will produce a signed assertion containing the claims expected by Azure AD plus additional client claims that you want to send.

-```csharp

-string ipAddress = "192.168.1.2";

-X509Certificate2 certificate = ReadCertificate(config.CertificateName);

-app = ConfidentialClientApplicationBuilder.Create(config.ClientId)

- .WithAuthority(new Uri(config.Authority))

- .WithClientClaims(certificate,

- new Dictionary<string, string> { { "client_ip", ipAddress } })

- .Build();

-```

-If one of the claims in the dictionary that you pass in is the same as one of the mandatory claims, the additional claim's value will be taken into account. It will override the claims computed by MSAL.NET.

-If you want to provide your own claims, including the mandatory claims expected by Azure AD, pass in `false` for the `mergeWithDefaultClaims` parameter.

-description: Learn about the differences between the Microsoft Authentication Library for .NET (MSAL.NET) and Azure AD Authentication Library for .NET (ADAL.NET).

-#Customer intent: As an application developer, I want to learn about the differences between the ADAL.NET and MSAL.NET libraries so I can migrate my applications to MSAL.NET.

-# Differences between ADAL.NET and MSAL.NET apps

-Migrating your applications from using ADAL to using MSAL comes with security and resiliency benefits. This article outlines differences between MSAL.NET and ADAL.NET. All new applications should use MSAL.NET and the Microsoft identity platform, which is the latest generation of Microsoft Authentication Libraries. Using MSAL.NET, you acquire tokens for users signing-in to your application with Azure AD (work and school accounts), Microsoft (personal) accounts (MSA), or Azure AD B2C. If you have an existing application that is using ADAL.NET, migrate it to MSAL.NET.

-You still need to use ADAL.NET if your application needs to sign in users with earlier versions of [Active Directory Federation Services (ADFS)](/windows-server/identity/active-directory-federation-services). For more information, see [ADFS support](https://aka.ms/msal-net-adfs-support).

-## Prerequisites

-Go through [MSAL overview](./msal-overview.md) to learn more about MSAL.

-## Differences

-| | **ADAL NET** | **MSAL NET** |

-|--|--||

-| **NuGet packages and Namespaces** |ADAL was consumed from the [Microsoft.IdentityModel.Clients.ActiveDirectory](https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory) NuGet package. The namespace was `Microsoft.IdentityModel.Clients.ActiveDirectory`. | Add the [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) NuGet package, and use the `Microsoft.Identity.Client` namespace. If you're building a confidential client application, check out [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web). |

-| **Scopes and resources** | ADAL.NET acquires tokens for *resources*. | MSAL.NET acquires tokens for *scopes*. Several MSAL.NET `AcquireTokenXXX` overrides require a parameter called scopes(`IEnumerable<string> scopes`). This parameter is a simple list of strings that declare the permissions and resources that are requested. Well-known scopes are the [Microsoft Graph's scopes](/graph/permissions-reference). You can also [access v1.0 resources using MSAL.NET](#scopes). |

-| **Core classes** | ADAL.NET used [AuthenticationContext](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/AuthenticationContext:-the-connection-to-Azure-AD) as the representation of your connection to the Security Token Service (STS) or authorization server, through an Authority. | MSAL.NET is designed around [client applications](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Client-Applications). It defines `IPublicClientApplication` interfaces for public client applications and `IConfidentialClientApplication` for confidential client applications, as well as a base interface `IClientApplicationBase` for the contract common to both types of applications.|

-| **Token acquisition** | In public clients, ADAL uses `AcquireTokenAsync` and `AcquireTokenSilentAsync` for authentication calls. | In public clients, MSAL uses `AcquireTokenInteractive` and `AcquireTokenSilent` for the same authentication calls. The parameters are different from the ADAL ones. <br><br>In Confidential client applications, there are [token acquisition methods](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Acquiring-Tokens) with an explicit name depending on the scenario. Another difference is that, in MSAL.NET, you no longer have to pass in the `ClientID` of your application in every AcquireTokenXX call. The `ClientID` is set only once when building `IPublicClientApplication` or `IConfidentialClientApplication`.|

-| **IAccount and IUser** | ADAL defines the notion of user through the IUser interface. However, a user is a human or a software agent. As such, a user can own one or more accounts in the Microsoft identity platform (several Azure AD accounts, Azure AD B2C, Microsoft personal accounts). The user can also be responsible for one or more Microsoft identity platform accounts. | MSAL.NET defines the concept of account (through the IAccount interface). The IAccount interface represents information about a single account. The user can have several accounts in different tenants. MSAL.NET provides better information in guest scenarios, as home account information is provided. You can read more about the [differences between IUser and IAccount](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/msal-net-2-released#iuser-is-replaced-by-iaccount).|

-| **Cache persistence** | ADAL.NET allows you to extend the `TokenCache` class to implement the desired persistence functionality on platforms without a secure storage (.NET Framework and .NET core) by using the `BeforeAccess`, and `BeforeWrite` methods. For details, see [token cache serialization in ADAL.NET](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Token-cache-serialization). | MSAL.NET makes the token cache a sealed class, removing the ability to extend it. As such, your implementation of token cache persistence must be in the form of a helper class that interacts with the sealed token cache. This interaction is described in [token cache serialization in MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/token-cache-serialization) article. The serialization for a public client application (See [token cache for a public client application](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/token-cache-serialization#token-cache-for-a-public-client-application)), is different from that of for a confidential client application (See [token cache for a web app or web API](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/token-cache-serialization#token-cache-for-a-public-client-application)). |

-| **Common authority** | ADAL uses Azure AD v1.0. `https://login.microsoftonline.com/common` authority in Azure AD v1.0 (which ADAL uses) allows users to sign in using any Azure AD organization (work or school) account. Azure AD v1.0 doesn't allow sign in with Microsoft personal accounts. For more information, see [authority validation in ADAL.NET](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/AuthenticationContext:-the-connection-to-Azure-AD#authority-validation). | MSAL uses Azure AD v2.0. `https://login.microsoftonline.com/common` authority in Azure AD v2.0 (which MSAL uses) allows users to sign in with any Azure AD organization (work or school) account or with a Microsoft personal account. To restrict sign in using only organization accounts (work or school account) in MSAL, you'll need to use the `https://login.microsoftonline.com/organizations` endpoint. For details, see the `authority` parameter in [public client application](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/Client-Applications#publicclientapplication). |

-## Supported grants

-Below is a summary comparing MSAL.NET and ADAL.NET supported grants for both public and confidential client applications.

-### Public client applications

-The following image summarizes some of the differences between ADAL.NET and MSAL.NET for a public client application.

-[](media/msal-compare-msaldotnet-and-adaldotnet/differences.png#lightbox)

-Here are the grants supported in ADAL.NET and MSAL.NET for Desktop and Mobile applications.

-Grant | MSAL.NET | ADAL.NET |

- | - | - |

-Interactive | [Acquiring tokens interactively in MSAL.NET](scenario-desktop-acquire-token-interactive.md) | [Interactive Auth](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Acquiring-tokens-interactivelyPublic-client-application-flows) |

-Integrated Windows authentication | [Integrated Windows authentication](scenario-desktop-acquire-token-integrated-windows-authentication.md) | [Integrated authentication on Windows (Kerberos)](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/AcquireTokenSilentAsync-using-Integrated-authentication-on-Windows-(Kerberos)) |

-Username / Password | [Username-password authentication](scenario-desktop-acquire-token-username-password.md) | [Acquiring tokens with username and password](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Acquiring-tokens-with-username-and-password) |

-Device code flow | [Device code flow](scenario-desktop-acquire-token-device-code-flow.md) | [Device profile for devices without web browsers](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Device-profile-for-devices-without-web-browsers) |

-### Confidential client applications

-The following image summarizes some of the differences between ADAL.NET and MSAL.NET for a confidential client application.

-

-[](media/msal-net-migration/confidential-client-application.png#lightbox)

-Here are the grants supported in ADAL.NET, MSAL.NET, and Microsoft.Identity.Web for web applications, web APIs, and daemon applications.

-Type of App | Grant | MSAL.NET | ADAL.NET |

- | | | -- |

-Web app, web API, daemon | Client Credentials | [Client credential flows in MSAL.NET](scenario-daemon-acquire-token.md#acquiretokenforclient-api) | [Client credential flows in ADAL.NET](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Client-credential-flows) |

-Web API | On behalf of | [On behalf of in MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/on-behalf-of) | [Service to service calls on behalf of the user with ADAL.NET](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Service-to-service-calls-on-behalf-of-the-user) |

-Web app | Auth Code | [Acquiring tokens with authorization codes on web apps with A MSAL.NET](scenario-web-app-call-api-acquire-token.md) | [Acquiring tokens with authorization codes on web apps with ADAL.NET](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Acquiring-tokens-with-authorization-codes-on-web-apps) |

-## Migrating from ADAL 2.x with refresh tokens

-In ADAL.NET v2.X, the refresh tokens were exposed allowing you to develop solutions around the use of these tokens by caching them and using the `AcquireTokenByRefreshToken` methods provided by ADAL 2.x.

-Some of those solutions were used in scenarios such as:

-MSAL.NET doesn't expose refresh tokens for security reasons. MSAL handles refreshing tokens for you.

-Fortunately, MSAL.NET has an API that allows you to migrate your previous refresh tokens (acquired with ADAL) into the `IConfidentialClientApplication`:

-```csharp

-/// <summary>

-/// Acquires an access token from an existing refresh token and stores it and the refresh token into

-/// the application user token cache, where it will be available for further AcquireTokenSilent calls.

-/// This method can be used in migration to MSAL from ADAL v2 and in various integration

-/// scenarios where you have a RefreshToken available.

-/// (see https://aka.ms/msal-net-migration-adal2-msal2)

-/// </summary>

-/// <param name="scopes">Scope to request from the token endpoint.

-/// Setting this to null or empty will request an access token, refresh token and ID token with default scopes</param>

-/// <param name="refreshToken">The refresh token from ADAL 2.x</param>

-IByRefreshToken.AcquireTokenByRefreshToken(IEnumerable<string> scopes, string refreshToken);

-```

-With this method, you can provide the previously used refresh token along with any scopes (resources) you want. The refresh token will be exchanged for a new one and cached into your application.

-As this method is intended for scenarios that aren't typical, it isn't readily accessible with the `IConfidentialClientApplication` without first casting it to `IByRefreshToken`.

-The code snippet below shows some migration code in a confidential client application.

-```csharp

-TokenCache userCache = GetTokenCacheForSignedInUser();

-string rt = GetCachedRefreshTokenForSignedInUser();

-IConfidentialClientApplication app;

-app = ConfidentialClientApplicationBuilder.Create(clientId)

- .WithAuthority(Authority)

- .WithRedirectUri(RedirectUri)

- .WithClientSecret(ClientSecret)

- .Build();

-IByRefreshToken appRt = app as IByRefreshToken;

-AuthenticationResult result = await appRt.AcquireTokenByRefreshToken(null, rt)

- .ExecuteAsync()

- .ConfigureAwait(false);

-```

-`GetCachedRefreshTokenForSignedInUser` retrieves the refresh token that was stored in some storage by a previous version of the application that used to use ADAL 2.x. `GetTokenCacheForSignedInUser` deserializes a cache for the signed-in user (as confidential client applications should have one cache per user).

-An access token and an ID token are returned in the `AuthenticationResult` value while the new refresh token is stored in the cache. You can also use this method for various integration scenarios where you have a refresh token available.

-## v1.0 and v2.0 tokens

-There are two versions of tokens: v1.0 tokens and v2.0 tokens. The v1.0 endpoint (used by ADAL) emits v1.0 ID tokens while the v2.0 endpoint (used by MSAL) emits v2.0 ID tokens. However, both endpoints emit access tokens of the version of the token that the web API accepts. A property of the application manifest of the web API enables developers to choose which version of token is accepted. See `accessTokenAcceptedVersion` in the [application manifest](reference-app-manifest.md) reference documentation.

-For more information about v1.0 and v2.0 access tokens, see [Azure Active Directory access tokens](access-tokens.md).

-## Exceptions

-### Interaction required exceptions

-Using MSAL.NET, you catch `MsalUiRequiredException` as described in [AcquireTokenSilent](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/AcquireTokenSilentAsync-using-a-cached-token).

-```csharp

-catch(MsalUiRequiredException exception)

-{

- try {"try to authenticate interactively"}

-}

-```

-For details, see [Handle errors and exceptions in MSAL.NET](msal-error-handling-dotnet.md)

-ADAL.NET had less explicit exceptions. For example, when silent authentication failed in ADAL the procedure was to catch the exception and look for the `user_interaction_required` error code:

-```csharp

-catch(AdalException exception)

-{

- if (exception.ErrorCode == "user_interaction_required")

- {

- try

- {ΓÇ£try to authenticate interactivelyΓÇ¥}}

- }

-}

-```

-For details, see [the recommended pattern to acquire a token in public client applications](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/AcquireTokenSilentAsync-using-a-cached-token#recommended-pattern-to-acquire-a-token) with ADAL.NET.

-### Prompt behavior

-Prompt behavior in MSAL.NET is equivalent to prompt behavior in ADAL.NET:

-| ADAL.NET | MSAL.NET | Description |

-| -- | -- | -|

-| `PromptBehavior.Auto`| `NoPrompt`| Azure AD chooses the best behavior (signing in users silently if they are signed in with only one account, or displaying the account selector if they are signed in with several accounts). |

-| `PromptBehavior.Always`| `ForceLogin` | Resets the sign-in box and forces the user to reenter their credentials. |

-| `PromptBehavior.RefreshSession`| `Consent`| Forces the user to consent again to all permissions. |

-| `PromptBehavior.Never`| `Never`| Don't use; instead, use the [recommended pattern for public client apps](scenario-desktop-acquire-token.md?tabs=dotnet). |

-| `PromptBehavior.SelectAccount`| `SelectAccount`| Displays the account selector and forces the user to select an account. |

-### Handling claim challenge exceptions

-At times when acquiring a token, Azure AD throws an exception in case a resource requires more claims from the user (for instance two-factor authentication).

-In MSAL.NET, claim challenge exceptions are handled in the following way:

-For details see [Handling MsalUiRequiredException](msal-error-handling-dotnet.md#msaluirequiredexception).

-In ADAL.NET, claim challenge exceptions were handled in the following way:

-For details, including samples see [handling AdalClaimChallengeException](https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Exceptions-in-ADAL.NET#handling-adalclaimchallengeexception).

-## Scopes

-ADAL uses the concept of resources with `resourceId` string, MSAL.NET, however, uses scopes. The logic used by Azure AD is as follows:

-### Example 1

-If you want to acquire tokens for an application accepting v1.0 tokens (for instance the Microsoft Graph API, which is `https://graph.microsoft.com`), you'd need to create `scopes` by concatenating a desired resource identifier with a desired OAuth2 permission for that resource.

-For instance, to access the name of the user via a v1.0 web API whose App ID URI is `ResourceId`, you'd want to use:

-```csharp

-var scopes = new [] { ResourceId+"/user_impersonation" };

-```

-If you want to read and write with MSAL.NET Azure Active Directory using the Microsoft Graph API (`https://graph.microsoft.com/`), you'd create a list of scopes like in the code snippet below:

-```csharp

-string ResourceId = "https://graph.microsoft.com/";

-string[] scopes = { ResourceId + "Directory.Read", ResourceId + "Directory.Write" }

-```

-### Example 2

-If resourceId ends with a '/', you'll need to have a double '/' when writing the scope value. For example, if you want to write the scope corresponding to the Azure Resource Manager API (`https://management.core.windows.net/`), request the following scope (note the two slashes).

-```csharp

-var resource = "https://management.core.windows.net/"

-var scopes = new[] {"https://management.core.windows.net//user_impersonation"};

-var result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();

-// then call the API: https://management.azure.com/subscriptions?api-version=2016-09-01

-```

-This is because the Resource Manager API expects a slash in its audience claim (`aud`), and then there's a slash to separate the API name from the scope.

-If you want to acquire a token for all the static scopes of a v1.0 application, you'd create your scopes list as shown in the code snippet below:

-```csharp

-ResourceId = "someAppIDURI";

-var scopes = new [] { ResourceId+"/.default" };

-```

-For a client credential flow, the scope to pass would also be `/.default`. This scope tells to Azure AD: "all the app-level permissions that the admin has consented to in the application registration.

-## Next steps

-[Migrate your apps from ADAL to MSAL](msal-net-migration.md)

-[Migrate your ADAL.NET confidential client apps to use MSAL.NET](msal-net-migration-confidential-client.md)

-description: Learn about initializing public client and confidential client applications using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn about initializing client applications so I can decide if this platform meets my application development needs and requirements.

-# Initialize client applications using MSAL.NET

-This article describes initializing public client and confidential client applications using the Microsoft Authentication Library for .NET (MSAL.NET). To learn more about the client application types, see [Public client and confidential client applications](msal-client-applications.md).

-With MSAL.NET 3.x, the recommended way to instantiate an application is by using the application builders: `PublicClientApplicationBuilder` and `ConfidentialClientApplicationBuilder`. They offer a powerful mechanism to configure the application from the code, a configuration file, or even by mixing both approaches.

-## Prerequisites

-Before initializing an application, you first need to register it so that your app can be integrated with the Microsoft identity platform. Refer to the [Quickstart: Register an application with the Microsoft identity platform](quickstart-register-app.md) for more information. After registration, you may need the following information (which can be found in the Azure portal):

-## Initializing applications

-There are many different ways to instantiate client applications.

-### Initializing a public client application from code

-The following code instantiates a public client application, signing-in users in the Microsoft Azure public cloud, with their work, school or personal Microsoft accounts.

-```csharp

-IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)

- .Build();

-```

-### Initializing a confidential client application from code

-In the same way, the following code instantiates a confidential application (a Web app located at `https://myapp.azurewebsites.net`) handling tokens from users in the Microsoft Azure public cloud, with their work and school accounts, or their personal Microsoft accounts. The application is identified with the identity provider by sharing a client secret:

-```csharp

-string redirectUri = "https://myapp.azurewebsites.net";

-IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)

- .WithClientSecret(clientSecret)

- .WithRedirectUri(redirectUri )

- .Build();

-```

-In production however, certificates are recommended as they're more secure than client secrets. They can be created and uploaded to the Azure portal. The code would then be the following:

-```csharp

-IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)

- .WithCertificate(certificate)

- .WithRedirectUri(redirectUri )

- .Build();

-```

-### Initializing a public client application from configuration options

-The following code instantiates a public client application from a configuration object, which could be filled-in programmatically or read from a configuration file:

-```csharp

-PublicClientApplicationOptions options = GetOptions(); // your own method

-IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)

- .Build();

-```

-### Initializing a confidential client application from configuration options

-The same kind of pattern applies to confidential client applications. You can also add other parameters using `.WithXXX` modifiers. This example uses `.WithCertificate`.

-```csharp

-ConfidentialClientApplicationOptions options = GetOptions(); // your own method

-IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)

- .WithCertificate(certificate)

- .Build();

-```

-## Builder modifiers

-In the code snippets using application builders, many `.With` methods can be applied as modifiers (for example, `.WithCertificate` and `.WithRedirectUri`).

-### Modifiers common to public and confidential client applications

-The modifiers you can set on a public client or confidential client application builder can be found in the `AbstractApplicationBuilder<T>` class. The different methods can be found in the [Azure SDK for .NET documentation](/dotnet/api/microsoft.identity.client.abstractapplicationbuilder-1).

-### Modifiers specific to Xamarin.iOS applications

-The modifiers you can set on a public client application builder on Xamarin.iOS are:

-|Modifier | Description|

-| | |

-|`.WithIosKeychainSecurityGroup()` | **Xamarin.iOS only**: Sets the iOS key chain security group (for the cache persistence).|

-### Modifiers specific to confidential client applications

-The modifiers you can set that are specific to a confidential client application builder can be found in the `ConfidentialClientApplicationBuilder` class. The different methods can be found in the [Azure SDK for .NET documentation](/dotnet/api/microsoft.identity.client.confidentialclientapplicationbuilder).

-Modifiers such as `.WithCertificate(X509Certificate2 certificate)` and `.WithClientSecret(string clientSecret)` are mutually exclusive. If you provide both, MSAL will throw a meaningful exception.

-### Example of usage of modifiers

-Let's assume that your application is a line-of-business application, which is only for your organization. Then you can write:

-```csharp

-IPublicClientApplication app;

-app = PublicClientApplicationBuilder.Create(clientId)

- .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)

- .Build();

-```

-Programming for national clouds has simplified, so if you want your application to be a multi-tenant application in a national cloud, you could write, for instance:

-```csharp

-IPublicClientApplication app;

-app = PublicClientApplicationBuilder.Create(clientId)

- .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)

- .Build();

-```

-There's also an override for ADFS (MSAL.NET will only support ADFS 2019 or later):

-```csharp

-IPublicClientApplication app;

-app = PublicClientApplicationBuilder.Create(clientId)

- .WithAdfsAuthority("https://consoso.com/adfs")

- .Build();

-```

-Finally, if you're an Azure AD B2C developer, you can specify your tenant like this:

-```csharp

-IPublicClientApplication app;

-app = PublicClientApplicationBuilder.Create(clientId)

- .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")

- .Build();

-```

-## See also

-[API reference documentation](/dotnet/api/microsoft.identity.client)

-[Package on NuGet](https://www.nuget.org/packages/Microsoft.Identity.Client/)

-[Library source code](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet)

-[Code samples](sample-v2-code.md)

-## Next steps

-After you've initialized the client application, your next task is to add support for user sign-in, authorized API access, or both.

-Our application scenario documentation provides guidance for signing in a user and acquiring an access token to access an API on behalf of that user:

-description: Learn how to instantiate a confidential client application with configuration options using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn how to use application config options so I can instantiate a confidential client app.

-# Instantiate a confidential client application with configuration options using MSAL.NET

-This article describes how to instantiate a [confidential client application](msal-client-applications.md) using the Microsoft Authentication Library for .NET (MSAL.NET). The application is instantiated with configuration options defined in a settings file.

-Before initializing an application, you first need to [register](quickstart-register-app.md) it so that your app can be integrated with the Microsoft identity platform. After registration, you may need the following information (which can be found in the Azure portal):

-## Configure the application from the config file

-The name of the properties of the options in MSAL.NET match the name of the properties of the `AzureADOptions` in ASP.NET Core, so you don't need to write any glue code.

-An ASP.NET Core application configuration is described in an *appsettings.json* file:

-```json

-{

- "AzureAd": {

- "Instance": "https://login.microsoftonline.com/",

- "Domain": "[Enter the domain of your tenant, e.g. contoso.onmicrosoft.com]",

- "TenantId": "[Enter 'common', or 'organizations' or the Tenant Id (Obtained from the Azure portal. Select 'Endpoints' from the 'App registrations' blade and use the GUID in any of the URLs), e.g. da41245a5-11b3-996c-00a8-4d99re19f292]",

- "ClientId": "[Enter the Client Id (Application ID obtained from the Azure portal), e.g. ba74781c2-53c2-442a-97c2-3d60re42f403]",

- "CallbackPath": "/signin-oidc",

- "SignedOutCallbackPath ": "/signout-callback-oidc",

- "ClientSecret": "[Copy the client secret added to the app from the Azure portal]"

- },

- "Logging": {

- "LogLevel": {

- "Default": "Warning"

- }

- },

- "AllowedHosts": "*"

-}

-```

-Starting in MSAL.NET v3.x, you can configure your confidential client application from the config file.

-In the class where you want to configure and instantiate your application, declare a `ConfidentialClientApplicationOptions` object. Bind the configuration read from the source (including the appconfig.json file) to the instance of the application options, using the `IConfigurationRoot.Bind()` method from the [Microsoft.Extensions.Configuration.Binder NuGet package](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.Binder):

-```csharp

-using Microsoft.Identity.Client;

-private ConfidentialClientApplicationOptions _applicationOptions;

-_applicationOptions = new ConfidentialClientApplicationOptions();

-configuration.Bind("AzureAD", _applicationOptions);

-```

-This enables the content of the "AzureAD" section of the *appsettings.json* file to be bound to the corresponding properties of the `ConfidentialClientApplicationOptions` object. Next, build a `ConfidentialClientApplication` object:

-```csharp

-IConfidentialClientApplication app;

-app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(_applicationOptions)

- .Build();

-```

-## Add runtime configuration

-In a confidential client application, you usually have a cache per user. Therefore you will need to get the cache associated with the user and inform the application builder that you want to use it. In the same way, you might have a dynamically computed redirect URI. In this case, the code is as follows:

-```csharp

-IConfidentialClientApplication app;

-var request = httpContext.Request;

-var currentUri = UriHelper.BuildAbsolute(request.Scheme, request.Host, request.PathBase, _azureAdOptions.CallbackPath ?? string.Empty);

-app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(_applicationOptions)

- .WithRedirectUri(currentUri)

- .Build();

-TokenCache userTokenCache = _tokenCacheProvider.SerializeCache(app.UserTokenCache,httpContext, claimsPrincipal);

-```

-description: Learn how to instantiate a public client application with configuration options using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn how to use application config options so I can instantiate a public client app.

-# Instantiate a public client application with configuration options using MSAL.NET

-This article describes how to instantiate a [public client application](msal-client-applications.md) using the Microsoft Authentication Library for .NET (MSAL.NET). The application is instantiated with configuration options defined in a settings file.

-Before initializing an application, you first need to [register](quickstart-register-app.md) it so that your app can be integrated with the Microsoft identity platform. After registration, you may need the following information (which can be found in the Azure portal):

-## Default Reply URI

-In MSAL.NET 4.1+ the default redirect URI (Reply URI) can now be set with the `public PublicClientApplicationBuilder WithDefaultRedirectUri()` method. This method will set the redirect URI property of public client application to the recommended default.

-This method's behavior is dependent upon the platform that you are using at the time. Here is a table that describes what redirect URI is set on certain platforms:

-Platform | Redirect URI

- | --

-Desktop app (.NET FW) | `https://login.microsoftonline.com/common/oauth2/nativeclient`

-UWP | value of `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`

-.NET Core | `http://localhost`

-For the UWP platform, is enhanced the experience by enabling SSO with the browser by setting the value to the result of `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`.

-For .NET Core, MSAL.Net is setting the value to the local host to enable the user to use the system browser for interactive authentication.

-> [!NOTE]

-> For embedded browsers in desktop scenarios the redirect URI used is intercepted by MSAL to detect that a response is returned from the identity provider that an auth code has been returned. This URI can therefore be used in any cloud without seeing an actual redirect to that URI. This means you can and should use `https://login.microsoftonline.com/common/oauth2/nativeclient` in any cloud. If you prefer you can also use any other URI as long as you configure the redirect URI correctly with MSAL and in the app registration. Specifying the default URI in the application registration means there is the least amount of setup in MSAL.

-A .NET Core console application could have the following *appsettings.json* configuration file:

-```json

-{

- "Authentication": {

- "AzureCloudInstance": "AzurePublic",

- "AadAuthorityAudience": "AzureAdMultipleOrgs",

- "ClientId": "ebe2ab4d-12b3-4446-8480-5c3828d04c50"

- },

- "WebAPI": {

- "MicrosoftGraphBaseEndpoint": "https://graph.microsoft.com"

- }

-}

-```

-The following code reads this file using the .NET configuration framework:

-```csharp

-public class SampleConfiguration

-{

- /// <summary>

- /// Authentication options

- /// </summary>

- public PublicClientApplicationOptions PublicClientApplicationOptions { get; set; }

- /// <summary>

- /// Base URL for Microsoft Graph (it varies depending on whether the application is ran

- /// in Microsoft Azure public clouds or national / sovereign clouds

- /// </summary>

- public string MicrosoftGraphBaseEndpoint { get; set; }

- /// <summary>

- /// Reads the configuration from a json file

- /// </summary>

- /// <param name="path">Path to the configuration json file</param>

- /// <returns>SampleConfiguration as read from the json file</returns>

- public static SampleConfiguration ReadFromJsonFile(string path)

- {

- // .NET configuration

- IConfigurationRoot Configuration;

- var builder = new ConfigurationBuilder()

- .SetBasePath(Directory.GetCurrentDirectory())

- .AddJsonFile(path);

- Configuration = builder.Build();

- // Read the auth and graph endpoint config

- SampleConfiguration config = new SampleConfiguration()

- {

- PublicClientApplicationOptions = new PublicClientApplicationOptions()

- };

- Configuration.Bind("Authentication", config.PublicClientApplicationOptions);

- config.MicrosoftGraphBaseEndpoint = Configuration.GetValue<string>("WebAPI:MicrosoftGraphBaseEndpoint");

- return config;

- }

-}

-```

-The following code creates your application, using the configuration from the settings file:

-```csharp

-SampleConfiguration config = SampleConfiguration.ReadFromJsonFile("appsettings.json");

-var app = PublicClientApplicationBuilder.CreateWithApplicationOptions(config.PublicClientApplicationOptions)

- .Build();

-```

-description: Learn how to migrate a confidential client application from Azure Active Directory Authentication Library for .NET to Microsoft Authentication Library for .NET.

-#Customer intent: As an application developer, I want to migrate my confidential client app from ADAL.NET to MSAL.NET.

-# Migrate confidential client applications from ADAL.NET to MSAL.NET

-In this how-to guide you'll migrate a confidential client application from Azure Active Directory Authentication Library for .NET (ADAL.NET) to Microsoft Authentication Library for .NET (MSAL.NET). Confidential client applications include web apps, web APIs, and daemon applications that call another service on their own behalf. For more information about confidential apps, see [Authentication flows and application scenarios](authentication-flows-app-scenarios.md). If your app is based on ASP.NET Core, see [Microsoft.Identity.Web](microsoft-identity-web.md).

-For app registrations:

-## Migration steps

-1. Find the code that uses ADAL.NET in your app.

- The code that uses ADAL in a confidential client app instantiates `AuthenticationContext` and calls either `AcquireTokenByAuthorizationCode` or one override of `AcquireTokenAsync` with the following parameters:

- - A `resourceId` string. This variable is the app ID URI of the web API that you want to call.

- - An instance of `IClientAssertionCertificate` or `ClientAssertion`. This instance provides the client credentials for your app to prove the identity of your app.

-1. After you've identified that you have apps that are using ADAL.NET, install the MSAL.NET NuGet package [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) and update your project library references. For more information, see [Install a NuGet package](https://www.bing.com/search?q=install+nuget+package). To use token cache serializers, install [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache).

-1. Update the code according to the confidential client scenario. Some steps are common and apply across all the confidential client scenarios. Other steps are unique to each scenario.

- Confidential client scenarios:

- - [Daemon scenarios](?tabs=daemon#migrate-daemon-apps) supported by web apps, web APIs, and daemon console applications.

- - [Web API calling downstream web APIs](?tabs=obo#migrate-a-web-api-that-calls-downstream-web-apis) supported by web APIs calling downstream web APIs on behalf of the user.

- - [Web app calling web APIs](?tabs=authcode#migrate-a-web-api-that-calls-downstream-web-apis) supported by web apps that sign in users and call a downstream web API.

-You might have provided a wrapper around ADAL.NET to handle certificates and caching. This guide uses the same approach to illustrate the process of migrating from ADAL.NET to MSAL.NET. However, this code is only for demonstration purposes. Don't copy/paste these wrappers or integrate them in your code as they are.

-## [Daemon](#tab/daemon)

-### Migrate daemon apps

-Daemon scenarios use the OAuth2.0 [client credential flow](v2-oauth2-client-creds-grant-flow.md). They're also called service-to-service calls. Your app acquires a token on its own behalf, not on behalf of a user.

-#### Find out if your code uses daemon scenarios

-The ADAL code for your app uses daemon scenarios if it contains a call to `AuthenticationContext.AcquireTokenAsync` with the following parameters:

-`AuthenticationContext.AcquireTokenAsync` doesn't have a parameter of type `UserAssertion`. If it does, then your app is a web API, and it uses the [web API calling downstream web APIs](?tabs=obo#migrate-a-web-api-that-calls-downstream-web-apis) scenario.

-#### Update the code of daemon scenarios

-In this case, replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IConfidentialClientApplication.AcquireTokenClient`.

-Here's a comparison of ADAL.NET and MSAL.NET code for daemon scenarios:

- ADAL

- MSAL

-

-```csharp

-using Microsoft.IdentityModel.Clients.ActiveDirectory;

-using System.Security.Cryptography.X509Certificates;

-using System.Threading.Tasks;

-public partial class AuthWrapper

-{

- const string ClientId = "Guid (AppID)";

- const string authority

- = "https://login.microsoftonline.com/{tenant}";

- // App ID URI of web API to call

- const string resourceId = "https://target-api.domain.com";

- X509Certificate2 certificate = LoadCertificate();

- public async Task<AuthenticationResult> GetAuthenticationResult()

- {

- var authContext = new AuthenticationContext(authority);

- var clientAssertionCert = new ClientAssertionCertificate(

- ClientId,

- certificate);

- var authResult = await authContext.AcquireTokenAsync(

- resourceId,

- clientAssertionCert,

- );

- return authResult;

- }

-}

-```

-```csharp

-using Microsoft.Identity.Client;

-using System.Security.Cryptography.X509Certificates;

-using System.Threading.Tasks;

-public partial class AuthWrapper

-{

- const string ClientId = "Guid (Application ID)";

- const string authority

- = "https://login.microsoftonline.com/{tenant}";

- // App ID URI of web API to call

- const string resourceId = "https://target-api.domain.com";

- X509Certificate2 certificate = LoadCertificate();

- IConfidentialClientApplication app;

- public async Task<AuthenticationResult> GetAuthenticationResult()

- {

- var app = ConfidentialClientApplicationBuilder.Create(ClientId)

- .WithCertificate(certificate)

- .WithAuthority(authority)

- .Build();

- // Setup token caching https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=aspnet

- // For example, for an in-memory cache with 1GB limit, use

- app.AddInMemoryTokenCache(services =>

- {

- // Configure the memory cache options

- services.Configure<MemoryCacheOptions>(options =>

- {

- options.SizeLimit = 1024 * 1024 * 1024; // in bytes (1 GB of memory)

- });

- }

- var authResult = await app.AcquireTokenForClient(

- new [] { $"{resourceId}/.default" })

- // .WithTenantId(specificTenant)

- // See https://aka.ms/msal.net/withTenantId

- .ExecuteAsync()

- .ConfigureAwait(false);

- return authResult;

- }

-}

-```

- :::column-end:::

-#### Benefit from token caching

-If you don't setup token caching, the token issuer will throttle you, resulting in errors. It also takes a lot less to get a token from the cache (10-20ms) than it is from ESTS (500-30000ms).

-If you want to implement a distributed token cache, see [Token cache for a web app or web API (confidential client application)](msal-net-token-cache-serialization.md?tabs=aspnet) and the sample [active-directory-dotnet-v1-to-v2/ConfidentialClientTokenCache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache).

-[Learn more about the daemon scenario](scenario-daemon-overview.md) and how it's implemented with MSAL.NET or Microsoft.Identity.Web in new applications.

-## [Web API calling downstream web APIs](#tab/obo)

-### Migrate a web API that calls downstream web APIs

-Web APIs that call downstream web APIs use the OAuth2.0 [on-behalf-of (OBO)](v2-oauth2-on-behalf-of-flow.md) flow. The web API uses the access token retrieved from the HTTP **Authorize** header and it validates this token. This token is then exchanged against a token to call the downstream web API. This token is used as a `UserAssertion` instance in both ADAL.NET and MSAL.NET.

-#### Find out if your code uses OBO

-The ADAL code for your app uses OBO if it contains a call to `AuthenticationContext.AcquireTokenAsync` with the following parameters:

-#### Update the code by using OBO

-In this case, we replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IConfidentialClientApplication.AcquireTokenOnBehalfOf`.

-Here's a comparison of sample OBO code for ADAL.NET and MSAL.NET:

- :::column span="":::

- ADAL

- :::column-end:::

- :::column span="":::

- MSAL

- :::column-end:::

-```csharp

-using Microsoft.IdentityModel.Clients.ActiveDirectory;

-using System.Security.Cryptography.X509Certificates;

-using System.Threading.Tasks;

-public partial class AuthWrapper

-{

- const string ClientId = "Guid (AppID)";

- const string authority

- = "https://login.microsoftonline.com/common";

- X509Certificate2 certificate = LoadCertificate();

- public async Task<AuthenticationResult> GetAuthenticationResult(

- string resourceId,

- string tokenUsedToCallTheWebApi)

- {

- var authContext = new AuthenticationContext(authority);

- var clientAssertionCert = new ClientAssertionCertificate(

- ClientId,

- certificate);

- var userAssertion = new UserAssertion(tokenUsedToCallTheWebApi);

- var authResult = await authContext.AcquireTokenAsync(

- resourceId,

- clientAssertionCert,

- userAssertion,

- );

- return authResult;

- }

-}

-```

-```csharp

-using Microsoft.Identity.Client;

-using System.Security.Cryptography.X509Certificates;

-using System.Threading.Tasks;

-public partial class AuthWrapper

-{

- const string ClientId = "Guid (Application ID)";

- const string authority

- = "https://login.microsoftonline.com/common";

- X509Certificate2 certificate = LoadCertificate();

- IConfidentialClientApplication app;

- public async Task<AuthenticationResult> GetAuthenticationResult(

- string resourceId,

- string tokenUsedToCallTheWebApi)

- {

-

- var app = ConfidentialClientApplicationBuilder.Create(ClientId)

- .WithCertificate(certificate)

- .WithAuthority(authority)

- .Build();

- // Setup token caching https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=aspnet

- // For example, for an in-memory cache with 1GB limit. For OBO, it is recommended to use a distributed cache like Redis.

- app.AddInMemoryTokenCache(services =>

- {

- // Configure the memory cache options

- services.Configure<MemoryCacheOptions>(options =>

- {

- options.SizeLimit = 1024 * 1024 * 1024; // in bytes (1 GB of memory)

- });

- }

- var userAssertion = new UserAssertion(tokenUsedToCallTheWebApi);

- var authResult = await app.AcquireTokenOnBehalfOf(

- new string[] { $"{resourceId}/.default" },

- userAssertion)

- // .WithTenantId(specificTenant)

- // See https://aka.ms/msal.net/withTenantId

- .ExecuteAsync()

- .ConfigureAwait(false);

-

- return authResult;

- }

-}

-```

-#### Benefit from token caching

-For token caching in OBOs, use a distributed token cache. For details, see [Token cache for a web app or web API (confidential client app)](msal-net-token-cache-serialization.md?tabs=aspnet) and read through [sample code](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache).

-```CSharp

-app.UseInMemoryTokenCaches(); // or a distributed token cache.

-```

-[Learn more about web APIs calling downstream web APIs](scenario-web-api-call-api-overview.md) and how they're implemented with MSAL.NET or Microsoft.Identity.Web in new apps.

-## [Web app calling web APIs](#tab/authcode)

-### Migrate a web app that calls web APIs

-If your app uses ASP.NET Core, we strongly recommend that you update to Microsoft.Identity.Web because it processes everything for you. For a quick presentation, see the [Microsoft.Identity.Web announcement of general availability](https://github.com/AzureAD/microsoft-identity-web/wiki/1.0.0). For details about how to use it in a web app, see [Why use Microsoft.Identity.Web in web apps?](https://aka.ms/ms-id-web/webapp).

-Web apps that sign in users and call web APIs on behalf of users employ the OAuth2.0 [authorization code flow](v2-oauth2-auth-code-flow.md). Typically:

-1. The app signs in a user by executing a first leg of the authorization code flow by going to the Microsoft identity platform authorize endpoint. The user signs in and performs multi-factor authentications if needed. As an outcome of this operation, the app receives the authorization code. The authentication library isn't used at this stage.

-1. The app executes the second leg of the authorization code flow. It uses the authorization code to get an access token, an ID token, and a refresh token. Your application needs to provide the `redirectUri` value, which is the URI where the Microsoft identity platform endpoint will provide the security tokens. After the app receives that URI, it typically calls `AcquireTokenByAuthorizationCode` for ADAL or MSAL to redeem the code and to get a token that will be stored in the token cache.

-1. The app uses ADAL or MSAL to call `AcquireTokenSilent` to get tokens for calling the necessary web APIs from the web app controllers.

-#### Find out if your code uses the auth code flow

-The ADAL code for your app uses auth code flow if it contains a call to `AuthenticationContext.AcquireTokenByAuthorizationCodeAsync`.

-#### Update the code by using the authorization code flow

-In this case, replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IConfidentialClientApplication.AcquireTokenByAuthorizationCode`.

-Here's a comparison of sample authorization code flows for ADAL.NET and MSAL.NET:

- :::column span="":::

- ADAL

- :::column-end:::

- :::column span="":::

- MSAL

- :::column-end:::

- :::column span="":::

-```csharp

-using Microsoft.IdentityModel.Clients.ActiveDirectory;

-using System.Security.Cryptography.X509Certificates;

-using System.Threading.Tasks;

-public partial class AuthWrapper

-{

- const string ClientId = "Guid (AppID)";

- const string authority

- = "https://login.microsoftonline.com/common";

- private Uri redirectUri = new Uri("host/login_oidc");

- X509Certificate2 certificate = LoadCertificate();

- public async Task<AuthenticationResult> GetAuthenticationResult(

- string resourceId,

- string authorizationCode)

- {

- var ac = new AuthenticationContext(authority);

- var clientAssertionCert = new ClientAssertionCertificate(

- ClientId,

- certificate);

- var authResult = await ac.AcquireTokenByAuthorizationCodeAsync(

- authorizationCode,

- redirectUri,

- clientAssertionCert,

- resourceId,

- );

- return authResult;

- }

-}

-```

- :::column-end:::

- :::column span="":::

-```csharp

-using Microsoft.Identity.Client;

-using Microsoft.Identity.Web;

-using System;

-using System.Security.Claims;

-using System.Security.Cryptography.X509Certificates;

-using System.Threading.Tasks;

-public partial class AuthWrapper

-{

- const string ClientId = "Guid (Application ID)";

- const string authority

- = "https://login.microsoftonline.com/{tenant}";

- private Uri redirectUri = new Uri("host/login_oidc");

- X509Certificate2 certificate = LoadCertificate();

- public IConfidentialClientApplication CreateApplication()

- {

- IConfidentialClientApplication app;

- app = ConfidentialClientApplicationBuilder.Create(ClientId)

- .WithCertificate(certificate)

- .WithAuthority(authority)

- .WithRedirectUri(redirectUri.ToString())

- .WithLegacyCacheCompatibility(false)

- .Build();

- // Add a token cache. For details about other serialization

- // see https://aka.ms/msal-net-cca-token-cache-serialization

- app.AddInMemoryTokenCache();

- return app;

- }

- // Called from 'code received event'.

- public async Task<AuthenticationResult> GetAuthenticationResult(

- string resourceId,

- string authorizationCode)

- {

- IConfidentialClientApplication app = CreateApplication();

- var authResult = await app.AcquireTokenByAuthorizationCode(

- new[] { $"{resourceId}/.default" },

- authorizationCode)

- .ExecuteAsync()

- .ConfigureAwait(false);

- return authResult;

- }

-}

-```

- :::column-end:::

-Calling `AcquireTokenByAuthorizationCode` adds a token to the token cache when the authorization code is received. To acquire extra tokens for other resources or tenants, use `AcquireTokenSilent` in your controllers.

-```csharp

-public partial class AuthWrapper

-{

- // Called from controllers

- public async Task<AuthenticationResult> GetAuthenticationResult(

- string resourceId2,

- string authority)

- {

- IConfidentialClientApplication app = CreateApplication();

- AuthenticationResult authResult;

- var scopes = new[] { $"{resourceId2}/.default" };

- var account = await app.GetAccountAsync(ClaimsPrincipal.Current.GetMsalAccountId());

- try

- {

- // try to get an already cached token

- authResult = await app.AcquireTokenSilent(

- scopes,

- account)

- // .WithTenantId(specificTenantId)

- // See https://aka.ms/msal.net/withTenantId

- .ExecuteAsync().ConfigureAwait(false);

- }

- catch (MsalUiRequiredException)

- {

- // The controller will need to challenge the user

- // including asking for claims={ex.Claims}

- throw;

- }

- return authResult;

- }

-}

-```

-#### Benefit from token caching

-Because your web app uses `AcquireTokenByAuthorizationCode`, it needs to use a distributed token cache for token caching. For details, see [Token cache for a web app or web API](msal-net-token-cache-serialization.md?tabs=aspnet) and read through [sample code](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache).

-```CSharp

-app.UseInMemoryTokenCaches(); // or a distributed token cache.

-```

-#### Handling MsalUiRequiredException

-When your controller attempts to acquire a token silently for different

-scopes/resources, MSAL.NET might throw an `MsalUiRequiredException` as expected if the user needs to re-sign-in, or if the

-access to the resource requires more claims (because of a Conditional Access

-policy). For details on mitigation see how to [Handle errors and exceptions in MSAL.NET](msal-error-handling-dotnet.md).

-[Learn more about web apps calling web APIs](scenario-web-app-call-api-overview.md) and how they're implemented with MSAL.NET or Microsoft.Identity.Web in new applications.

-## MSAL benefits

-Key benefits of MSAL.NET for your app include:

- - Azure AD Cached Credential Service (CCS) benefits. CCS operates as an Azure AD backup.

- - Proactive renewal of tokens if the API that you call enables long-lived tokens through [continuous access evaluation](app-resilience-continuous-access-evaluation.md).

-

- ```csharp

- app = ConfidentialClientApplicationBuilder.Create(ClientId)

- .WithCertificate(certificate)

- .WithAuthority(authority)

- .WithLegacyCacheCompatibility(false)

- .Build();

- ```

-## Troubleshooting

-### MsalServiceException

-The following troubleshooting information makes two assumptions:

-If you get an exception with either of the following messages:

-> `AADSTS700027: Client assertion contains an invalid signature. [Reason - The key was not found.]`

-> `AADSTS90002: Tenant 'cf61953b-e41a-46b3-b500-663d279ea744' not found. This may happen if there are no active`

-> `subscriptions for the tenant. Check to make sure you have the correct tenant ID. Check with your subscription`

-> `administrator.`

-Troubleshoot the exception using these steps:

-1. Confirm that you're using the latest version of [MSAL.NET](https://www.nuget.org/packages/Microsoft.Identity.Client/).

-1. Confirm that the authority host that you set when building the confidential client app and the authority host that you used with ADAL are similar. In particular, is it the same [cloud](msal-national-cloud.md) (Azure Government, Microsoft Azure operated by 21Vianet, or Azure Germany)?

-### MsalClientException

-In multi-tenant apps, specify a common authority when building the app to target a specific tenant such as, the tenant of the user when calling a web API. Since MSAL.NET 4.37.0, when you specify `.WithAzureRegion` at the app creation, you can no longer specify the Authority using `.WithAuthority` during the token requests. If you do, you'll get the following error when updating from previous versions of MSAL.NET:

- `MsalClientException - "You configured WithAuthority at the request level, and also WithAzureRegion. This is not supported when the environment changes from application to request. Use WithTenantId at the request level instead."`

-To remediate this issue, replace `.WithAuthority` on the AcquireTokenXXX expression by `.WithTenantId`. Specify the tenant using either a GUID or a domain name.

-## Next steps

-Learn more about:

-description: Learn how to migrate a public client application from Azure Active Directory Authentication Library for .NET to Microsoft Authentication Library for .NET.

-#Customer intent: As an application developer, I want to migrate my public client app from ADAL.NET to MSAL.NET.

-# Migrate public client applications from ADAL.NET to MSAL.NET

-This article describes how to migrate a public client application from Azure Active Directory Authentication Library for .NET (ADAL.NET) to Microsoft Authentication Library for .NET (MSAL.NET). Public client applications are desktop apps, including Win32, WPF, and UWP apps, and mobile apps, that call another service on the user's behalf. For more information about public client applications, see [Authentication flows and application scenarios](authentication-flows-app-scenarios.md).

-## Migration steps

-1. Find the code by using ADAL.NET in your app.

- The code that uses ADAL in a public client application instantiates `AuthenticationContext` and calls an override of `AcquireTokenAsync` with the following parameters:

- - A `resourceId` string. This variable is the app ID URI of the web API that you want to call.

- - A `clientId` which is the identifier for your application, also known as App ID.

-2. After you've identified that you have apps that are using ADAL.NET, install the MSAL.NET NuGet package [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client) and update your project library references. For more information, see [Install a NuGet package](https://www.bing.com/search?q=install+nuget+package).

-3. Update the code according to the public client application scenario. Some steps are common and apply across all the public client scenarios. Other steps are unique to each scenario.

- The public client scenarios are:

- - [Web Authentication Manager](scenario-desktop-acquire-token-wam.md) the preferred broker-based authentication on Windows.

- - [Interactive authentication](scenario-desktop-acquire-token-interactive.md) where the user is shown a web-based interface to complete the sign-in process.

- - [Integrated Windows authentication](scenario-desktop-acquire-token-integrated-windows-authentication.md) where a user signs using the same identity they used to sign into a Windows domain (for domain-joined or Azure AD-joined machines).

- - [Username/password](scenario-desktop-acquire-token-username-password.md) where the sign-in occurs by providing a username/password credential.

- - [Device code flow](scenario-desktop-acquire-token-device-code-flow.md) where a device of limited UX shows you a device code to complete the authentication flow on an alternate device.

-## [Interactive](#tab/interactive)

-Interactive scenarios are where your public client application shows a login user interface hosted in a browser, and the user is required to interactively sign-in.

-#### Find out if your code uses interactive scenarios

-The ADAL code for your app in a public client application that uses interactive authentication instantiates `AuthenticationContext` and includes a call to `AcquireTokenAsync`, with the following parameters.

- #### Update the code for interactive scenarios

- [!INCLUDE [Common steps](includes/msal-net-adoption-steps-public-clients.md)]

-In this case, we replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IPublicClientApplication.AcquireTokenInteractive`.

-Here's a comparison of ADAL.NET and MSAL.NET code for interactive scenarios:

- ADAL

- MSAL

-

-```csharp

-var ac = new AuthenticationContext("https://login.microsoftonline.com/<tenantId>");

-AuthenticationResult result;

-result = await ac.AcquireTokenAsync("<clientId>",

- "https://resourceUrl",

- new Uri("https://ClientReplyUrl"),

- new PlatformParameters(PromptBehavior.Auto));

-```

-```csharp

-// 1. Configuration - read below about redirect URI

-var pca = PublicClientApplicationBuilder.Create("client_id")

- .WithBroker()

- .Build();

-// Add a token cache, see https://learn.microsoft.com/azure/active-directory/develop/msal-net-token-cache-serialization?tabs=desktop

-// 2. GetAccounts

-var accounts = await pca.GetAccountsAsync();

-var accountToLogin = // choose an account, or null, or use PublicClientApplication.OperatingSystemAccount for the default OS account

-try

-{

- // 3. AcquireTokenSilent

- var authResult = await pca.AcquireTokenSilent(new[] { "User.Read" }, accountToLogin)

- .ExecuteAsync();

-}

-catch (MsalUiRequiredException) // no change in the pattern

-{

- // 4. Specific: Switch to the UI thread for next call . Not required for console apps.

- await SwitchToUiThreadAsync(); // not actual code, this is different on each platform / tech

- // 5. AcquireTokenInteractive

- var authResult = await pca.AcquireTokenInteractive(new[] { "User.Read" })

- .WithAccount(accountToLogin) // this already exists in MSAL, but it is more important for WAM

- .WithParentActivityOrWindow(myWindowHandle) // to be able to parent WAM's windows to your app (optional, but highly recommended; not needed on UWP)

- .ExecuteAsync();

-}

-```

- :::column-end:::

-The MSAL code shown above uses WAM (Web authentication manager) which is the recommended approach. If you wish to use interactive authentication without WAM, see [Interactive Authentication](scenario-desktop-acquire-token-interactive.md).

-## [Integrated Windows authentication](#tab/iwa)

-Integrated Windows authentication is where your public client application signs in using the same identity they used to sign into a Windows domain (for domain-joined or Azure AD-joined machines).

-#### Find out if your code uses integrated Windows authentication

-The ADAL code for your app uses integrated Windows authentication scenarios if it contains a call to `AcquireTokenAsync` available as an extension method of the `AuthenticationContextIntegratedAuthExtensions` class, with the following parameters:

-#### Update the code for integrated Windows authentication scenarios

- [!INCLUDE [Common steps](includes/msal-net-adoption-steps-public-clients.md)]

-In this case, we replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IPublicClientApplication.AcquireTokenByIntegratedWindowsAuth`.

-Here's a comparison of ADAL.NET and MSAL.NET code for integrated Windows authentication scenarios:

- ADAL

- MSAL

-

-```csharp

-var ac = new AuthenticationContext("https://login.microsoftonline.com/<tenantId>");

-AuthenticationResult result;

-result = await context.AcquireTokenAsync(resource, clientId,

- new UserCredential("john@contoso.com"));

-```

-```csharp

- string authority = "https://login.microsoftonline.com/contoso.com";

- string[] scopes = new string[] { "user.read" };

- IPublicClientApplication app = PublicClientApplicationBuilder

- .Create(clientId)

- .WithAuthority(authority)

- .Build();

- var accounts = await app.GetAccountsAsync();

- AuthenticationResult result = null;

- if (accounts.Any())

- {

- result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())

- .ExecuteAsync();

- }

- else

- {

- try

- {

- result = await app.AcquireTokenByIntegratedWindowsAuth(scopes)

- .ExecuteAsync(CancellationToken.None);

- }

- catch (MsalUiRequiredException ex)

- {

- // MsalUiRequiredException: AADSTS65001: The user or administrator has not consented to use the application

- // with ID '{appId}' named '{appName}'.Send an interactive authorization request for this user and resource.

- // you need to get user consent first. This can be done, if you are not using .NET Core (which does not have any Web UI)

- // by doing (once only) an AcquireToken interactive.

- // If you are using .NET core or don't want to do an AcquireTokenInteractive, you might want to suggest the user to navigate

- // to a URL to consent: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read

- // AADSTS50079: The user is required to use multi-factor authentication.

- // There is no mitigation - if MFA is configured for your tenant and Azure AD decides to enforce it,

- // you need to fallback to an interactive flows such as AcquireTokenInteractive or AcquireTokenByDeviceCode

- }

- catch (MsalServiceException ex)

- {

- // Kind of errors you could have (in ex.Message)

- // MsalServiceException: AADSTS90010: The grant type is not supported over the /common or /consumers endpoints. Please use the /organizations or tenant-specific endpoint.

- // you used common.

- // Mitigation: as explained in the message from Azure AD, the authority needs to be tenanted or otherwise organizations

- // MsalServiceException: AADSTS70002: The request body must contain the following parameter: 'client_secret or client_assertion'.

- // Explanation: this can happen if your application was not registered as a public client application in Azure AD

- // Mitigation: in the Azure portal, edit the manifest for your application and set the `allowPublicClient` to `true`

- }

- catch (MsalClientException ex)

- {

- // Error Code: unknown_user Message: Could not identify logged in user

- // Explanation: the library was unable to query the current Windows logged-in user or this user is not AD or Azure AD

- // joined (work-place joined users are not supported).

- // Mitigation 1: on UWP, check that the application has the following capabilities: Enterprise Authentication,

- // Private Networks (Client and Server), User Account Information

- // Mitigation 2: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the

- // AcquireTokenByIntegratedWindowsAuth form that takes in the username

- // Error Code: integrated_windows_auth_not_supported_managed_user

- // Explanation: This method relies on a protocol exposed by Active Directory (AD). If a user was created in Azure

- // Active Directory without AD backing ("managed" user), this method will fail. Users created in AD and backed by

- // Azure AD ("federated" users) can benefit from this non-interactive method of authentication.

- // Mitigation: Use interactive authentication

- }

- }

- Console.WriteLine(result.Account.Username);

-}

-```

- :::column-end:::

-## [Username Password](#tab/up)

-Username Password authentication is where the sign-in occurs by providing a username/password credential.

-#### Find out if your code uses Username Password authentication

-The ADAL code for your app uses Username password authentication scenarios if it contains a call to `AcquireTokenAsync` available as an extension method of the `AuthenticationContextIntegratedAuthExtensions` class, with the following parameters:

-#### Update the code for username password auth scenarios

-In this case, we replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IPublicClientApplication.AcquireTokenByUsernamePassword`.

-Here's a comparison of ADAL.NET and MSAL.NET code for username password scenarios:

- [!INCLUDE [Common steps](includes/msal-net-adoption-steps-public-clients.md)]

- ADAL

- MSAL

-

-```csharp

-var ac = new AuthenticationContext("https://login.microsoftonline.com/<tenantId>");

-AuthenticationResult result;

-result = await context.AcquireTokenAsync(

- resource, clientId,

- new UserPasswordCredential("john@contoso.com", johnsPassword));

-```

-```csharp

- string authority = "https://login.microsoftonline.com/contoso.com";

- string[] scopes = new string[] { "user.read" };

- IPublicClientApplication app;

- app = PublicClientApplicationBuilder.Create(clientId)

- .WithAuthority(authority)

- .Build();

- var accounts = await app.GetAccountsAsync();

- AuthenticationResult result = null;

- if (accounts.Any())

- {

- result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())

- .ExecuteAsync();

- }

- else

- {

- try

- {

- var securePassword = new SecureString();

- foreach (char c in "dummy") // you should fetch the password

- securePassword.AppendChar(c); // keystroke by keystroke

- result = await app.AcquireTokenByUsernamePassword(scopes,

- "joe@contoso.com",

- securePassword)

- .ExecuteAsync();

- }

- catch(MsalException)

- {

- // See details below

- }

- }

- Console.WriteLine(result.Account.Username);

-```

- :::column-end:::

-## [Device Code](#tab/devicecode)

-Device code flow authentication is where a device of limited UX shows you a device code to complete the authentication flow on an alternate device.

-#### Find out if your code uses Device code flow authentication

-The ADAL code for your app uses device code flow scenarios if it contains a call to `AuthenticationContext.AcquireTokenByDeviceCodeAsync` with the following parameters:

-#### Update the code for device code flow scenarios

- [!INCLUDE [Common steps](includes/msal-net-adoption-steps-public-clients.md)]

-In this case, we replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IPublicClientApplication.AcquireTokenWithDeviceCode`.

-Here's a comparison of ADAL.NET and MSAL.NET code for device code flow scenarios:

- ADAL

- MSAL

-

-```csharp

-static async Task<AuthenticationResult> GetTokenViaCode(AuthenticationContext ctx)

-{

- AuthenticationResult result = null;

- try

- {

- result = await ac.AcquireTokenSilentAsync(resource, clientId);

- }

- catch (AdalException adalException)

- {

- if (adalException.ErrorCode == AdalError.FailedToAcquireTokenSilently

- || adalException.ErrorCode == AdalError.InteractionRequired)

- {

- try

- {

- DeviceCodeResult codeResult = await ctx.AcquireDeviceCodeAsync(resource, clientId);

- Console.WriteLine("You need to sign in.");

- Console.WriteLine("Message: " + codeResult.Message + "\n");

- result = await ctx.AcquireTokenByDeviceCodeAsync(codeResult);

- }

- catch (Exception exc)

- {

- Console.WriteLine("Something went wrong.");

- Console.WriteLine("Message: " + exc.Message + "\n");

- }

- }

- return result;

-}

-```

-```csharp

-private const string ClientId = "<client_guid>";

-private const string Authority = "https://login.microsoftonline.com/contoso.com";

-private readonly string[] scopes = new string[] { "user.read" };

-static async Task<AuthenticationResult> GetATokenForGraph()

-{

- IPublicClientApplication pca = PublicClientApplicationBuilder

- .Create(ClientId)

- .WithAuthority(Authority)

- .WithDefaultRedirectUri()

- .Build();

- var accounts = await pca.GetAccountsAsync();

- // All AcquireToken* methods store the tokens in the cache, so check the cache first

- try

- {

- return await pca.AcquireTokenSilent(scopes, accounts.FirstOrDefault())

- .ExecuteAsync();

- }

- catch (MsalUiRequiredException ex)

- {

- // No token found in the cache or Azure AD insists that a form interactive auth is required (e.g. the tenant admin turned on MFA)

- // If you want to provide a more complex user experience, check out ex.Classification

- return await AcquireByDeviceCodeAsync(pca);

- }

-}

-private static async Task<AuthenticationResult> AcquireByDeviceCodeAsync(IPublicClientApplication pca)

-{

- try

- {

- var result = await pca.AcquireTokenWithDeviceCode(scopes,

- deviceCodeResult =>

- {

- // This will print the message on the console which tells the user where to go sign-in using

- // a separate browser and the code to enter once they sign in.

- // The AcquireTokenWithDeviceCode() method will poll the server after firing this

- // device code callback to look for the successful login of the user via that browser.

- // This background polling (whose interval and timeout data is also provided as fields in the

- // deviceCodeCallback class) will occur until:

- // * The user has successfully logged in via browser and entered the proper code

- // * The timeout specified by the server for the lifetime of this code (typically ~15 minutes) has been reached

- // * The developing application calls the Cancel() method on a CancellationToken sent into the method.

- // If this occurs, an OperationCanceledException will be thrown (see catch below for more details).

- Console.WriteLine(deviceCodeResult.Message);

- return Task.FromResult(0);

- }).ExecuteAsync();

- Console.WriteLine(result.Account.Username);

- return result;

- }

- // TODO: handle or throw all these exceptions depending on your app

- catch (MsalServiceException ex)

- {

- // Kind of errors you could have (in ex.Message)

- // AADSTS50059: No tenant-identifying information found in either the request or implied by any provided credentials.

- // Mitigation: as explained in the message from Azure AD, the authoriy needs to be tenanted. you have probably created

- // your public client application with the following authorities:

- // https://login.microsoftonline.com/common or https://login.microsoftonline.com/organizations

- // AADSTS90133: Device Code flow is not supported under /common or /consumers endpoint.

- // Mitigation: as explained in the message from Azure AD, the authority needs to be tenanted

- // AADSTS90002: Tenant <tenantId or domain you used in the authority> not found. This may happen if there are

- // no active subscriptions for the tenant. Check with your subscription administrator.

- // Mitigation: if you have an active subscription for the tenant this might be that you have a typo in the

- // tenantId (GUID) or tenant domain name.

- }

- catch (OperationCanceledException ex)

- {

- // If you use a CancellationToken, and call the Cancel() method on it, then this *may* be triggered

- // to indicate that the operation was cancelled.

- // See https://learn.microsoft.com/dotnet/standard/threading/cancellation-in-managed-threads

- // for more detailed information on how C# supports cancellation in managed threads.

- }

- catch (MsalClientException ex)

- {

- // Possible cause - verification code expired before contacting the server

- // This exception will occur if the user does not manage to sign-in before a time out (15 mins) and the

- // call to `AcquireTokenWithDeviceCode` is not cancelled in between

- }

-}

-```

- :::column-end:::

-### MSAL benefits

-Key benefits of MSAL.NET for your app include:

- - Azure AD Cached Credential Service (CCS) benefits. CCS operates as an Azure AD backup.

- - Proactive renewal of tokens if the API that you call enables long-lived tokens through [continuous access evaluation](app-resilience-continuous-access-evaluation.md).

-### Troubleshooting

-The following troubleshooting information makes two assumptions:

-If you get an exception with either of the following messages:

-> `AADSTS90002: Tenant 'cf61953b-e41a-46b3-b500-663d279ea744' not found. This may happen if there are no active`

-> `subscriptions for the tenant. Check to make sure you have the correct tenant ID. Check with your subscription`

-> `administrator.`

-You can troubleshoot the exception by using these steps:

-1. Confirm that you're using the latest version of MSAL.NET.

-1. Confirm that the authority host that you set when building the confidential client application and the authority host that you used with ADAL are similar. In particular, is it the same [cloud](msal-national-cloud.md) (Azure Government, Microsoft Azure operated by 21Vianet, or Azure Germany)?

-## Next steps

-Learn more about the [differences between ADAL.NET and MSAL.NET apps](msal-net-differences-adal-net.md).

-Learn more about [token cache serialization in MSAL.NET](msal-net-token-cache-serialization.md)

-description: Learn why and how to migrate from Azure AD Authentication Library for .NET (ADAL.NET) to Microsoft Authentication Library for .NET (MSAL.NET) or Microsoft.Identity.Web

-#Customer intent: As an application developer, I want to learn why and how to migrate from ADAL.NET and MSAL.NET or Microsoft.Identity.Web libraries.

-# Migrating applications to MSAL.NET or Microsoft.Identity.Web

-## Why migrate to MSAL.NET or Microsoft.Identity.Web

-Both the Microsoft Authentication Library for .NET (MSAL.NET) and Azure AD Authentication Library for .NET (ADAL.NET) are used to authenticate Azure AD entities and request tokens from Azure AD. Up until now, most developers have requested tokens from Azure AD for developers platform (v1.0) using Azure AD Authentication Library (ADAL). These tokens are used to authenticate Azure AD identities (work and school accounts).

-MSAL comes with benefits over ADAL. Some of these benefits are listed below:

-**MSAL.NET or Microsoft.Identity.Web are now the recommended auth libraries to use with the Microsoft identity platform**. No new features will be implemented on ADAL.NET. The efforts are focused on improving MSAL.NET. For details see the announcement: [Update your applications to use Microsoft Authentication Library and Microsoft Graph API](https://techcommunity.microsoft.com/t5/azure-active-directory-identity/update-your-applications-to-use-microsoft-authentication-library/ba-p/1257363).

-## Should you migrate to MSAL.NET or to Microsoft.Identity.Web

-Before digging in the details of MSAL.NET vs ADAL.NET, you might want to check if you want to use MSAL.NET or a higher-level abstraction like [Microsoft.Identity.Web](microsoft-identity-web.md).

-For details about the decision tree below, read [MSAL.NET or Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/wiki/MSAL.NET-or-Microsoft.Identity.Web).

-

-<!-- 1P

-## Examples of 1P Migrations

-[See examples](https://identitydivision.visualstudio.com/DevEx/_wiki/wikis/DevEx.wiki/20413/1P-ADAL.NET-to-MSAL.NET-migration-examples) of other 1P teams who have already, or are currently, migrating from ADAL to one of the MSAL+ solutions above. See their code, and in some cases read about their migration story.

- -->

-### Deprecated ADAL.Net NuGet packages and their MSAL.Net equivalents

-You might unknowingly consume ADAL dependencies from other Azure SDKs. Below are few of the deprecated packages and their MSAL alternatives.

-| ADAL.NET Package (Deprecated) | MSAL.NET Package (Current) |

-| -- | -- |

-| `Microsoft.Azure.KeyVault`| `Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keys, Azure.Security.KeyVault.Certificates`|

-| `Microsoft.Azure.Management.Compute`| `Azure.ResourceManager.Compute`|

-| `Microsoft.Azure.Services.AppAuthentication`| `Azure.Identity`|

-| `Microsoft.Azure.Management.StorageSync`| `Azure.ResourceManager.StorageSync`|

-| `Microsoft.Azure.Management.Fluent`| `Azure.ResourceManager`|

-| `Microsoft.Azure.Management.EventGrid`| `Azure.ResourceManager.EventGrid`|

-| `Microsoft.Azure.Management.Automation`| `Azure.ResourceManager.Automation`|

-| `Microsoft.Azure.Management.Compute.Fluent`| `Azure.ResourceManager.Compute`|

-| `Microsoft.Azure.Management.MachineLearning.Fluent`| `Azure.ResourceManager.MachineLearningCompute`|

-| `Microsoft.Azure.Management.Media, windowsazure.mediaservices`| `Azure.ResourceManager.Media`|

-## Next steps

- - [Web apps](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apps#migrating-from-previous-versions--adding-authentication)

- - [Web APIs](https://github.com/AzureAD/microsoft-identity-web/wiki/web-apis)

-description: Learn about providing your own HttpClient and proxy to connect to Azure AD using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn about providing my own HttpClient so I can have fine-grained control of the proxy.

-# Providing your own HttpClient and proxy using MSAL.NET

-When [initializing a client application](msal-net-initializing-client-applications.md), you can use the `.WithHttpClientFactory method` to provide your own HttpClient. Providing your own HttpClient enables advanced scenarios such fine-grained control of an HTTP proxy, customizing user agent headers, or forcing MSAL to use a specific HttpClient (for example in ASP.NET Core web apps/APIs).

-`HttpClient` is intended to be instantiated once and then reused throughout the life of an application. See [Guidelines for using HttpClient: Recommended use](/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use).

-## Initialize with HttpClientFactory

-The following example shows to create an `HttpClientFactory` and then initialize a public client application with it:

-```csharp

-IMsalHttpClientFactory httpClientFactory = new MyHttpClientFactory();

-var pca = PublicClientApplicationBuilder.Create(MsalTestConstants.ClientId)

- .WithHttpClientFactory(httpClientFactory)

- .Build();

-```

-## Example implementation using a proxy

-```csharp

-public class HttpFactoryWithProxy : IMsalHttpClientFactory

-{

- private static HttpClient _httpClient;

- public HttpFactoryWithProxy()

- {

- // Consider using Lazy<T>

- if (_httpClient == null)

- {

- var proxy = new WebProxy

- {

- Address = new Uri($"http://{proxyHost}:{proxyPort}"),

- BypassProxyOnLocal = false,

- UseDefaultCredentials = false,

- Credentials = new NetworkCredential(

- userName: proxyUserName,

- password: proxyPassword)

- };

- // Now create a client handler which uses that proxy

- var httpClientHandler = new HttpClientHandler

- {

- Proxy = proxy,

- };

- _httpClient = new HttpClient(handler: httpClientHandler);

- }

- }

- public HttpClient GetHttpClient()

- {

- return _httpClient;

- }

-}

-```

-## HttpClient and Xamarin iOS

-When using Xamarin iOS, it is recommended to create an `HttpClient` that explicitly uses the `NSURLSession`-based handler for iOS 7 and newer. MSAL.NET automatically creates an `HttpClient` that uses `NSURLSessionHandler` for iOS 7 and newer. For more information, read the [Xamarin iOS documentation for HttpClient](/xamarin/cross-platform/macios/http-stack).

-description: Learn about serialization and custom serialization of the token cache using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn about token cache serialization so I can have fine-grained control of the proxy.

-# Token cache serialization in MSAL.NET

-After Microsoft Authentication Library (MSAL) [acquires a token](msal-acquire-cache-tokens.md), it caches that token. Public client applications (desktop and mobile apps) should try to get a token from the cache before acquiring a token by another method. Acquisition methods on confidential client applications manage the cache themselves. This article discusses default and custom serialization of the token cache in MSAL.NET.

-## Quick summary

-The recommendation is:

- - If you request tokens for users in a production application, use a [distributed token cache](msal-net-token-cache-serialization.md?tabs=aspnet#distributed-caches) (Redis, SQL Server, Azure Cosmos DB, distributed memory). Use token cache serializers available from [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache/).

- - If you want to use an in-memory cache and you're only using [`AcquireTokenForClient`](/dotnet/api/microsoft.identity.client.acquiretokenforclientparameterbuilder), either reuse the confidential client application instance and don't add a serializer, or create a new confidential client application and enable the [shared cache option](msal-net-token-cache-serialization.md?tabs=aspnet#no-token-cache-serialization).

-

- A shared cache is faster because it's not serialized. However, the memory grows as tokens are cached. The number of tokens is equal to the number of tenants times the number of downstream APIs. An app token is about 2 KB in size, whereas tokens for a user are about 7 KB in size. It's great for development, or if you have few users.

-## [ASP.NET Core web apps and web APIs](#tab/aspnetcore)

-The [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache) NuGet package provides token cache serialization within the [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) library.

-If you're using the [MSAL library](/dotnet/api/microsoft.identity.client) directly in an ASP.NET Core app, consider using [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web), which provides a simpler, higher-level API. Otherwise, see [Non-ASP.NET Core web apps and web APIs](?tabs=aspnet#configuring-the-token-cache), which covers direct MSAL usage.

-| Extension method | Description |

-| - | |

-| [AddInMemoryTokenCaches](/dotnet/api/microsoft.identity.web.microsoftidentityappcallswebapiauthenticationbuilder.addinmemorytokencaches) | Creates a temporary cache in memory for token storage and retrieval. In-memory token caches are faster than other cache types, but their tokens aren't persisted between application restarts, and you can't control the cache size. In-memory caches are good for applications that don't require tokens to persist between app restarts. Use an in-memory token cache in apps that participate in machine-to-machine auth scenarios like services, daemons, and others that use [AcquireTokenForClient](/dotnet/api/microsoft.identity.client.acquiretokenforclientparameterbuilder) (the client credentials grant). In-memory token caches are also good for sample applications and during local app development. Microsoft.Identity.Web versions 1.19.0+ share an in-memory token cache across all application instances.

-| [AddSessionTokenCaches](/dotnet/api/microsoft.identity.web.microsoftidentityappcallswebapiauthenticationbuilderextension.addsessiontokencaches) | The token cache is bound to the user session. This option isn't ideal if the ID token contains many claims, because the cookie becomes too large.

-| `AddDistributedTokenCaches` | The token cache is an adapter against the ASP.NET Core `IDistributedCache` implementation. It enables you to choose between a distributed memory cache, a Redis cache, a distributed NCache, or a SQL Server cache. For details about the `IDistributedCache` implementations, see [Distributed memory cache](/aspnet/core/performance/caching/distributed).

-### In-memory token cache

-Here's an example of code that uses the in-memory cache in the [ConfigureServices](/dotnet/api/microsoft.aspnetcore.hosting.startupbase.configureservices) method of the [Startup](/aspnet/core/fundamentals/startup) class in an ASP.NET Core application:

-```CSharp

-using Microsoft.Identity.Web;

-public class Startup

-{

- const string scopesToRequest = "user.read";

-

- public void ConfigureServices(IServiceCollection services)

- {

- // code before

- services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)

- .AddMicrosoftIdentityWebApp(Configuration)

- .EnableTokenAcquisitionToCallDownstreamApi(new string[] { scopesToRequest })

- .AddInMemoryTokenCaches();

- // code after

- }

- // code after

-}

-```

-`AddInMemoryTokenCaches` is suitable in production if you request app-only tokens. If you use user tokens, consider using a distributed token cache.

-Token cache configuration code is similar between ASP.NET Core web apps and web APIs.

-### Distributed token caches

-Here are examples of possible distributed caches:

-```C#

-// or use a distributed Token Cache by adding

- services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)

- .AddMicrosoftIdentityWebApp(Configuration)

- .EnableTokenAcquisitionToCallDownstreamApi(new string[] { scopesToRequest }

- .AddDistributedTokenCaches();

-// Distributed token caches have a L1/L2 mechanism.

-// L1 is in memory, and L2 is the distributed cache

-// implementation that you will choose below.

-// You can configure them to limit the memory of the

-// L1 cache, encrypt, and set eviction policies.

-services.Configure<MsalDistributedTokenCacheAdapterOptions>(options =>

- {

- // Optional: Disable the L1 cache in apps that don't use session affinity

- // by setting DisableL1Cache to 'true'.

- options.DisableL1Cache = false;

-

- // Or limit the memory (by default, this is 500 MB)

- options.L1CacheOptions.SizeLimit = 1024 * 1024 * 1024; // 1 GB

- // You can choose if you encrypt or not encrypt the cache

- options.Encrypt = false;

- // And you can set eviction policies for the distributed

- // cache.

- options.SlidingExpiration = TimeSpan.FromHours(1);

- });

-// Then, choose your implementation of distributed cache

-// --

-// good for prototyping and testing, but this is NOT persisted and it is NOT distributed - do not use in production

-services.AddDistributedMemoryCache();

-// Or a Redis cache

-// Requires the Microsoft.Extensions.Caching.StackExchangeRedis NuGet package

-services.AddStackExchangeRedisCache(options =>

-{

- options.Configuration = "localhost";

- options.InstanceName = "SampleInstance";

-});

-// You can even decide if you want to repair the connection

-// with Redis and retry on Redis failures.

-services.Configure<MsalDistributedTokenCacheAdapterOptions>(options =>

-{

- options.OnL2CacheFailure = (ex) =>

- {

- if (ex is StackExchange.Redis.RedisConnectionException)

- {

- // action: try to reconnect or something

- return true; //try to do the cache operation again

- }

- return false;

- };

-});

-// Or even a SQL Server token cache

-// Requires the Microsoft.Extensions.Caching.SqlServer NuGet package

-services.AddDistributedSqlServerCache(options =>

-{

- options.ConnectionString = _config["DistCache_ConnectionString"];

- options.SchemaName = "dbo";

- options.TableName = "TestCache";

-});

-// Or an Azure Cosmos DB cache

-// Requires the Microsoft.Extensions.Caching.Cosmos NuGet package

-services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>

-{

- cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];

- cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];

- cacheOptions.ClientBuilder = new CosmosClientBuilder(Configuration["CosmosConnectionString"]);

- cacheOptions.CreateIfNotExists = true;

-});

-```

-For more information, see:

-The usage of distributed cache is featured in the [ASP.NET Core web app tutorial](/aspnet/core/tutorials/first-mvc-app/) in the [phase 2-2 token cache](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/2-WebApp-graph-user/2-2-TokenCache).

-## [Non-ASP.NET Core web apps and web APIs](#tab/aspnet)

-If you're using MSAL.NET in your web app or web API, you can benefit from token cache serializers in [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache)

-### Referencing the NuGet package

-Add the [Microsoft.Identity.Web.TokenCache](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenCache) NuGet package to your project instead of MSAL.NET.

-### Configuring the token cache

-The following code shows how to add an in-memory well-partitioned token cache to your app.

-```CSharp

-using Microsoft.Identity.Web;

-using Microsoft.Identity.Client;

-using Microsoft.Extensions.DependencyInjection;

-```

-```CSharp

-public static async Task<AuthenticationResult> GetTokenAsync(string clientId, X509Certificate cert, string authority, string[] scopes)

- {

- // Create the confidential client application

- app= ConfidentialClientApplicationBuilder.Create(clientId)

- // Alternatively to the certificate, you can use .WithClientSecret(clientSecret)

- .WithCertificate(cert)

- .WithLegacyCacheCompatibility(false)

- .WithAuthority(authority)

- .Build();

- // Add a static in-memory token cache. Other options available: see below

- app.AddInMemoryTokenCache(); // Microsoft.Identity.Web.TokenCache 1.17+

-

- // Make the call to get a token for client_credentials flow (app-to-app scenario)

- return await app.AcquireTokenForClient(scopes).ExecuteAsync();

-

- // OR Make the call to get a token for OBO (web API scenario)

- return await app.AcquireTokenOnBehalfOf(scopes, userAssertion).ExecuteAsync();

-

- // OR Make the call to get a token via auth code (web app scenario)

- return await app.AcquireTokenByAuthorizationCode(scopes, authCode);

-

- // OR, when the user has previously logged in, get a token silently

- string homeAccountId = User.GetHomeAccountId(); // uid and utid claims

- var account = await app.GetAccountAsync(homeAccountId);

- try

- {

- return await app.AcquireTokenSilent(scopes, account).ExecuteAsync();;

- }

- catch (MsalUiRequiredException)

- {

- // cannot get a token silently, so redirect the user to be challenged

- }

- }

-```

-### Available caching technologies

-Instead of `app.AddInMemoryTokenCache();`, you can use different caching serialization technologies. For example, you can use no-serialization, in-memory, and distributed token cache storage provided by .NET.

-<a id="no-token-cache-serialization"></a>

-#### Token cache without serialization

-Use `.WithCacheOptions(CacheOptions.EnableSharedCacheOptions)` when building the application and don't add any serializer.

-> [!IMPORTANT]

-> There is no way to control the size of the cache with this option. If you are building a website, a web API, or a multi-tenant S2S app, then use the `In-memory token cache` option.

-```CSharp

- // Create the confidential client application

- app= ConfidentialClientApplicationBuilder.Create(clientId)

- // Alternatively to the certificate, you can use .WithClientSecret(clientSecret)

- .WithCertificate(cert)

- .WithLegacyCacheCompatibility(false)

- .WithCacheOptions(CacheOptions.EnableSharedCacheOptions)

- .WithAuthority(authority)

- .Build();

-```

-`WithCacheOptions(CacheOptions.EnableSharedCacheOptions)` makes the internal MSAL token cache shared between MSAL client application instances. Sharing a token cache is faster than using any token cache serialization, but the internal in-memory token cache doesn't have eviction policies. Existing tokens are refreshed in place, but fetching tokens for different users, tenants, and resources makes the cache grow accordingly.

-If you use this approach and have a large number of users or tenants, be sure to monitor the memory footprint. If the memory footprint becomes a problem, consider enabling token cache serialization, which might reduce the internal cache size. Currently, you can't use shared cache and cache serialization together.

-#### In-memory token cache

-In-memory token cache serialization is great in samples. It's also good in production applications if you only request app tokens (`AcquireTokenForClient`), provided that you don't mind if the token cache is lost when the web app is restarted. We don't recommend it in production if you request user tokens (`AcquireTokenByAuthorizationCode`, `AcquireTokenSilent`, `AcquireTokenOnBehalfOf`).

-```CSharp

- // Add an in-memory token cache

- app.AddInMemoryTokenCache();

-```

-You can also specify options to limit the size of the in-memory token cache:

-```CSharp

- // Add an in-memory token cache with options

- app.AddInMemoryTokenCache(services =>

- {

- // Configure the memory cache options

- services.Configure<MemoryCacheOptions>(options =>

- {

- options.SizeLimit = 500 * 1024 * 1024; // in bytes (500 MB)

- });

- }

- );

-```

-#### Distributed caches

-If you use `app.AddDistributedTokenCache`, the token cache is an adapter against the .NET `IDistributedCache` implementation. So you can choose between a SQL Server cache, a Redis cache, an Azure Cosmos DB cache, or any other cache implementing the [IDistributedCache](/dotnet/api/microsoft.extensions.caching.distributed.idistributedcache?view=dotnet-plat-ext-6.0&preserve-view=true) interface.

-For testing purposes only, you may want to use `services.AddDistributedMemoryCache()`, an in-memory implementation of `IDistributedCache`.

-Here's the code for a SQL Server cache:

-```CSharp

- // SQL Server token cache

- app.AddDistributedTokenCache(services =>

- {

- services.AddDistributedSqlServerCache(options =>

- {

-

- // Requires to reference Microsoft.Extensions.Caching.SqlServer

- options.ConnectionString = @"Data Source=(localdb)\MSSQLLocalDB;Initial Catalog=TestCache;Integrated Security=True;Connect Timeout=30;Encrypt=False;TrustServerCertificate=False;ApplicationIntent=ReadWrite;MultiSubnetFailover=False";

- options.SchemaName = "dbo";

- options.TableName = "TestCache";

- // You don't want the SQL token cache to be purged before the access token has expired. Usually

- // access tokens expire after 1 hour (but this can be changed by token lifetime policies), whereas

- // the default sliding expiration for the distributed SQL database is 20 mins.

- // Use a value above 60 mins (or the lifetime of a token in case of longer-lived tokens)

- options.DefaultSlidingExpiration = TimeSpan.FromMinutes(90);

- });

- });

-```

-Here's the code for a Redis cache:

-```CSharp

- // Redis token cache

- app.AddDistributedTokenCache(services =>

- {

- // Requires to reference Microsoft.Extensions.Caching.StackExchangeRedis

- services.AddStackExchangeRedisCache(options =>

- {

- options.Configuration = "localhost";

- options.InstanceName = "Redis";

- });

- // You can even decide if you want to repair the connection

- // with Redis and retry on Redis failures.

- services.Configure<MsalDistributedTokenCacheAdapterOptions>(options =>

- {

- options.OnL2CacheFailure = (ex) =>

- {

- if (ex is StackExchange.Redis.RedisConnectionException)

- {

- // action: try to reconnect or something

- return true; //try to do the cache operation again

- }

- return false;

- };

- });

- });

-```

-Here's the code for an Azure Cosmos DB cache:

-```CSharp

- // Azure Cosmos DB token cache

- app.AddDistributedTokenCache(services =>

- {

- // Requires to reference Microsoft.Extensions.Caching.Cosmos

- services.AddCosmosCache((CosmosCacheOptions cacheOptions) =>

- {

- cacheOptions.ContainerName = Configuration["CosmosCacheContainer"];

- cacheOptions.DatabaseName = Configuration["CosmosCacheDatabase"];

- cacheOptions.ClientBuilder = new CosmosClientBuilder(Configuration["CosmosConnectionString"]);

- cacheOptions.CreateIfNotExists = true;

- });

- });

-```

-For more information about distributed caches, see:

-### Disabling a legacy token cache

-MSAL has some internal code specifically to enable interacting with legacy Microsoft Authentication Library (ADAL) cache. When MSAL and ADAL aren't used side by side, the legacy cache isn't used and the related legacy code is unnecessary. MSAL [4.25.0](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases/tag/4.25.0) adds the ability to disable legacy ADAL cache code and improve cache usage performance. For a performance comparison before and after disabling the legacy cache, see [GitHub pull request 2309](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/pull/2309).

-Call `.WithLegacyCacheCompatibility(false)` on an application builder like the following code.

-```csharp

-var app = ConfidentialClientApplicationBuilder

- .Create(clientId)

- .WithClientSecret(clientSecret)

- .WithLegacyCacheCompatibility(false)

- .Build();

-```

-### Samples

-## [Desktop apps](#tab/desktop)

-In desktop applications, we recommend that you use the cross-platform token cache. MSAL.NET provides the cross-platform token cache in a separate library named [Microsoft.Identity.Client.Extensions.Msal](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet).

-#### Referencing the NuGet package

-Add the [Microsoft.Identity.Client.Extensions.Msal](https://www.nuget.org/packages/Microsoft.Identity.Client.Extensions.Msal/) NuGet package to your project.

-#### Configuring the token cache

-For details, see the [Cross platform Token Cache](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet/wiki/Cross-platform-Token-Cache). Here's an example using the cross-platform token cache:

-```csharp

- var storageProperties =

- new StorageCreationPropertiesBuilder(Config.CacheFileName, Config.CacheDir)

- .WithLinuxKeyring(

- Config.LinuxKeyRingSchema,

- Config.LinuxKeyRingCollection,

- Config.LinuxKeyRingLabel,

- Config.LinuxKeyRingAttr1,

- Config.LinuxKeyRingAttr2)

- .WithMacKeyChain(

- Config.KeyChainServiceName,

- Config.KeyChainAccountName)

- .Build();

- IPublicClientApplication pca = PublicClientApplicationBuilder.Create(clientId)

- .WithAuthority(Config.Authority)

- .WithRedirectUri("http://localhost") // make sure to register this redirect URI for the interactive login

- .Build();

-

-// This hooks up the cross-platform cache into MSAL

-var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties );

-cacheHelper.RegisterCache(pca.UserTokenCache);

-

-```

-#### Plain-text fallback mode

-The cross-platform token cache allows you to store unencrypted tokens in plain text. This feature is intended for use in development environments for debugging purposes only.

-You can use the plain-text fallback mode by using the following code pattern.

-```csharp

-storageProperties =

- new StorageCreationPropertiesBuilder(

- Config.CacheFileName + ".plaintext",

- Config.CacheDir)

- .WithUnprotectedFile()

- .Build();

-var cacheHelper = await MsalCacheHelper.CreateAsync(storageProperties).ConfigureAwait(false);

-```

-## [Mobile apps](#tab/mobile)

-MSAL.NET provides an in-memory token cache by default. Serialization is provided by default for platforms where secure storage is available for a user as part of the platform: Universal Windows Platform (UWP), Xamarin.iOS, and Xamarin.Android.

-## [Write your own cache](#tab/custom)

-If you want to write your own token cache serializer, MSAL.NET provides custom token cache serialization in the .NET Framework and .NET Core subplatforms. Events are fired when the cache is accessed. Apps can choose whether to serialize or deserialize the cache.

-On confidential client applications that handle users (web apps that sign in users and call web APIs, and web APIs that call downstream web APIs), there can be many users. The users are processed in parallel. For security and performance reasons, our recommendation is to serialize one cache per user. Serialization events compute a cache key based on the identity of the processed user and serialize or deserialize a token cache for that user.

-Remember, custom serialization isn't available on mobile platforms (UWP, Xamarin.iOS, and Xamarin.Android). MSAL already defines a secure and performant serialization mechanism for these platforms. .NET desktop and .NET Core applications, however, have varied architectures. And MSAL can't implement a general-purpose serialization mechanism.

-For example, websites might choose to store tokens in a Redis cache, or desktop apps might store tokens in an encrypted file. So serialization isn't provided out of the box. To have a persistent token cache application in .NET desktop or .NET Core, customize the serialization.

-The following classes and interfaces are used in token cache serialization:

-

-> [!IMPORTANT]

-> MSAL.NET creates token caches for you. It provides you with the `IToken` cache when you call an application's `UserTokenCache` and `AppTokenCache` properties. You're not supposed to implement the interface yourself.

->

-> Your responsibility, when you implement a custom token cache serialization, is to react to `BeforeAccess` and `AfterAccess` events (or their `Async` varieties). The `BeforeAccess` delegate is responsible for deserializing the cache, whereas the `AfterAccess` one is responsible for serializing the cache. Parts of these events store or load blobs, which are passed through the event argument to whatever storage you want.

-The strategies are different depending on whether you're writing a token cache serialization for a [public client application](msal-client-applications.md) (desktop) or a [confidential client application](msal-client-applications.md) (web app, web API, daemon app).

-### Custom token cache for a web app or web API (confidential client application)

-If you want to write your own token cache serializer for confidential client applications, we recommend that you inherit from [Microsoft.Identity.Web.MsalAbstractTokenCacheProvider](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.TokenCache/MsalAbstractTokenCacheProvider.cs) and override the `WriteCacheBytesAsync` and `ReadCacheBytesAsync` methods.

-Examples of token cache serializers are provided in [Microsoft.Identity.Web/TokenCacheProviders](https://github.com/AzureAD/microsoft-identity-web/blob/master/src/Microsoft.Identity.Web.TokenCache).

-### Custom token cache for a desktop or mobile app (public client application)

-MSAL.NET v2.x and later versions provide several options for serializing the token cache of a public client. You can serialize the cache only to the MSAL.NET format (the unified format cache is common across MSAL and the platforms).

-Customizing the token cache serialization to share the single sign-on state between ADAL.NET 3.x, ADAL.NET 5.x, and MSAL.NET is explained in part of the following sample: [active-directory-dotnet-v1-to-v2](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2).

-> [!Note]

-> The MSAL.NET 1.1.4-preview token cache format is no longer supported in MSAL 2.x. If you have applications that use MSAL.NET 1.x, your users will have to sign in again. The migration from ADAL 4.x (and 3.x) is supported.

-#### Simple token cache serialization (MSAL only)

-The following code is an example of a naive implementation of custom serialization of a token cache for desktop applications. Here, the user token cache is a file in the same folder as the application.

-After you build the application, you enable the serialization by calling the `TokenCacheHelper.EnableSerialization()` method and passing the application's `UserTokenCache` property.

-```csharp

-app = PublicClientApplicationBuilder.Create(ClientId)

- .Build();

-TokenCacheHelper.EnableSerialization(app.UserTokenCache);

-```

-The `TokenCacheHelper` helper class is defined as:

-```csharp

-static class TokenCacheHelper

- {

- public static void EnableSerialization(ITokenCache tokenCache)

- {

- tokenCache.SetBeforeAccess(BeforeAccessNotification);

- tokenCache.SetAfterAccess(AfterAccessNotification);

- }

- /// <summary>

- /// Path to the token cache. Note that this could be something different, for instance, for MSIX applications:

- /// private static readonly string CacheFilePath =

- /// $"{Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)}\{AppName}\msalcache.bin";

- /// </summary>

- public static readonly string CacheFilePath = System.Reflection.Assembly.GetExecutingAssembly().Location + ".msalcache.bin3";

- private static readonly object FileLock = new object();

- private static void BeforeAccessNotification(TokenCacheNotificationArgs args)

- {

- lock (FileLock)

- {

- args.TokenCache.DeserializeMsalV3(File.Exists(CacheFilePath)

- ? ProtectedData.Unprotect(File.ReadAllBytes(CacheFilePath),

- null,

- DataProtectionScope.CurrentUser)

- : null);

- }

- }

- private static void AfterAccessNotification(TokenCacheNotificationArgs args)

- {

- // if the access operation resulted in a cache update

- if (args.HasStateChanged)

- {

- lock (FileLock)

- {

- // reflect changes in the persistent store

- File.WriteAllBytes(CacheFilePath,

- ProtectedData.Protect(args.TokenCache.SerializeMsalV3(),

- null,

- DataProtectionScope.CurrentUser)

- );

- }

- }

- }

- }

-```

-A product-quality, file-based token cache serializer for public client applications (for desktop applications running on Windows, Mac, and Linux) is available from the [Microsoft.Identity.Client.Extensions.Msal](https://github.com/AzureAD/microsoft-authentication-extensions-for-dotnet/tree/master/src/Microsoft.Identity.Client.Extensions.Msal) open-source library. You can include it in your applications from the following NuGet package: [Microsoft.Identity.Client.Extensions.Msal](https://www.nuget.org/packages/Microsoft.Identity.Client.Extensions.Msal/).

-#### Dual token cache serialization (MSAL unified cache)

-If you want to implement token cache serialization with the unified cache format (common to MSAL.NET 2.x and other MSALs of the same generation or older, on the same platform), take a look at the following sample: https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/TokenCacheMigration/ADAL2MSAL.

-## Monitor cache hit ratios and cache performance

-MSAL exposes important metrics as part of [AuthenticationResult.AuthenticationResultMetadata](/dotnet/api/microsoft.identity.client.authenticationresultmetadata) object. You can log these metrics to assess the health of your application.

-| Metric | Meaning | When to trigger an alarm? |

-| :-: | :-: | :--: |

-| `DurationTotalInMs` | Total time spent in MSAL, including network calls and cache. | Alarm on overall high latency (> 1 second). Value depends on token source. From the cache: one cache access. From Azure Active Directory (Azure AD): two cache accesses plus one HTTP call. First ever call (per-process) takes longer because of one extra HTTP call. |

-| `DurationInCacheInMs` | Time spent loading or saving the token cache, which is customized by the app developer (for example, save to Redis).| Alarm on spikes. |

-| `DurationInHttpInMs`| Time spent making HTTP calls to Azure AD. | Alarm on spikes.|

-| `TokenSource` | Source of the token. Tokens are retrieved from the cache much faster (for example, ~100 ms versus ~700 ms). Can be used to monitor and alarm the cache hit ratio. | Use with `DurationTotalInMs`. |

-| `CacheRefreshReason` | Reason for fetching the access token from the identity provider. | Use with `TokenSource`. |

-## Next steps

-The following samples illustrate token cache serialization.

-| Sample | Platform | Description|

-| | -- | -- |

-|[active-directory-dotnet-desktop-msgraph-v2](https://github.com/azure-samples/active-directory-dotnet-desktop-msgraph-v2) | Desktop (WPF) | Windows Desktop .NET (WPF) application that calls the Microsoft Graph API. |

-|[active-directory-dotnet-v1-to-v2](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2) | Desktop (console) | Set of Visual Studio solutions that illustrate the migration of Azure AD v1.0 applications (using ADAL.NET) to Microsoft identity platform applications (using MSAL.NET). In particular, see [Token cache migration](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/blob/master/TokenCacheMigration/README.md) and [Confidential client token cache](https://github.com/Azure-Samples/active-directory-dotnet-v1-to-v2/tree/master/ConfidentialClientTokenCache). |

-[ms-identity-aspnet-webapp-openidconnect](https://github.com/Azure-Samples/ms-identity-aspnet-webapp-openidconnect) | ASP.NET (net472) | Example of token cache serialization in an ASP.NET MVC application (using MSAL.NET).

-Add the redirect URI to the app's registration in the [Azure portal](https://portal.azure.com). To generate a properly formatted redirect URI, use **App registrations** in the Azure portal to generate the brokered redirect URI from the bundle ID.

-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.

-1. Select **Azure Active Directory** > **App registrations** > your registered app

- :::image type="content" source="media/msal-net-use-brokers-with-xamarin-apps/portal-01-ios-platform-settings.png" alt-text="iOS platform settings with generated redirect URI in Azure portal":::

-MSAL uses URLs to invoke the broker and then return to your app. To complete that round trip, register a **Redirect URI** for your app by using the [Azure portal](https://portal.azure.com).

-The last part of the URI, `hgbUYHVBYUTvuvT&Y6tr554365466=`, is the Base64-encoded version of the signature that the APK is signed with. While developing your app in Visual Studio, if you're debugging your code without signing the APK with a specific certificate, Visual Studio signs the APK for you for debugging purposes. When Visual Studio signs the APK for you in this way, it gives it a unique signature for the machine it's built on. Thus, each time you build your app on a different machine, you'll need to update the redirect URI in the application's code and the application's registration in the Azure portal in order to authenticate with MSAL.

-While debugging, you may encounter an MSAL exception (or log message) stating the redirect URI provided is incorrect. **The exception or log message also indicates the redirect URI you should be using** with the current machine you're debugging on. You can use the provided redirect URI to continue developing your app as long as you update redirect URI in code and add the provided redirect URI to the app's registration in the Azure portal.

-Once you're ready to finalize your code, update the redirect URI in the code and the application's registration in the Azure portal to use the signature of the certificate you sign the APK with.

-description: Learn how a user can get pre-consent for several resources using the Microsoft Authentication Library for .NET (MSAL.NET).

-#Customer intent: As an application developer, I want to learn how to specify additional scopes so I can get pre-consent for several resources.

-# User gets consent for several resources using MSAL.NET

-The Microsoft identity platform does not allow you to get a token for several resources at once. When using the Microsoft Authentication Library for .NET (MSAL.NET), the scopes parameter in the acquire token method should only contain scopes for a single resource. However, you can pre-consent to several resources upfront by specifying additional scopes using the `.WithExtraScopeToConsent` builder method.

-> [!NOTE]

-> Getting consent for several resources works for Microsoft identity platform, but not for Azure AD B2C. Azure AD B2C supports only admin consent, not user consent.

-For example, if you have two resources that have 2 scopes each:

-You should use the `.WithExtraScopeToConsent` modifier which has the *extraScopesToConsent* parameter as shown in the following example:

-```csharp

-string[] scopesForCustomerApi = new string[]

-{

- "https://mytenant.onmicrosoft.com/customerapi/customer.read",

- "https://mytenant.onmicrosoft.com/customerapi/customer.write"

-};

-string[] scopesForVendorApi = new string[]