├── .gitattributes ├── .github ├── CODEOWNERS ├── policies │ ├── auto-merge.yml │ ├── label-new-issues.yml │ ├── scheduled-prod-sync.yml │ ├── scheduled-stage-sync.yml │ ├── stale-issues.yml │ └── tag-automatic-pr.yml └── workflows │ └── linkchecker.yml ├── .gitignore ├── .lycheeignore ├── .openpublishing.publish.config.json ├── .openpublishing.redirection.json ├── LICENSE ├── LICENSE-CODE ├── README.md ├── SECURITY.md ├── ThirdPartyNotices ├── dotnet ├── .sourcemap-ecma-0.json ├── api │ └── overview │ │ ├── core-msal-net-libraries │ │ └── index.md │ │ └── index.md ├── docfx.json ├── docs-ref-toc │ └── toc.yml ├── msal-dotnet-ref-breadcrumb │ └── toc.yml └── xml │ ├── FrameworksIndex │ └── msal-dotnet-latest.xml │ ├── Microsoft.Identity.Client.Advanced │ └── AcquireTokenParameterBuilderExtensions.xml │ ├── Microsoft.Identity.Client.AppConfig │ ├── ManagedIdentityId.xml │ └── PoPAuthenticationConfiguration.xml │ ├── Microsoft.Identity.Client.AuthScheme.PoP │ └── IPoPCryptoProvider.xml │ ├── Microsoft.Identity.Client.AuthScheme │ └── IAuthenticationOperation.xml │ ├── Microsoft.Identity.Client.Broker │ └── BrokerExtension.xml │ ├── Microsoft.Identity.Client.Cache │ ├── CacheData.xml │ └── CacheLevel.xml │ ├── Microsoft.Identity.Client.Desktop │ ├── DesktopExtensions.xml │ └── WamExtension.xml │ ├── Microsoft.Identity.Client.Extensibility │ ├── AbstractConfidentialClientAcquireTokenParameterBuilderExtension.xml │ ├── AcquireTokenForClientBuilderExtensions.xml │ ├── AcquireTokenInteractiveParameterBuilderExtensions.xml │ ├── AcquireTokenOnBehalfOfParameterBuilderExtensions.xml │ ├── AppTokenProviderParameters.xml │ ├── AppTokenProviderResult.xml │ ├── ConfidentialClientApplicationBuilderExtensions.xml │ ├── ConfidentialClientApplicationExtensions.xml │ ├── ICustomWebUi.xml │ ├── MsalAuthenticationExtension.xml │ └── OnBeforeTokenRequestData.xml │ ├── Microsoft.Identity.Client.Kerberos │ ├── KerberosKeyTypes.xml │ ├── KerberosSupplementalTicket.xml │ ├── KerberosSupplementalTicketManager.xml │ └── KerberosTicketContainer.xml │ ├── Microsoft.Identity.Client.ManagedIdentity │ └── ManagedIdentitySource.xml │ ├── Microsoft.Identity.Client.Platforms.Features.DesktopOs.Kerberos │ └── Credential.xml │ ├── Microsoft.Identity.Client.RP │ ├── AcquireTokenForClientParameterBuilderForResourceProviders.xml │ └── ConfidentialClientApplicationBuilderForResourceProviders.xml │ ├── Microsoft.Identity.Client.Region │ └── RegionOutcome.xml │ ├── Microsoft.Identity.Client.SSHCertificates │ └── SSHExtensions.xml │ ├── Microsoft.Identity.Client.TelemetryCore.TelemetryClient │ └── TelemetryData.xml │ ├── Microsoft.Identity.Client.Utils.Windows │ └── WindowsNativeUtils.xml │ ├── Microsoft.Identity.Client.Utils │ └── MacMainThreadScheduler.xml │ ├── Microsoft.Identity.Client │ ├── AadAuthorityAudience.xml │ ├── AbstractAcquireTokenParameterBuilder`1.xml │ ├── AbstractApplicationBuilder`1.xml │ ├── AbstractClientAppBaseAcquireTokenParameterBuilder`1.xml │ ├── AbstractConfidentialClientAcquireTokenParameterBuilder`1.xml │ ├── AbstractManagedIdentityAcquireTokenParameterBuilder`1.xml │ ├── AbstractPublicClientAcquireTokenParameterBuilder`1.xml │ ├── AccountExtensions.xml │ ├── AccountId.xml │ ├── AcquireTokenByAuthorizationCodeParameterBuilder.xml │ ├── AcquireTokenByIntegratedWindowsAuthParameterBuilder.xml │ ├── AcquireTokenByRefreshTokenParameterBuilder.xml │ ├── AcquireTokenByUsernameAndPasswordConfidentialParameterBuilder.xml │ ├── AcquireTokenByUsernamePasswordParameterBuilder.xml │ ├── AcquireTokenForClientParameterBuilder.xml │ ├── AcquireTokenForManagedIdentityParameterBuilder.xml │ ├── AcquireTokenInteractiveParameterBuilder.xml │ ├── AcquireTokenOnBehalfOfParameterBuilder.xml │ ├── AcquireTokenSilentParameterBuilder.xml │ ├── AcquireTokenWithDeviceCodeParameterBuilder.xml │ ├── ApplicationBase.xml │ ├── ApplicationOptions.xml │ ├── AssertionRequestOptions.xml │ ├── AuthenticationHeaderParser.xml │ ├── AuthenticationInfoParameters.xml │ ├── AuthenticationResult.xml │ ├── AuthenticationResultMetadata.xml │ ├── AzureCloudInstance.xml │ ├── BaseAbstractAcquireTokenParameterBuilder`1.xml │ ├── BaseAbstractApplicationBuilder`1.xml │ ├── BaseApplicationOptions.xml │ ├── BrokerOptions+OperatingSystems.xml │ ├── BrokerOptions.xml │ ├── CacheOptions.xml │ ├── CacheRefreshReason.xml │ ├── ClientApplicationBase.xml │ ├── ConfidentialClientApplication.xml │ ├── ConfidentialClientApplicationBuilder.xml │ ├── ConfidentialClientApplicationOptions.xml │ ├── DeviceCodeResult.xml │ ├── EmbeddedWebViewOptions.xml │ ├── GetAuthorizationRequestUrlParameterBuilder.xml │ ├── IAccount.xml │ ├── IAppConfig.xml │ ├── IApplicationBase.xml │ ├── IByRefreshToken.xml │ ├── IByUsernameAndPassword.xml │ ├── IClientApplicationBase.xml │ ├── IConfidentialClientApplication.xml │ ├── ILongRunningWebApi.xml │ ├── IManagedIdentityApplication.xml │ ├── IMsalHttpClientFactory.xml │ ├── IMsalSFHttpClientFactory.xml │ ├── IPublicClientApplication.xml │ ├── ITelemetryConfig.xml │ ├── ITelemetryEventPayload.xml │ ├── ITokenCache.xml │ ├── ITokenCacheSerializer.xml │ ├── IntuneAppProtectionPolicyRequiredException.xml │ ├── LogCallback.xml │ ├── LogLevel.xml │ ├── ManagedIdentityApplication.xml │ ├── ManagedIdentityApplicationBuilder.xml │ ├── Metrics.xml │ ├── MsalClaimsChallengeException.xml │ ├── MsalClientException.xml │ ├── MsalError.xml │ ├── MsalException.xml │ ├── MsalManagedIdentityException.xml │ ├── MsalServiceException.xml │ ├── MsalThrottledServiceException.xml │ ├── MsalThrottledUiRequiredException.xml │ ├── MsalUiRequiredException.xml │ ├── OsCapabilitiesExtensions.xml │ ├── Prompt.xml │ ├── PublicClientApplication.xml │ ├── PublicClientApplicationBuilder.xml │ ├── PublicClientApplicationExtensions.xml │ ├── PublicClientApplicationOptions.xml │ ├── RegionDetails.xml │ ├── SystemWebViewOptions.xml │ ├── TelemetryAudienceType.xml │ ├── TenantProfile.xml │ ├── TokenCache.xml │ ├── TokenCacheCallback.xml │ ├── TokenCacheExtensions.xml │ ├── TokenCacheNotificationArgs.xml │ ├── TokenSource.xml │ ├── TraceTelemetryConfig.xml │ ├── UiRequiredExceptionClassification.xml │ ├── UserAssertion.xml │ ├── WindowsBrokerOptions.xml │ └── WwwAuthenticateParameters.xml │ ├── Microsoft.IdentityModel.JsonWebTokens │ ├── JsonClaimValueTypes.xml │ ├── JsonWebToken.xml │ ├── JsonWebTokenHandler.xml │ ├── JwtConstants.xml │ ├── JwtHeaderParameterNames.xml │ ├── JwtRegisteredClaimNames.xml │ └── JwtTokenUtilities.xml │ ├── PackageInformation │ └── msal-dotnet-latest.json │ ├── _filter.xml │ ├── ns-.xml │ ├── ns-AspNetCore.xml │ ├── ns-Microsoft.Identity.Abstractions.xml │ ├── ns-Microsoft.Identity.Client.Advanced.xml │ ├── ns-Microsoft.Identity.Client.AppConfig.xml │ ├── ns-Microsoft.Identity.Client.AuthScheme.PoP.xml │ ├── ns-Microsoft.Identity.Client.AuthScheme.xml │ ├── ns-Microsoft.Identity.Client.Broker.xml │ ├── ns-Microsoft.Identity.Client.Cache.xml │ ├── ns-Microsoft.Identity.Client.Desktop.xml │ ├── ns-Microsoft.Identity.Client.Extensibility.xml │ ├── ns-Microsoft.Identity.Client.Kerberos.xml │ ├── ns-Microsoft.Identity.Client.ManagedIdentity.xml │ ├── ns-Microsoft.Identity.Client.Platforms.Features.DesktopOs.Kerberos.xml │ ├── ns-Microsoft.Identity.Client.RP.xml │ ├── ns-Microsoft.Identity.Client.Region.xml │ ├── ns-Microsoft.Identity.Client.SSHCertificates.xml │ ├── ns-Microsoft.Identity.Client.TelemetryCore.TelemetryClient.xml │ ├── ns-Microsoft.Identity.Client.Utils.Windows.xml │ ├── ns-Microsoft.Identity.Client.Utils.xml │ ├── ns-Microsoft.Identity.Client.xml │ ├── ns-Microsoft.Identity.Web.Experimental.xml │ ├── ns-Microsoft.Identity.Web.Extensibility.xml │ ├── ns-Microsoft.Identity.Web.Internal.xml │ ├── ns-Microsoft.Identity.Web.OWIN.xml │ ├── ns-Microsoft.Identity.Web.Resource.xml │ ├── ns-Microsoft.Identity.Web.TestOnly.xml │ ├── ns-Microsoft.Identity.Web.TokenCacheProviders.Distributed.xml │ ├── ns-Microsoft.Identity.Web.TokenCacheProviders.InMemory.xml │ ├── ns-Microsoft.Identity.Web.TokenCacheProviders.Session.xml │ ├── ns-Microsoft.Identity.Web.TokenCacheProviders.xml │ ├── ns-Microsoft.Identity.Web.UI.Areas.MicrosoftIdentity.Controllers.xml │ ├── ns-Microsoft.Identity.Web.UI.Areas.MicrosoftIdentity.Pages.Account.xml │ ├── ns-Microsoft.Identity.Web.UI.xml │ ├── ns-Microsoft.Identity.Web.xml │ ├── ns-Microsoft.IdentityModel.Abstractions.xml │ ├── ns-Microsoft.IdentityModel.JsonWebTokens.xml │ ├── ns-Microsoft.IdentityModel.KeyVaultExtensions.xml │ ├── ns-Microsoft.IdentityModel.Logging.xml │ ├── ns-Microsoft.IdentityModel.LoggingExtensions.xml │ ├── ns-Microsoft.IdentityModel.ManagedKeyVaultSecurityKey.xml │ ├── ns-Microsoft.IdentityModel.Protocols.Configuration.xml │ ├── ns-Microsoft.IdentityModel.Protocols.OpenIdConnect.Configuration.xml │ ├── ns-Microsoft.IdentityModel.Protocols.OpenIdConnect.xml │ ├── ns-Microsoft.IdentityModel.Protocols.SignedHttpRequest.xml │ ├── ns-Microsoft.IdentityModel.Protocols.WsFederation.xml │ ├── ns-Microsoft.IdentityModel.Protocols.xml │ ├── ns-Microsoft.IdentityModel.TestExtensions.xml │ ├── ns-Microsoft.IdentityModel.Tokens.Configuration.xml │ ├── ns-Microsoft.IdentityModel.Tokens.Saml.xml │ ├── ns-Microsoft.IdentityModel.Tokens.Saml2.xml │ ├── ns-Microsoft.IdentityModel.Tokens.xml │ ├── ns-Microsoft.IdentityModel.Validators.xml │ ├── ns-Microsoft.IdentityModel.Xml.xml │ └── ns-System.IdentityModel.Tokens.Jwt.xml └── msal-dotnet-articles ├── TOC.yml ├── acquiring-tokens ├── acquire-token-silently.md ├── acquiretokensilentasync-api.md ├── clear-token-cache.md ├── desktop-mobile │ ├── acquiring-tokens-interactively.md │ ├── adfs-support.md │ ├── device-code-flow.md │ ├── integrated-windows-authentication.md │ ├── linux-dotnet-sdk-wsl.md │ ├── linux-dotnet-sdk.md │ ├── mobile-applications.md │ ├── social-identities.md │ ├── username-password-authentication.md │ └── wam.md ├── overview.md ├── using-web-browsers.md └── web-apps-apis │ ├── authorization-codes.md │ ├── client-credential-flows.md │ ├── confidential-client-assertions.md │ ├── on-behalf-of-flow.md │ └── workload-identity-federation.md ├── advanced ├── android-ios-emulator.md ├── backup-authentication-system.md ├── clearing-token-cache.md ├── client-and-server-throttling.md ├── client-credential-multi-tenant.md ├── custom-authority-aliases.md ├── exceptions │ ├── broker.md │ ├── device-authentication-errors.md │ ├── index.md │ ├── msal-error-handling.md │ ├── msal-logging.md │ ├── retry-policy.md │ ├── tls-issues.md │ ├── understanding-msaluirequiredexception.md │ ├── understanding-statemismatcherror.md │ ├── unity.md │ └── wam-errors.md ├── experimental-features.md ├── extensibility-points.md ├── extract-authentication-parameters.md ├── high-availability.md ├── httpclient.md ├── managed-identity.md ├── monitoring.md ├── multicloud-support-instance-awareness.md ├── performance-testing.md ├── powershell-support.md ├── proof-of-possession-tokens.md ├── spa-authorization-code.md ├── ssh-certificates.md ├── testing-apps-using-msal.md ├── using-in-azure-functions.md └── webview2.md ├── breadcrumb └── toc.yml ├── docfx.json ├── file-content ├── example_logging_no_pii.txt └── example_logging_pii.txt ├── getting-started ├── best-practices.md ├── choosing-msal-dotnet.md ├── initializing-client-applications.md ├── instantiate-confidential-client-config-options.md ├── instantiate-public-client-config-options.md └── scenarios.md ├── how-to ├── build-apps-on-linux-ubuntu.md ├── cache-options.md ├── create-config-for-mam-conditional-access.md ├── custom-token-cache-in-public-client-applications.md ├── default-reply-uri.md ├── differences-adal-msal-net.md ├── get-tenant-profiles.md ├── install-nuget-custom-source.md ├── migrate-android-broker.md ├── migrate-confidential-client.md ├── migrate-ios-broker.md ├── migrate-public-client.md ├── msal-net-migration.md ├── override-target-framework.md ├── overriding-authority.md ├── protect-ios-android-mam-intune.md ├── synchronous-programming.md └── token-cache-serialization.md ├── includes ├── adal-migration-note.md ├── error-handling-claims-challenges.md ├── error-handling-introduction.md ├── error-handling-retries.md ├── importance-of-logging.md ├── msal-net-adoption-steps-confidential-clients.md └── msal-net-adoption-steps-public-clients.md ├── index.md ├── media ├── a-icon.png ├── access-token-fiddler.png ├── aspnet-core-project-templates.png ├── auth-parameters-diagram.png ├── authenticationresult-graph.png ├── azure-ad-b2c-appsettings.png ├── azure-ad-b2c-controller.png ├── azure-ad-calling-api.png ├── azure-ad-certificates.png ├── azure-ad-client-type.png ├── certificate-icon.png ├── complex-web-app-topology.png ├── configureservices-startup.png ├── console-app-topology.png ├── daemon-app-topology.png ├── daemon-certificate-topology.png ├── daemon-icon.png ├── desktop-web-topology.png ├── device-code-flow-topology.png ├── devicecoderesult-class.png ├── errorList.png ├── groupmanager-topology.png ├── iconfidentialclientapplication-interface.png ├── idweb-msal.png ├── ipublicclientapplication-interface.png ├── iwa-console-topology.png ├── latency-diagram.png ├── linux │ ├── dotnet-msal-wsl.gif │ └── linux-entra-login.gif ├── loggerTypes.png ├── msal-compare-msaldotnet-and-adaldotnet │ └── differences.png ├── msal-exceptions.png ├── msal-folder-content.png ├── msal-logging │ ├── fiddler-exempt.png │ └── msft-sts-fiddler.png ├── msal-net-logging │ └── otel.png ├── msal-net-migration │ ├── confidential-client-application.png │ └── decision-diagram.png ├── msal-net-token-cache-serialization │ ├── class-diagram.png │ └── topology.png ├── msal-net-use-brokers-with-xamarin-apps │ └── portal-01-ios-platform-settings.png ├── msal-net-uwp-considerations │ ├── topology-native-uwp.png │ └── topology-xamarin-native.png ├── msal-net-web-browsers │ ├── embedded-webview.png │ └── system-browser.png ├── msal-serializers.png ├── msal-templates-support.png ├── nativeinterop-library.png ├── net-api-api.png ├── net-app-api.png ├── net-daemon-api.png ├── net-desktop-api.png ├── net-iot-api.png ├── net-mobile-api.png ├── net-oauth.png ├── obo-flow-topology.png ├── on-behalf-flow.png ├── p-icon.png ├── proof-of-possession-tokens │ └── example-www-authenticate-headers.png ├── ropc-enable-azure-portal.png ├── user-icon.png ├── user-sync-app-topology.png ├── uwp-app-topology.png ├── wam │ ├── wam-demo.gif │ ├── wam-per-tenant.gif │ ├── wsl1.png │ ├── wsl2.png │ ├── wsl3.png │ ├── wsl4.png │ ├── wsl5.png │ └── wsl6.png ├── web-api-icon.png ├── web-app-icon.png ├── web-app-topology.png ├── wpf-app-topology.png └── xamarin-forms-topology.png ├── microsoft-identity-web ├── getting-started │ └── scenarios.md └── index.md └── resources ├── handling-pii.md ├── known-issues.md ├── region-discovery-troubleshooting.md ├── semantic-versioning-api-change-management.md ├── telemetry-overview.md └── troubleshooting.md /.gitattributes: -------------------------------------------------------------------------------- 1 | # Set the default behavior, in case people don't have core.autocrlf set. 2 | * text=auto 3 | 4 | # Explicitly declare text files you want to always be normalized and converted 5 | # to native line endings on checkout. 6 | *.c text 7 | *.h text 8 | 9 | # Declare files that will always have CRLF line endings on checkout. 10 | *.sln text eol=crlf 11 | 12 | # Denote all files that are truly binary and should not be modified. 13 | *.png binary 14 | *.jpg binary -------------------------------------------------------------------------------- /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | # Conceptual and API content needs the review of the engineering team. 2 | msal-dotnet-articles/* @MicrosoftDocs/identity-sdk-cca-engineering-team 3 | 4 | # API documentation does not have code owners, but that is OK. 5 | # Anyone can create a PR to the `main` branch and we will review 6 | # the changes on the one-off basis. 7 | dotnet/ 8 | -------------------------------------------------------------------------------- /.github/policies/auto-merge.yml: -------------------------------------------------------------------------------- 1 | id: 2 | name: GitOps.PullRequestIssueManagement 3 | description: GitOps.PullRequestIssueManagement primitive 4 | owner: 5 | resource: repository 6 | disabled: false 7 | where: 8 | configuration: 9 | resourceManagementConfiguration: 10 | eventResponderTasks: 11 | - description: Approve and auto-squash-merge bot PRs to main labeled 'auto-merge' 12 | triggerOnOwnActions: true 13 | if: 14 | - payloadType: Pull_Request 15 | - labelAdded: 16 | label: ':octocat: auto-merge' 17 | - targetsBranch: 18 | branch: main 19 | - isActivitySender: 20 | user: microsoft-github-policy-service[bot] 21 | then: 22 | - enableAutoMerge: 23 | mergeMethod: Squash 24 | - approvePullRequest: 25 | comment: "Approved; this PR will merge when all status checks pass." 26 | 27 | - description: Auto-merge policy service bot PRs to live labeled 'auto-merge' 28 | triggerOnOwnActions: true 29 | if: 30 | - payloadType: Pull_Request 31 | - labelAdded: 32 | label: ':octocat: auto-merge' 33 | - targetsBranch: 34 | branch: live 35 | - isActivitySender: 36 | user: microsoft-github-policy-service[bot] 37 | then: 38 | - enableAutoMerge: 39 | mergeMethod: Merge 40 | 41 | - description: Don't auto-merge PRs with 'auto-merge' label removed 42 | if: 43 | - payloadType: Pull_Request 44 | - labelRemoved: 45 | label: ':octocat: auto-merge' 46 | then: 47 | - disableAutoMerge -------------------------------------------------------------------------------- /.github/policies/label-new-issues.yml: -------------------------------------------------------------------------------- 1 | id: 2 | name: GitOps.PullRequestIssueManagement 3 | description: GitOps.PullRequestIssueManagement primitive 4 | owner: 5 | resource: repository 6 | disabled: false 7 | where: 8 | configuration: 9 | resourceManagementConfiguration: 10 | eventResponderTasks: 11 | - description: Add untriaged label to new issues 12 | if: 13 | - payloadType: Issues 14 | - isAction: 15 | action: Opened 16 | then: 17 | - addLabel: 18 | label: untriaged 19 | -------------------------------------------------------------------------------- /.github/policies/scheduled-prod-sync.yml: -------------------------------------------------------------------------------- 1 | name: GitOps.PullRequestIssueManagement - Scheduled PRs 2 | description: Creates pull requests on a schedule 3 | resource: repository 4 | 5 | where: 6 | configuration: 7 | resourceManagementConfiguration: 8 | scheduledSearches: 9 | - description: Push to live branch (scheduled 11AM PT publish) 10 | frequencies: 11 | - daily: 12 | time: 18:00 13 | filters: [] 14 | actions: 15 | - createPullRequest: 16 | head: main 17 | base: live 18 | title: Merge main into live 19 | body: Automated merge of the main branch into live. 20 | 21 | - description: Push to live branch (scheduled 7PM PT publish) 22 | frequencies: 23 | - daily: 24 | time: 2:00 25 | filters: [] 26 | actions: 27 | - createPullRequest: 28 | head: main 29 | base: live 30 | title: Merge main into live 31 | body: Automated merge of the main branch into live. 32 | 33 | - description: Push to live branch (scheduled 3AM PT publish) 34 | frequencies: 35 | - daily: 36 | time: 10:00 37 | filters: [] 38 | actions: 39 | - createPullRequest: 40 | head: main 41 | base: live 42 | title: Merge main into live 43 | body: Automated merge of the main branch into live. 44 | -------------------------------------------------------------------------------- /.github/policies/scheduled-stage-sync.yml: -------------------------------------------------------------------------------- 1 | name: GitOps.PullRequestIssueManagement - Scheduled PRs 2 | description: Creates pull requests on a schedule 3 | resource: repository 4 | 5 | where: 6 | configuration: 7 | resourceManagementConfiguration: 8 | scheduledSearches: 9 | - description: Push to main branch (scheduled 10AM PT publish) 10 | frequencies: 11 | - daily: 12 | time: 17:00 13 | filters: [] 14 | actions: 15 | - createPullRequest: 16 | head: smoke-test 17 | base: main 18 | title: Merge smoke-test into main 19 | body: Automated merge of the smoke-test branch into main. 20 | 21 | - description: Push to main branch (scheduled 6PM PT publish) 22 | frequencies: 23 | - daily: 24 | time: 1:00 25 | filters: [] 26 | actions: 27 | - createPullRequest: 28 | head: smoke-test 29 | base: main 30 | title: Merge smoke-test into main 31 | body: Automated merge of the smoke-test branch into main. 32 | 33 | - description: Push to main branch (scheduled 2AM PT publish) 34 | frequencies: 35 | - daily: 36 | time: 9:00 37 | filters: [] 38 | actions: 39 | - createPullRequest: 40 | head: smoke-test 41 | base: main 42 | title: Merge smoke-test into main 43 | body: Automated merge of the smoke-test branch into main. 44 | -------------------------------------------------------------------------------- /.github/policies/stale-issues.yml: -------------------------------------------------------------------------------- 1 | name: Stale issues 2 | description: Close needs-more-info issues that haven't had a response in 14 days 3 | resource: repository 4 | where: 5 | configuration: 6 | resourceManagementConfiguration: 7 | scheduledSearches: 8 | - frequencies: 9 | - daily: 10 | time: 12:00 11 | filters: 12 | - isIssue 13 | - isOpen 14 | - hasLabel: 15 | label: needs-more-info 16 | - noActivitySince: 17 | days: 14 18 | actions: 19 | - addReply: 20 | reply: This issue has been automatically closed due to no response from the original author. Feel free to reopen it if you have more information that can help us investigate the issue further. 21 | - closeIssue -------------------------------------------------------------------------------- /.github/policies/tag-automatic-pr.yml: -------------------------------------------------------------------------------- 1 | id: 2 | name: GitOps.PullRequestIssueManagement 3 | description: GitOps.PullRequestIssueManagement primitive 4 | owner: 5 | resource: repository 6 | disabled: false 7 | where: 8 | configuration: 9 | resourceManagementConfiguration: 10 | eventResponderTasks: 11 | - description: Sync API docs to staging 12 | triggerOnOwnActions: true 13 | if: 14 | - payloadType: Pull_Request 15 | - isAction: 16 | action: Opened 17 | - isActivitySender: 18 | user: microsoft-github-policy-service[bot] 19 | - titleContains: 20 | pattern: Merge smoke-test into main 21 | isRegex: False 22 | then: 23 | - addLabel: 24 | label: ':octocat: auto-merge' 25 | 26 | - description: Sync staging to production 27 | triggerOnOwnActions: true 28 | if: 29 | - payloadType: Pull_Request 30 | - isAction: 31 | action: Opened 32 | - isActivitySender: 33 | user: microsoft-github-policy-service[bot] 34 | - titleContains: 35 | pattern: Merge main into live 36 | isRegex: False 37 | then: 38 | - addLabel: 39 | label: ':octocat: auto-merge' -------------------------------------------------------------------------------- /.github/workflows/linkchecker.yml: -------------------------------------------------------------------------------- 1 | name: Validate existing links 2 | 3 | on: 4 | push: 5 | repository_dispatch: 6 | workflow_dispatch: 7 | schedule: 8 | - cron: "00 18 * * *" 9 | 10 | jobs: 11 | linkChecker: 12 | permissions: 13 | contents: write 14 | issues: write 15 | runs-on: ubuntu-latest 16 | steps: 17 | - uses: actions/checkout@v3 18 | 19 | - name: Link Checker 20 | id: lychee 21 | uses: lycheeverse/lychee-action@master 22 | env: 23 | GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} 24 | with: 25 | args: --accept=200,429,403,502,503 --verbose --no-progress './**/*.md' 26 | fail: true 27 | 28 | - name: Create Issue From File 29 | if: always() && env.lychee_exit_code != 0 && github.event_name != 'pull_request' 30 | uses: peter-evans/create-issue-from-file@main 31 | with: 32 | title: Link Checker Report 33 | content-filepath: ./lychee/out.md 34 | labels: report, automated issue 35 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | log/ 2 | obj/ 3 | _site/ 4 | .optemp/ 5 | _themes*/ 6 | **/.vs/ 7 | 8 | .openpublishing.buildcore.ps1 9 | 10 | # Make sure we remove auto-generated content if any. 11 | dotnet/api/*.yml 12 | dotnet/api/microsoft-authentication-library-dotnet/*.yml 13 | 14 | # User-specific files 15 | *.suo 16 | *.user 17 | *.userosscache 18 | *.sln.docstates 19 | 20 | # Vs Code 21 | *.vscode -------------------------------------------------------------------------------- /.lycheeignore: -------------------------------------------------------------------------------- 1 | https://aka.ms/msal/estsr/guidance 2 | xref:.* 3 | https://go.microsoft.com/fwlink/\?linkid=2083908 4 | https://endpoint.microsoft.com.* 5 | https://portal.azure.com.* 6 | https://account.microsoft.com.* 7 | https://azure.microsoft.com/overview/azure-stack.* 8 | https://azure.microsoft.com/products/kubernetes-service.* -------------------------------------------------------------------------------- /.openpublishing.redirection.json: -------------------------------------------------------------------------------- 1 | { 2 | "redirections": [ 3 | { 4 | "source_path": "msal-dotnet-articles/resources/release-cadence.md", 5 | "redirect_url": "/entra/msal/dotnet#releases" 6 | }, 7 | { 8 | "source_path": "msal-dotnet-articles/acquiring-tokens/desktop-mobile/adfs.md", 9 | "redirect_url": "/entra/msal/dotnet/acquiring-tokens/desktop-mobile/adfs-support" 10 | }, 11 | { 12 | "source_path": "msal-dotnet-articles/advanced/subject-name-and-issuer-authentication.md", 13 | "redirect_url": "/entra/msal/dotnet/" 14 | }, 15 | { 16 | "source_path": "msal-dotnet-articles/contribute/bugs-and-feature-requests.md", 17 | "redirect_url": "https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/CONTRIBUTING.md" 18 | }, 19 | { 20 | "source_path": "msal-dotnet-articles/contribute/build-and-test.md", 21 | "redirect_url": "https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/CONTRIBUTING.md" 22 | }, 23 | { 24 | "source_path": "msal-dotnet-articles/contribute/overview.md", 25 | "redirect_url": "https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/CONTRIBUTING.md" 26 | }, 27 | { 28 | "source_path": "msal-dotnet-articles/contribute/prerequisites-to-build.md", 29 | "redirect_url": "https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/main/CONTRIBUTING.md" 30 | }, 31 | { 32 | "source_path": "msal-dotnet-articles/acquiring-tokens/msal-net-client-assertions.md", 33 | "redirect_url": "/entra/msal/dotnet/acquiring-tokens/web-apps-apis/confidential-client-assertions" 34 | }, 35 | { 36 | "source_path": "msal-dotnet-articles/acquiring-tokens/desktop-mobile/dotnet-core.md", 37 | "redirect_url": "/entra/msal/dotnet/acquiring-tokens/using-web-browsers" 38 | }, 39 | { 40 | "source_path": "msal-dotnet-articles/acquiring-tokens/user-gets-consent-for-multiple-resources.md", 41 | "redirect_url": "/entra/msal/dotnet/acquiring-tokens/desktop-mobile/acquiring-tokens-interactively" 42 | }, 43 | { 44 | "source_path": "dotnet/api/microsoft-authentication-library-dotnet/ConfidentialClient.yml", 45 | "redirect_url": "/dotnet/api/microsoft-authentication-library-dotnet/higher-levellibraries" 46 | }, 47 | { 48 | "source_path": "dotnet/api/overview/msal-public-client/index.md", 49 | "redirect_url": "/dotnet/api/overview/core-msal-net-libraries/" 50 | }, 51 | { 52 | "source_path": "msal-dotnet-articles/resources/ios12-security-advisory.md", 53 | "redirect_url": "/entra/msal/dotnet/" 54 | }, 55 | { 56 | "source_path": "msal-dotnet-articles/acquiring-tokens/desktop-mobile/uwp.md", 57 | "redirect_url": "/entra/msal/dotnet/" 58 | }, 59 | { 60 | "source_path": "msal-dotnet-articles/acquiring-tokens/desktop-mobile/xamarin.md", 61 | "redirect_url": "/entra/msal/dotnet/acquiring-tokens/desktop-mobile/mobile-applications" 62 | } 63 | ] 64 | } 65 | -------------------------------------------------------------------------------- /LICENSE-CODE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | Copyright (c) Microsoft Corporation 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 5 | associated documentation files (the "Software"), to deal in the Software without restriction, 6 | including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 7 | and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 8 | subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial 11 | portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT 14 | NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 15 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 16 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 17 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Microsoft Authentication Library for .NET 2 | 3 | [![Validate existing links](https://github.com/MicrosoftDocs/microsoft-authentication-library-dotnet/actions/workflows/linkchecker.yml/badge.svg)](https://github.com/MicrosoftDocs/microsoft-authentication-library-dotnet/actions/workflows/linkchecker.yml) 4 | 5 | This is the **documentation repository** for Microsoft Authentication Library (MSAL) for .NET. 6 | 7 | | Resource | Location | 8 | |:-----------------------------|:-----------| 9 | | ✅ **SDK Repository** | [`AzureAD/microsoft-authentication-library-for-dotnet`](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) | 10 | | ✅ **SDK Package** | [`Microsoft.Identity.Client`](https://www.nuget.org/packages/Microsoft.Identity.Client/) | 11 | | ✅ **SDK Documentation** | [MSAL.NET on Microsoft Learn](https://learn.microsoft.com/entra/msal/dotnet/) | 12 | 13 | ## Contributions 14 | 15 | Contributions to our documentation are welcome. Make sure to familiarize yourself with the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/) and the [Contributor Guide](https://learn.microsoft.com/contribute/) before making any changes. 16 | 17 | If you would like to author an entirely new document (e.g., for a new scenario), make sure to [open an issue](https://github.com/MicrosoftDocs/microsoft-authentication-library-dotnet/issues) first. This will allow the engineering team to discuss the proposed changes and ensure that it won't be overwritten by future changes. 18 | 19 | ## API Documentation 20 | 21 | **Do not** modify any XML files in the `dotnet/xml` folder - those are generated automatically from the library source code and any changes will be automatically overwritten the next time the documentation runs. 22 | 23 | To make changes to any API docs you will need to open a pull request in the [`AzureAD/microsoft-authentication-library-for-dotnet`](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) repository and amend code comments. 24 | 25 | ## Microsoft Open Source Code of Conduct 26 | 27 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 28 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /ThirdPartyNotices: -------------------------------------------------------------------------------- 1 | ##Legal Notices 2 | Microsoft and any contributors grant you a license to the Microsoft documentation and other content 3 | in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), 4 | see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the [MIT License](https://opensource.org/licenses/MIT), see the 5 | [LICENSE-CODE](LICENSE-CODE) file. 6 | 7 | Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation 8 | may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. 9 | The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. 10 | Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653. 11 | 12 | Privacy information can be found at https://privacy.microsoft.com/en-us/ 13 | 14 | Microsoft and any contributors reserve all others rights, whether under their respective copyrights, patents, 15 | or trademarks, whether by implication, estoppel or otherwise. -------------------------------------------------------------------------------- /dotnet/api/overview/core-msal-net-libraries/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Core MSAL.NET Libraries 3 | description: "Core MSAL.NET libraries enable developers to build token acquisition flows into their applications both on the client (e.g., desktop, mobile, and web) as well as on the service sides (e.g., web APIs)." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Core MSAL.NET Libraries 17 | 18 | Core MSAL.NET libraries enable developers to build token acquisition flows into their applications both on the client (e.g., desktop, mobile, and web) as well as on the service sides (e.g., web APIs). 19 | 20 | ## Public client applications 21 | 22 | Public client applications are applications that run on devices, desktop computers, or in a web browser, that cannot be trusted to securely store secrets required for authentication. These applications can only access a web API or service on behalf of the authenticating user and cannot impersonate other users or groups. The reason they can't store a secret is mainly due to the fact that client applications can be reverse-engineered and secrets extracted. The concept is following the definitions included in [RFC6749 Section 2.1 - Client Types](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). 23 | 24 | MSAL.NET enables the development of public client applications with the help of as well as included configuration and functions. 25 | 26 | ## Confidential client applications 27 | 28 | Confidential client applications are apps that run on servers, such as web apps, web API apps, or service/daemon apps. Their internals are considered difficult to access, and therefore they can keep an application secret secure and out of sight of its users. Confidential clients can hold configuration-time secrets. The concept, just like public client applications, also is following the definitions included in [RFC6749 Section 2.1 - Client Types](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). 29 | 30 | MSAL.NET enables the development of confidential client applications with the help of as well as included configuration and functions. 31 | 32 | ## Get started 33 | 34 | Refer to [Token acquisition](/entra/msal/dotnet/acquiring-tokens/overview) for more details. 35 | 36 | - [`PublicClientApplication`](xref:Microsoft.Identity.Client.PublicClientApplication) 37 | - [`ConfidentialClientApplication`](xref:Microsoft.Identity.Client.ConfidentialClientApplication) 38 | - [`ManagedIdentityApplication`](xref:Microsoft.Identity.Client.ManagedIdentityApplication) 39 | 40 | ## Resources 41 | 42 | - [Public client and confidential client applications](/azure/active-directory/develop/msal-client-applications) 43 | - [RFC6749 - The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749) 44 | -------------------------------------------------------------------------------- /dotnet/api/overview/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: MSAL.NET API Reference Documentation 3 | description: "The full overview of the MSAL.NET API surface." 4 | author: Dickson-Mwendia 5 | manager: CelesteDG 6 | ms.author: dmwendia 7 | ms.date: 12/13/2023 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: devx-track-csharp, aaddev, devx-track-dotnet 13 | #Customer intent: 14 | --- 15 | 16 | # MSAL.NET API Reference Documentation 17 | 18 | This section covers the complete API reference documentation for MSAL.NET. It's a reflection of the **latest version** of all MSAL.NET component packages hosted on NuGet. 19 | 20 | Check out the [scenario overview](/entra/msal/dotnet/getting-started/scenarios) to learn more about the workloads where MSAL.NET can be useful. To find out which library you need to use for your scenario, refer to [Choosing a version of MSAL.NET](/entra/msal/dotnet/getting-started/choosing-msal-dotnet). 21 | 22 | ## Packages 23 | 24 | ### Core MSAL.NET Libraries 25 | 26 | [![NuGet badge for Microsoft.Identity.Client](https://img.shields.io/nuget/v/Microsoft.Identity.Client.svg?style=flat-square&label=Microsoft.Identity.Client&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client/) 27 | 28 | [![NuGet badge for Microsoft.Identity.Client.Broker](https://img.shields.io/nuget/v/Microsoft.Identity.Client.Broker.svg?style=flat-square&label=Microsoft.Identity.Client.Broker&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client.Broker/) 29 | 30 | [![NuGet badget for Microsoft.Identity.Client.Desktop](https://img.shields.io/nuget/v/Microsoft.Identity.Client.Desktop.svg?style=flat-square&label=Microsoft.Identity.Client.Desktop&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client.Desktop/) 31 | 32 | [![NuGet badge for Microsoft.Identity.Client.Extensions.Msal](https://img.shields.io/nuget/v/Microsoft.Identity.Client.Extensions.Msal.svg?style=flat-square&label=Microsoft.Identity.Client.Extensions.Msal&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Client.Extensions.Msal/) 33 | 34 | ### Higher-Level Libraries 35 | 36 | [![NuGet badge for Microsoft.Identity.Web](https://img.shields.io/nuget/v/Microsoft.Identity.Web.svg?style=flat-square&label=Microsoft.Identity.Web&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Web/) 37 | 38 | [![NuGet badge for Microsoft.Identity.Web.UI](https://img.shields.io/nuget/v/Microsoft.Identity.Web.UI.svg?style=flat-square&label=Microsoft.Identity.Web.UI&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Web.UI/) 39 | 40 | [![NuGetMicrosoft.Identity.Web.MicrosoftGraph](https://img.shields.io/nuget/v/Microsoft.Identity.Web.MicrosoftGraph.svg?style=flat-square&label=Microsoft.Identity.Web.MicrosoftGraph&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Web.MicrosoftGraph/) 41 | 42 | [![NuGet badge for Microsoft.Identity.Web.MicrosoftGraphBeta](https://img.shields.io/nuget/v/Microsoft.Identity.Web.MicrosoftGraphBeta.svg?style=flat-square&label=Microsoft.Identity.Web.MicrosoftGraphBeta&colorB=00b200)](https://www.nuget.org/packages/Microsoft.Identity.Web.MicrosoftGraphBeta/) 43 | -------------------------------------------------------------------------------- /dotnet/docfx.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "markdownEngineName": "markdig", 4 | "content": [ 5 | { 6 | "files": [ 7 | "**/*.md", 8 | "**/*.yml" 9 | ], 10 | "exclude": [ 11 | "**/obj/**", 12 | "**/includes/**", 13 | "**/_themes/**", 14 | "README.md", 15 | "LICENSE", 16 | "LICENSE-CODE", 17 | "ThirdPartyNotices" 18 | ] 19 | }, 20 | { 21 | "files": [ 22 | "**/*.md" 23 | ], 24 | "exclude": [], 25 | "src": "api/overview/msal-public-client", 26 | "dest": "api/overview/msal-public-client" 27 | } 28 | ], 29 | "resource": [ 30 | { 31 | "files": [ 32 | "**/*.png", 33 | "**/*.jpg", 34 | "**/*.svg", 35 | "**/*.gif", 36 | "**/*.bmp" 37 | ], 38 | "exclude": [ 39 | "**/obj/**", 40 | "**/includes/**" 41 | ] 42 | } 43 | ], 44 | "globalMetadata": { 45 | "uhfHeaderId": "MSDocsHeader-Entra", 46 | "feedback_system": "Standard", 47 | "feedback_github_repo": "MicrosoftDocs/microsoft-authentication-library-dotnet", 48 | "feedback_product_url": "https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues", 49 | "apiPlatform": "dotnet", 50 | "breadcrumb_path": "/dotnet/msal-dotnet-ref-breadcrumb/toc.json" 51 | }, 52 | "fileMetadata": { 53 | "author": { 54 | "api/**.yml": "dotnet-bot", 55 | "api/**.md": "dotnet-bot" 56 | }, 57 | "ms.author": { 58 | "api/**.yml": "dmwendia", 59 | "api/**.md": "dmwendia" 60 | }, 61 | "ms.service": { 62 | "api/**.yml": "msal", 63 | "api/**.md": "msal" 64 | }, 65 | "titleSuffix": { 66 | "api/**.md": "Microsoft Authentication Library for .NET", 67 | "api/**.yml": "Microsoft Authentication Library for .NET" 68 | }, 69 | "ms.topic": { 70 | "api/**.md": "conceptual", 71 | "api/**.yml": "reference" 72 | }, 73 | "open_to_public_contributors": { 74 | "api/**.md": false 75 | } 76 | }, 77 | "template": [], 78 | "isCanonicalUrlWithMoniker": true, 79 | "dest": "_site", 80 | "lruSize": 0, 81 | "xrefService": [ 82 | "https://xref.docs.microsoft.com/query?uid={uid}" 83 | ] 84 | } 85 | } 86 | -------------------------------------------------------------------------------- /dotnet/docs-ref-toc/toc.yml: -------------------------------------------------------------------------------- 1 | - name: Reference 2 | href: ~/api/overview/index.md 3 | landingPageType: Root 4 | expanded: false 5 | items: 6 | - name: Core MSAL.NET Libraries 7 | href: ~/api/overview/msal-public-client/index.md 8 | landingPageType: Service 9 | children: 10 | - Microsoft.Identity.Client 11 | - Microsoft.Identity.Client.Advanced 12 | - Microsoft.Identity.Client.AppConfig 13 | - Microsoft.Identity.Client.AuthScheme.PoP 14 | - Microsoft.Identity.Client.Broker 15 | - Microsoft.Identity.Client.Cache 16 | - Microsoft.Identity.Client.Desktop 17 | - Microsoft.Identity.Client.Extensibility 18 | - Microsoft.Identity.Client.Kerberos 19 | - Microsoft.Identity.Client.ManagedIdentity 20 | - Microsoft.Identity.Client.Platforms.Features.DesktopOs.Kerberos 21 | - Microsoft.Identity.Client.Region 22 | - Microsoft.Identity.Client.SSHCertificates 23 | - Microsoft.Identity.Client.TelemetryCore.TelemetryClient 24 | - Microsoft.Identity.Client.Utils.Windows 25 | - name: Higher-Level Libraries 26 | landingPageType: Service 27 | children: 28 | - AspNetCore 29 | - Microsoft.Identity.Abstractions 30 | - Microsoft.Identity.Web 31 | - Microsoft.Identity.Web.Internal 32 | - Microsoft.Identity.Web.Resource 33 | - Microsoft.Identity.Web.TokenCacheProviders 34 | - Microsoft.Identity.Web.TokenCacheProviders.Distributed 35 | - Microsoft.Identity.Web.TokenCacheProviders.InMemory 36 | - Microsoft.Identity.Web.TokenCacheProviders.Session 37 | - Microsoft.Identity.Web.UI.Areas.MicrosoftIdentity.Controllers 38 | - Microsoft.Identity.Web.UI.Areas.MicrosoftIdentity.Pages.Account 39 | - Microsoft.Identity.Web.UI 40 | - Microsoft.Identity.Web.OWIN 41 | - Microsoft.IdentityModel.Abstractions 42 | - Microsoft.IdentityModel.JsonWebTokens 43 | - Microsoft.IdentityModel.KeyVaultExtensions 44 | - Microsoft.IdentityModel.Logging 45 | - Microsoft.IdentityModel.LoggingExtensions 46 | - Microsoft.IdentityModel.ManagedKeyVaultSecurityKey 47 | - Microsoft.IdentityModel.Protocols 48 | - Microsoft.IdentityModel.Protocols.OpenIdConnect 49 | - Microsoft.IdentityModel.Protocols.OpenIdConnect.Configuration 50 | - Microsoft.IdentityModel.Protocols.SignedHttpRequest 51 | - Microsoft.IdentityModel.Protocols.WsFederation 52 | - Microsoft.IdentityModel.TestExtensions 53 | - Microsoft.IdentityModel.Tokens 54 | - Microsoft.IdentityModel.Tokens.Saml 55 | - Microsoft.IdentityModel.Tokens.Saml2 56 | - Microsoft.IdentityModel.Validators 57 | - Microsoft.IdentityModel.Xml 58 | - System.IdentityModel.Tokens.Jwt 59 | - Microsoft.IdentityModel.Protocols.Configuration 60 | - Microsoft.IdentityModel.Tokens.Configuration 61 | - name: Other 62 | landingPageType: Service 63 | children: 64 | - '**' -------------------------------------------------------------------------------- /dotnet/msal-dotnet-ref-breadcrumb/toc.yml: -------------------------------------------------------------------------------- 1 | - name: Microsoft Entra 2 | tocHref: /dotnet/ 3 | topicHref: /entra/index 4 | items: 5 | - name: MSAL 6 | tocHref: /dotnet/ 7 | topicHref: /entra/msal/index 8 | items: 9 | - name: .NET API browser 10 | tocHref: /dotnet/ 11 | topicHref: /dotnet/api/index 12 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client.RP/AcquireTokenForClientParameterBuilderForResourceProviders.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.70.0.0 10 | 4.70.1.0 11 | 4.70.2.0 12 | 4.71.0.0 13 | 4.71.1.0 14 | 4.74.0.0 15 | 16 | 17 | System.Object 18 | 19 | 20 | 21 | 22 | Resource Provider extensibility methods for AcquireTokenForClientParameterBuilder 23 | 24 | To be added. 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | Method 34 | 35 | Microsoft.Identity.Client 36 | 4.74.0.0 37 | 38 | 39 | Microsoft.Identity.Client.AcquireTokenForClientParameterBuilder 40 | 41 | 42 | 43 | 44 | 45 | 46 | The existing AcquireTokenForClientParameterBuilder instance. 47 | 48 | A Base64-encoded SHA-256 hash of the token (UTF-8). For example: 49 | Convert.ToBase64String(SHA256(Encoding.UTF8.GetBytes(accessToken))). 50 | 51 | 52 | Configures the SDK to not retrieve a token from the cache if it matches the SHA256 hash 53 | of the token configured. Similar to WithForceRefresh(bool) API, but instead of bypassing 54 | the cache for all tokens, the cache bypass only occurs for 1 token 55 | 56 | The builder to chain the .With methods. 57 | To be added. 58 | 59 | 60 | 61 | 62 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client/AcquireTokenByUsernameAndPasswordConfidentialParameterBuilder.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.64.0.0 10 | 4.64.1.0 11 | 4.65.0.0 12 | 4.66.0.0 13 | 4.66.1.0 14 | 4.66.2.0 15 | 4.67.0.0 16 | 4.67.1.0 17 | 4.67.2.0 18 | 4.68.0.0 19 | 4.69.1.0 20 | 4.70.0.0 21 | 4.70.1.0 22 | 4.70.2.0 23 | 4.71.0.0 24 | 4.71.1.0 25 | 4.74.0.0 26 | 27 | 28 | Microsoft.Identity.Client.AbstractConfidentialClientAcquireTokenParameterBuilder<Microsoft.Identity.Client.AcquireTokenByUsernameAndPasswordConfidentialParameterBuilder> 29 | 30 | Microsoft.Identity.Client.AcquireTokenByUsernameAndPasswordConfidentialParameterBuilder 31 | 32 | 33 | 34 | 35 | 36 | Parameter builder for the 37 | operation. See https://aka.ms/msal-net-up 38 | 39 | To be added. 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | Method 49 | 50 | Microsoft.Identity.Client 51 | 4.74.0.0 52 | 53 | 54 | System.Void 55 | 56 | 57 | 58 | To be added. 59 | To be added. 60 | 61 | 62 | 63 | 64 | 65 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client/ApplicationBase.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.51.0.0 10 | 4.52.0.0 11 | 4.53.0.0 12 | 4.54.0.0 13 | 4.54.1.0 14 | 4.55.0.0 15 | 4.56.0.0 16 | 4.57.0.0 17 | 4.58.0.0 18 | 4.58.1.0 19 | 4.59.0.0 20 | 4.60.0.0 21 | 4.60.1.0 22 | 4.60.2.0 23 | 4.60.3.0 24 | 4.61.0.0 25 | 4.61.1.0 26 | 4.61.3.0 27 | 4.62.0.0 28 | 4.63.0.0 29 | 4.64.0.0 30 | 4.64.1.0 31 | 4.65.0.0 32 | 4.66.0.0 33 | 4.66.1.0 34 | 4.66.2.0 35 | 4.67.0.0 36 | 4.67.1.0 37 | 4.67.2.0 38 | 4.68.0.0 39 | 4.69.1.0 40 | 4.70.0.0 41 | 4.70.1.0 42 | 4.70.2.0 43 | 4.71.0.0 44 | 4.71.1.0 45 | 4.74.0.0 46 | 47 | 48 | System.Object 49 | 50 | 51 | 52 | Microsoft.Identity.Client.IApplicationBase 53 | 54 | 55 | 56 | To be added. 57 | To be added. 58 | 59 | 60 | 61 | 62 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client/IApplicationBase.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.51.0.0 10 | 4.52.0.0 11 | 4.53.0.0 12 | 4.54.0.0 13 | 4.54.1.0 14 | 4.55.0.0 15 | 4.56.0.0 16 | 4.57.0.0 17 | 4.58.0.0 18 | 4.58.1.0 19 | 4.59.0.0 20 | 4.60.0.0 21 | 4.60.1.0 22 | 4.60.2.0 23 | 4.60.3.0 24 | 4.61.0.0 25 | 4.61.1.0 26 | 4.61.3.0 27 | 4.62.0.0 28 | 4.63.0.0 29 | 4.64.0.0 30 | 4.64.1.0 31 | 4.65.0.0 32 | 4.66.0.0 33 | 4.66.1.0 34 | 4.66.2.0 35 | 4.67.0.0 36 | 4.67.1.0 37 | 4.67.2.0 38 | 4.68.0.0 39 | 4.69.1.0 40 | 4.70.0.0 41 | 4.70.1.0 42 | 4.70.2.0 43 | 4.71.0.0 44 | 4.71.1.0 45 | 4.74.0.0 46 | 47 | 48 | 49 | 50 | Interface used for creation of client applications. For details see https://aka.ms/msal-net-client-applications. 51 | 52 | To be added. 53 | 54 | 55 | 56 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client/LogCallback.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.48.1.0 10 | 4.49.1.0 11 | 4.51.0.0 12 | 4.52.0.0 13 | 4.53.0.0 14 | 4.54.0.0 15 | 4.54.1.0 16 | 4.55.0.0 17 | 4.56.0.0 18 | 4.57.0.0 19 | 4.58.0.0 20 | 4.58.1.0 21 | 4.59.0.0 22 | 4.60.0.0 23 | 4.60.1.0 24 | 4.60.2.0 25 | 4.60.3.0 26 | 4.61.0.0 27 | 4.61.1.0 28 | 4.61.3.0 29 | 4.62.0.0 30 | 4.63.0.0 31 | 4.64.0.0 32 | 4.64.1.0 33 | 4.65.0.0 34 | 4.66.0.0 35 | 4.66.1.0 36 | 4.66.2.0 37 | 4.67.0.0 38 | 4.67.1.0 39 | 4.67.2.0 40 | 4.68.0.0 41 | 4.69.1.0 42 | 4.70.0.0 43 | 4.70.1.0 44 | 4.70.2.0 45 | 4.71.0.0 46 | 4.71.1.0 47 | 4.74.0.0 48 | 49 | 50 | System.Delegate 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | System.Void 59 | 60 | 61 | Log level of the log message to process 62 | Pre-formatted log message 63 | Indicates if the log message contains Organizational Identifiable Information (OII) 64 | or Personally Identifiable Information (PII) nor not. 65 | 66 | Callback delegate that allows application developers to consume logs, and handle them in a custom manner. This 67 | callback is set using . 68 | If PiiLoggingEnabled is set to true, when registering the callback this method will receive the messages twice: 69 | once with the containsPii parameter equals false and the message without PII, 70 | and a second time with the containsPii parameter equals to true and the message might contain PII. 71 | In some cases (when the message does not contain PII), the message will be the same. 72 | For details see https://aka.ms/msal-net-logging 73 | 74 | To be added. 75 | 76 | 77 | 78 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client/PublicClientApplicationOptions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.48.1.0 10 | 4.49.1.0 11 | 4.51.0.0 12 | 4.52.0.0 13 | 4.53.0.0 14 | 4.54.0.0 15 | 4.54.1.0 16 | 4.55.0.0 17 | 4.56.0.0 18 | 4.57.0.0 19 | 4.58.0.0 20 | 4.58.1.0 21 | 4.59.0.0 22 | 4.60.0.0 23 | 4.60.1.0 24 | 4.60.2.0 25 | 4.60.3.0 26 | 4.61.0.0 27 | 4.61.1.0 28 | 4.61.3.0 29 | 4.62.0.0 30 | 4.63.0.0 31 | 4.64.0.0 32 | 4.64.1.0 33 | 4.65.0.0 34 | 4.66.0.0 35 | 4.66.1.0 36 | 4.66.2.0 37 | 4.67.0.0 38 | 4.67.1.0 39 | 4.67.2.0 40 | 4.68.0.0 41 | 4.69.1.0 42 | 4.70.0.0 43 | 4.70.1.0 44 | 4.70.2.0 45 | 4.71.0.0 46 | 4.71.1.0 47 | 4.74.0.0 48 | 49 | 50 | Microsoft.Identity.Client.ApplicationOptions 51 | 52 | 53 | 54 | 55 | Configuration options for a public client application (desktop/mobile app). 56 | See https://aka.ms/msal-net/application-configuration 57 | 58 | To be added. 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | Constructor 67 | 68 | Microsoft.Identity.Client 69 | 4.74.0.0 70 | 71 | 72 | 73 | To be added. 74 | To be added. 75 | 76 | 77 | 78 | 79 | -------------------------------------------------------------------------------- /dotnet/xml/Microsoft.Identity.Client/TokenCacheCallback.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Microsoft.Identity.Client 9 | 4.48.1.0 10 | 4.49.1.0 11 | 4.51.0.0 12 | 4.52.0.0 13 | 4.53.0.0 14 | 4.54.0.0 15 | 4.54.1.0 16 | 4.55.0.0 17 | 4.56.0.0 18 | 4.57.0.0 19 | 4.58.0.0 20 | 4.58.1.0 21 | 4.59.0.0 22 | 4.60.0.0 23 | 4.60.1.0 24 | 4.60.2.0 25 | 4.60.3.0 26 | 4.61.0.0 27 | 4.61.1.0 28 | 4.61.3.0 29 | 4.62.0.0 30 | 4.63.0.0 31 | 4.64.0.0 32 | 4.64.1.0 33 | 4.65.0.0 34 | 4.66.0.0 35 | 4.66.1.0 36 | 4.66.2.0 37 | 4.67.0.0 38 | 4.67.1.0 39 | 4.67.2.0 40 | 4.68.0.0 41 | 4.69.1.0 42 | 4.70.0.0 43 | 4.70.1.0 44 | 4.70.2.0 45 | 4.71.0.0 46 | 4.71.1.0 47 | 4.74.0.0 48 | 49 | 50 | System.Delegate 51 | 52 | 53 | 54 | 55 | 56 | System.Void 57 | 58 | 59 | Arguments related to the cache item impacted 60 | 61 | Notification for certain token cache interactions during token acquisition. This delegate is 62 | used in particular to provide a custom token cache serialization. 63 | See https://aka.ms/aka.ms/msal-net-token-cache-serialization 64 | 65 | To be added. 66 | 67 | 68 | -------------------------------------------------------------------------------- /dotnet/xml/PackageInformation/msal-dotnet-latest.json: -------------------------------------------------------------------------------- 1 | {"msal-dotnet-latest":{"Microsoft.Identity.Web":{"Name":"Microsoft.Identity.Web","Version":"3.10.0","Feed":"https://api.nuget.org/v3/index.json"},"Microsoft.Identity.Client":{"Name":"Microsoft.Identity.Client","Version":"4.74.0","Feed":"https://api.nuget.org/v3/index.json"},"Microsoft.Identity.Client.Desktop":{"Name":"Microsoft.Identity.Client.Desktop","Version":"4.74.0","Feed":"https://api.nuget.org/v3/index.json"},"Microsoft.IdentityModel.JsonWebTokens":{"Name":"Microsoft.IdentityModel.JsonWebTokens","Version":"8.12.1","Feed":"https://api.nuget.org/v3/index.json"},"Microsoft.Identity.Client.Broker":{"Name":"Microsoft.Identity.Client.Broker","Version":"4.74.0","Feed":"https://api.nuget.org/v3/index.json"}}} -------------------------------------------------------------------------------- /dotnet/xml/ns-.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-AspNetCore.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Abstractions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Advanced.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.AppConfig.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.AuthScheme.PoP.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.AuthScheme.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Broker.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | [!NOTE] 12 | >The `Microsoft.Identity.Client.Broker` functionality is not available for UWP, .NET 6 Windows (`net6-windows` target framework moniker), or legacy applications using .NET Framework, or .NET Core 3 and below. 13 | > 14 | >For legacy applications, refer to [`Microsoft.Identity.Client.Desktop`](xref:Microsoft.Identity.Client.Desktop). 15 | 16 | ## Installation 17 | 18 | Using the [.NET Command-Line Interface (CLI)](/dotnet/core/tools/): 19 | 20 | ```bash 21 | dotnet add package Microsoft.Identity.Client.Broker 22 | ``` 23 | 24 | Using the [NuGet Command Line Interface (CLI)](/nuget/tools/nuget-exe-cli-reference): 25 | 26 | ```bash 27 | nuget install Microsoft.Identity.Client.Broker 28 | ``` 29 | 30 | Using the [Package Manager Console](/nuget/tools/package-manager-console): 31 | 32 | ```powershell 33 | Install-Package Microsoft.Identity.Client.Broker 34 | ``` 35 | 36 | Using [Visual Studio](/visualstudio/): 37 | 38 | 1. Open the Solution Explorer. 39 | 2. Right-click on a project within the solution. 40 | 3. Click on **Manage NuGet Packages...** 41 | 4. Click on the Browse tab and search for `Microsoft.Identity.Client.Broker`. 42 | 5. Click on the `Microsoft.Identity.Client.Broker` package and click **Install**. 43 | 44 | ## Documentation 45 | 46 | To get started, check out the [Microsoft Authentication Library for .NET](/entra/msal/dotnet/) guide. 47 | 48 | ## Samples 49 | 50 | Refer to [Microsoft identity platform code samples](/azure/active-directory/develop/sample-v2-code) and the [Samples Browser](/samples/browse/?products=microsoft-authentication-library&expanded=microsoft-authentication-library). 51 | ]]> 52 | 53 | 54 | 55 | 69 | 70 | 71 | 72 | 73 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Cache.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Desktop.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | [!WARNING] 12 | >This package and namespace are intended for legacy applications that want to use the [Web Account Manager (WAM)](/windows/uwp/security/web-account-manager) in Windows. 13 | > 14 | >For modern applications, refer to [`Microsoft.Identity.Client.Broker`](xref:Microsoft.Identity.Client.Broker). 15 | 16 | ## Installation 17 | 18 | Using the [.NET Command-Line Interface (CLI)](/dotnet/core/tools/): 19 | 20 | ```bash 21 | dotnet add package Microsoft.Identity.Client.Desktop 22 | ``` 23 | 24 | Using the [NuGet Command Line Interface (CLI)](/nuget/tools/nuget-exe-cli-reference): 25 | 26 | ```bash 27 | nuget install Microsoft.Identity.Client.Desktop 28 | ``` 29 | 30 | Using the [Package Manager Console](/nuget/tools/package-manager-console): 31 | 32 | ```powershell 33 | Install-Package Microsoft.Identity.Client.Desktop 34 | ``` 35 | 36 | Using [Visual Studio](/visualstudio/): 37 | 38 | 1. Open the Solution Explorer. 39 | 2. Right-click on a project within the solution. 40 | 3. Click on **Manage NuGet Packages...** 41 | 4. Click on the Browse tab and search for `Microsoft.Identity.Client.Desktop`. 42 | 5. Click on the `Microsoft.Identity.Client.Desktop` package and click **Install**. 43 | 44 | ## Documentation 45 | 46 | To get started, check out the [Microsoft Authentication Library for .NET](/entra/msal/dotnet/) guide. To learn more about the use of Web Account Manager with MSAL.NET, refer to [Using MSAL.NET with Web Account Manager (WAM)](/entra/msal/dotnet/acquiring-tokens/desktop-mobile/wam). 47 | 48 | ## Samples 49 | 50 | Refer to [Microsoft identity platform code samples](/azure/active-directory/develop/sample-v2-code) and the [Samples Browser](/samples/browse/?products=microsoft-authentication-library&expanded=microsoft-authentication-library). 51 | ]]> 52 | 53 | 54 | 55 | 69 | 70 | 71 | 72 | 73 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Extensibility.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Kerberos.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.ManagedIdentity.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Platforms.Features.DesktopOs.Kerberos.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.RP.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Region.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.SSHCertificates.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.TelemetryCore.TelemetryClient.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Utils.Windows.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.Utils.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Client.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 45 | 46 | 47 | 48 | 62 | 63 | 64 | 65 | 66 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.Experimental.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.Extensibility.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.Internal.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.OWIN.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.Resource.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.TestOnly.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.TokenCacheProviders.Distributed.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.TokenCacheProviders.InMemory.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.TokenCacheProviders.Session.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.TokenCacheProviders.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.UI.Areas.MicrosoftIdentity.Controllers.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.UI.Areas.MicrosoftIdentity.Pages.Account.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.UI.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.Identity.Web.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Abstractions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.JsonWebTokens.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.KeyVaultExtensions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Logging.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.LoggingExtensions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.ManagedKeyVaultSecurityKey.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Protocols.Configuration.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Protocols.OpenIdConnect.Configuration.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Protocols.OpenIdConnect.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Protocols.SignedHttpRequest.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Protocols.WsFederation.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Protocols.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.TestExtensions.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Tokens.Configuration.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Tokens.Saml.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Tokens.Saml2.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Tokens.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Validators.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-Microsoft.IdentityModel.Xml.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /dotnet/xml/ns-System.IdentityModel.Tokens.Jwt.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | To be added. 4 | To be added. 5 | 6 | 7 | -------------------------------------------------------------------------------- /msal-dotnet-articles/acquiring-tokens/clear-token-cache.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Clear the token cache (MSAL.NET) 3 | description: Learn how to clear the token cache using the Microsoft Authentication Library for .NET (MSAL.NET). 4 | author: cilwerner 5 | manager: CelesteDG 6 | ms.author: cwerner 7 | ms.date: 08/24/2023 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: how-to 12 | ms.custom: devx-track-csharp, aaddev, devx-track-dotnet 13 | #Customer intent: As an application developer, I want to learn how how to clear the token cache so I can . 14 | --- 15 | 16 | # Clear the token cache using MSAL.NET 17 | 18 | ## Web API and daemon apps 19 | 20 | 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](../how-to/token-cache-serialization.md?tabs=aspnetcore) for details on how to use a memory cache or distributed cache. 21 | 22 | ## Desktop, command line and mobile applications 23 | 24 | When you [acquire an access token](/azure/active-directory/develop/msal-acquire-cache-tokens) 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. 25 | 26 | 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. 27 | 28 | ```csharp 29 | private readonly IPublicClientApplication _app; 30 | private static readonly string ClientId = ConfigurationManager.AppSettings["ida:ClientId"]; 31 | private static readonly string Authority = string.Format(CultureInfo.InvariantCulture, AadInstance, Tenant); 32 | 33 | _app = PublicClientApplicationBuilder.Create(ClientId) 34 | .WithAuthority(Authority) 35 | .Build(); 36 | 37 | var accounts = (await _app.GetAccountsAsync()).ToList(); 38 | 39 | // clear the cache 40 | while (accounts.Any()) 41 | { 42 | await _app.RemoveAsync(accounts.First()); 43 | accounts = (await _app.GetAccountsAsync()).ToList(); 44 | } 45 | 46 | ``` 47 | 48 | To learn more about acquiring and caching tokens, read [acquire an access token](/azure/active-directory/develop/msal-acquire-cache-tokens) 49 | -------------------------------------------------------------------------------- /msal-dotnet-articles/acquiring-tokens/desktop-mobile/mobile-applications.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using MSAL.NET With .NET MAUI 3 | description: "How to use MSAL.NET on mobile platforms." 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | #Customer intent: 13 | --- 14 | 15 | # Using MSAL.NET With MAUI 16 | 17 | MSAL.NET can run on mobile devices (both iOS and Android) through applications built with [.NET Multi-platform App UI (MAUI)](https://dotnet.microsoft.com/apps/maui). 18 | 19 | >[!NOTE] 20 | >The .NET team recommends [migrating existing Xamarin applications to MAUI](/dotnet/maui/migration/). New applications should always use MAUI. MSAL.NET versions 4.61.0 and above do not provide support for Xamarin Android and Xamarin iOS. 21 | 22 | ## Using MSAL.NET with brokers on mobile devices 23 | 24 | MSAL.NET can be used with authentication brokers on mobile devices, such as Microsoft Authenticator or the Company Portal. To learn more about how to configure applications to use brokers on iOS and Android, refer to [Use Microsoft Authenticator or Intune Company Portal on Xamarin applications](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps). 25 | 26 | ## MAUI on Android 27 | 28 | To get started with MSAL.NET integration on Android, refer to the following resources: 29 | 30 | - [How to migrate Xamarin ADAL apps to MSAL for Android](/entra/identity-platform/msal-net-migration-android-broker) 31 | - [Xamarin Android Configuration Tips + Troubleshooting](/entra/identity-platform/msal-net-xamarin-android-considerations) 32 | - [Xamarin Android System Browser Info](/entra/identity-platform/msal-net-system-browser-android-considerations) 33 | 34 | To learn more about testing MSAL on Android devices, refer to the [MSAL for Android Wiki](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki/Android-Emulator-with-MSAL). 35 | 36 | ## MAUI on iOS 37 | 38 | To get started with MSAL.NET integration on iOS, refer to the following resources: 39 | 40 | - [How to migrate Xamarin ADAL apps to MSAL for iOS](/entra/identity-platform/msal-net-migration-ios-broker) 41 | - [Xamarin iOS Configuration Tips + Troubleshooting](/entra/identity-platform/msal-net-xamarin-ios-considerations) 42 | -------------------------------------------------------------------------------- /msal-dotnet-articles/acquiring-tokens/web-apps-apis/workload-identity-federation.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Acquiring a token with federated workload identity 3 | description: "How to acquire tokens with federated workload identity in MSAL.NET" 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Workload identity federation 17 | 18 | [Workload identity federation](/entra/workload-id/workload-identity-federation) allows you to access Microsoft Entra protected resources without needing to manage client application secrets. First, set up the workload identity federation in the app registration. In the application code, create a function which will fetch the tokens from the external provider, then pass it into . For each token request, MSAL will call this function to get an external token with which to acquire the Microsoft Entra tokens. Make sure this function caches the token to avoid making too many calls to the external provider. 19 | 20 | ```csharp 21 | using Microsoft.Identity.Client; 22 | 23 | var app = ConfidentialClientApplicationBuilder 24 | .Create(clientId) 25 | .WithClientAssertion((AssertionRequestOptions options) => FetchExternalTokenAsync()) 26 | .WithCacheOptions(CacheOptions.EnableSharedCacheOptions) // for more cache options see https://learn.microsoft.com/entra/msal/dotnet/how-to/token-cache-serialization?tabs=msal 27 | .Build() 28 | 29 | var result = await app.AcquireTokenForClient(scope).ExecuteAsync(); 30 | 31 | public async Task FetchExternalTokenAsync() 32 | { 33 | // Logic to get token from cache or other sources, like GitHub, Kubernetes, etc. 34 | // Caching is the responsability of the implementer. 35 | return token; 36 | } 37 | 38 | ``` 39 | 40 | [Microsoft.Identity.Web.Certificateless](https://www.nuget.org/packages/Microsoft.Identity.Web.Certificateless) package provides some helper methods to acquire federated tokens. Use for managed identity federation. 41 | 42 | ```csharp 43 | using Microsoft.Identity.Web; 44 | 45 | // Reuse this instance so that the assertion is cached and only refreshed once it expires. 46 | ManagedIdentityClientAssertion managedIdentityClientAssertion = new ManagedIdentityClientAssertion(userAssignedId); 47 | 48 | public async Task FetchExternalTokenAsync() 49 | { 50 | return await managedIdentityClientAssertion.GetSignedAssertion(default); 51 | } 52 | 53 | ``` 54 | 55 | To acquire a federated token in a Azure Kubernetes cluster, use . 56 | 57 | ```csharp 58 | using Microsoft.Identity.Web; 59 | 60 | // Reuse this instance so that the assertion is cached and only refreshed once it expires. 61 | AzureIdentityForKubernetesClientAssertion aksClientAssertion = new AzureIdentityForKubernetesClientAssertion(); 62 | 63 | public async Task FetchExternalTokenAsync() 64 | { 65 | return await aksClientAssertion.GetSignedAssertion(default); 66 | } 67 | 68 | ``` 69 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/android-ios-emulator.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using MSAL.NET with Android and iOS emulators 3 | description: "How to use MSAL.NET with Android and iOS device emulators." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Using MSAL.NET with Android and iOS emulators 17 | 18 | >[!NOTE] 19 | >The MSAL .NET team recommends testing with an Android or iOS device whenever possible, as there are subtle differences between authentication with an emulator and a device. 20 | 21 | Some of those issues are documented here in the [native Android MSAL library Wiki](https://github.com/AzureAD/microsoft-authentication-library-for-android/wiki/Android-Emulator-with-MSAL). 22 | 23 | For iOS, there are differences between SSO and accessing keychain when using an emulator or a device. Before opening an issue or reporting a bug, please see if the issue replicates on a device. 24 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/backup-authentication-system.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Backup authentication system 3 | description: "The Microsoft Entra backup authentication system enables the caching of credentials processed by the Evolved Security Token Service (ESTS) in order to provide resiliency during outages in Microsoft Entra authentication services." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Backup authentication system 17 | 18 | The Microsoft Entra ID has a backup authentication system that enables the caching of credentials in order to provide resiliency during outages in Microsoft Entra authentication services. 19 | 20 | In order to assist in speeding up the token retrieval from the backup authentication system, MSAL will provide a routing hint in the form of a header or an extra query parameter in authentication requests sent to ESTS. MSAL will attempt to do this for most of the authentication scenarios but there may be cases where MSAL is not able to provide this hint due to the absence of user data. This issue can be resolved by the use of and . 21 | 22 | Here is an example of how to use the : 23 | 24 | ```csharp 25 | ConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(TestConstants.ClientId) 26 | .WithClientSecret(clientSecret) 27 | .Build(); 28 | // When creating an authorization Uri 29 | var uri = await app 30 | .GetAuthorizationRequestUrl(TestConstants.s_scope) 31 | .WithCcsRoutingHint(userObjectIdentifier, tenantIdentifier) 32 | .ExecuteAsync(); 33 | 34 | // When Acquiring a Token 35 | app.AcquireTokenByAuthorizationCode(scopes, authCode) 36 | .WithCcsRoutingHint(userObjectIdentifier, tenantIdentifier) 37 | .ExecuteAsync() 38 | ``` 39 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/clearing-token-cache.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cleaning the token cache 3 | description: "How to clear the token cache used by MSAL.NET" 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Clearing the token cache 17 | 18 | Clearing the token cache is achieved by removing the accounts from the cache. This does not remove the session cookie which is in the browser. 19 | 20 | The example below is using an instance of . 21 | 22 | ```csharp 23 | // Clear the cache 24 | var accounts = await app.GetAccountsAsync(); 25 | while (accounts.Any()) 26 | { 27 | await app.RemoveAsync(accounts.First()); 28 | accounts = await app.GetAccountsAsync(); 29 | } 30 | ``` 31 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/client-and-server-throttling.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Understanding client and server throttling in MSAL.NET 3 | description: "Microsoft Entra ID throttles applications when you call the authentication API too frequently. Learn how to handle this with MSAL.NET." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: how-to 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Understanding client and server throttling in MSAL.NET 17 | 18 | ## Server throttling 19 | 20 | Microsoft Entra ID throttles applications when you call the authentication API too frequently. Most often this happens when token caching is not used because: 21 | 22 | 1. Token caching is not setup correctly (see [Token cache serialization](/azure/active-directory/develop/msal-net-token-cache-serialization)). 23 | 2. Not calling before calling , . 24 | 3. If you are asking for a scope which does not apply to Microsoft Account (MSA) users, such as `User.ReadBasic.All`, resulting in cache misses. 25 | 26 | The server signals throttling in two ways: 27 | 28 | - For `client_credentials` grant, i.e., , Microsoft Entra ID will reply with `429 Too Many Requests`, with a `Retry-After: 60` header. 29 | - For user-facing calls, Microsoft Entra ID will send a message which results in a with an `invalid_grant` error code and a message set to `AADSTS50196: The server terminated an operation because it encountered a loop while processing a request`. 30 | 31 | ## Client throttling 32 | 33 | MSAL detects certain conditions where the application should not make repeated calls to Microsoft Entra ID. If a call is made, then a or a exception is thrown. These are subtypes of , so this behavior does not introduce a breaking change. 34 | 35 | If MSAL would not apply client-side throttling the application would still not be able to acquire tokens as Microsoft Entra ID would throw the error regardless. 36 | 37 | ## Conditions to get throttled 38 | 39 | 40 | 41 | ### Microsoft Entra ID is telling the application to back off 42 | 43 | If the server is having problems or if an application is requesting tokens too often Microsoft Entra ID will respond with `HTTP 429 (Too Many Requests)` and with `Retry-After` header, `Retry-After X seconds`. The application will see an with [header details](../advanced/exceptions/retry-policy.md). The throttling state is maintained for X seconds. This limit affects all flows. 44 | 45 | The most likely culprit is that you have not setup token caching. See [Token cache serialization in MSAL.NET](/azure/active-directory/develop/msal-net-token-cache-serialization) for details. 46 | 47 | 48 | 49 | ### Microsoft Entra ID is having problems 50 | 51 | If Microsoft Entra ID is having problems it may respond with a `HTTP 5xx` error code with no `Retry-After` header. The throttling state is maintained for one minute. Affects only public client flows. 52 | 53 | ### Application is ignoring `MsalUiRequiredException` 54 | 55 | MSAL throws when authentication cannot be resolved silently and the end-user needs to use a browser. This is a common occurrence when a tenant administrator introduced Multi-Factor Authentication (MFA) or when a user's password expires. Retrying the silent authentication cannot succeed. The throttling state is maintained for two minutes. Affects only the flow. 56 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/client-credential-multi-tenant.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using MSAL.NET for client credential flow in multi-tenant services 3 | description: Learn Microsoft's Advanced Client Credential Multi-Tenant with MSAL.NET, token caching, and Microsoft.Identity.Web for ASP.NET Core. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Using MSAL.NET for client credential flow in multi-tenant services 17 | 18 | ## Decision point - Microsoft.Identity.Web or Microsoft.Identity.Client (MSAL)? 19 | 20 | If you use ASP.NET Core, you are encouraged to adopt [`Microsoft.Identity.Web`](https://github.com/AzureAD/microsoft-identity-web/wiki), which provides a higher level API over token acquisition and has better defaults. See [Is MSAL.NET right for me?](../getting-started/choosing-msal-dotnet.md) 21 | 22 | ## Decision point - token caching 23 | 24 | MSAL maintains a token cache which grows with each token acquired. MSAL manages token lifetimes in a smart way, so you should use its cache. You have the option of using in-memory caching or distributed caching. 25 | 26 | See [MSAL.NET Token Cache Serialization](/azure/active-directory/develop/msal-net-token-cache-serialization). 27 | 28 | We recommend using persisted distributed caches (e.g. Redis, Cosmos etc.) for all user flows. 29 | 30 | We also recommend that multi-tenant service 2 service apps use persisted distributed caches. But you may get away with using a memory cache with evictions if you know that your service needs app tokens for a limited number of tenants. 31 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/custom-authority-aliases.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Custom authority aliases 3 | description: "How to use custom authority aliases with your MSAL.NET applications." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Custom authority aliases 17 | 18 | ## What is Instance Discovery 19 | 20 | Before acquiring tokens, MSAL makes a network call to the Microsoft Entra authority discovery endpoint: 21 | 22 | ```text 23 | https://login.microsoftonline.com/common/discovery/instance?api-version=1.1&authorization_endpoint=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Fauthorize 24 | ``` 25 | 26 | The information returned is used to: 27 | 28 | - Discover a list of aliases for each cloud (Azure Public, German Cloud, China Cloud etc.). A token issued to an authority in the set is valid for all other authorities in the set. 29 | - Use the preferred_network alias for communication with Microsoft Entra ID 30 | - Use the preferred_cache alias to store tokens in the cache 31 | - Provide a level of validation for the authority - if a non-existent authority is used, then Microsoft Entra ID returns an "invalid_instance" error: 32 | 33 | ```json 34 | { 35 | "error":"invalid_instance", 36 | "error_description":"AADSTS50049: Unknown or invalid instance.\r\nTrace ID: 3adb62d2-11d5-4bb0-acac-7d97451c0000\r\nCorrelation ID: ce374500-8786-4739-ac5b-9a57f9cc0140\r\nTimestamp: 2023-03-27 16:25:19Z", 37 | "error_codes":[ 38 | 50049 39 | ], 40 | "timestamp":"2023-03-27 16:25:19Z", 41 | "trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333", 42 | "correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd", 43 | "error_uri":"https://login.microsoftonline.com/error?code=50049" 44 | } 45 | ``` 46 | 47 | ## Instance validation 48 | 49 | The validation is important if you obtain your authority dynamically, for example when you call a protect API, it returns a 401 Unauthorized HTTP response which can include a header pointing to an authority that is able to generate a token. If the API is hacked, it could advertise an authority that does not belong to Microsoft Entra ID and that could steal user credentials. 50 | 51 | ## Disabling Instance Discovery 52 | 53 | MSAL libraries already employ a variety of caching mechanisms for this data. You may still want to bypass the Instance Discovery network call to further optimize performance in some PublicClientApplication scenarios, but you you should only do this if you understand the security risk outlined above. If you provide your own instance metadata, MSAL will always use it and it will never go to the network for this kind of data. 54 | 55 | ```csharp 56 | var app = PublicClientApplicationBuilder 57 | .Create(MsalTestConstants.ClientId) 58 | // or a Guid instead of common 59 | .WithAuthority(new Uri("https://login.microsoftonline.com/common/"), false) // or a tenanted authority ending in a GUID 60 | .WithInstanceDicoveryMetadata(instanceMetadataJson) // a json string similar to https://aka.ms/aad-instance-discovery 61 | .Build(); 62 | ``` 63 | 64 | >[!NOTE] 65 | >You have to set the `validateAuthority` flag to `false` because validation is only made against your custom discovery metadata. 66 | 67 | ### Example instance metadata 68 | 69 | Assuming that your authority is `https://login.contoso.net` then a valid instance discovery is shown below. You need to pass this value a string. 70 | 71 | ```json 72 | { 73 | "api-version": "1.1", 74 | "metadata": [ 75 | { 76 | "preferred_network": "login.contoso.net", 77 | "preferred_cache": "login.contoso.net", 78 | "aliases": [ 79 | "login.contoso.net" 80 | ] 81 | } 82 | ] 83 | } 84 | ``` 85 | 86 | ## Related MsalError constants 87 | 88 | The `MsalError` you can get when using this feature are the following: 89 | 90 | | Error | Description | 91 | |:------|:------------| 92 | | `InvalidUserInstanceMetadata ` | You have configured your own custom instance discovery metadata, but the JSON you provided seems to be invalid. You need a valid `ValidateAuthorityOrCustomMetadata`. Alternatively, it's possible that you have configured your own instance metadata, but have been requesting authority validation. You need to set the validate authority flag to false. | 93 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/exceptions/broker.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Troubleshooting brokered applications 3 | description: Master brokered authentication on Android with our troubleshooting guide. Learn about redirect URIs, broker versions, precedence, and log acquisition. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: troubleshooting-general 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Troubleshooting brokered applications 17 | 18 | ## Tips for Android brokered authentication 19 | 20 | Here are a few tips on avoiding issues when you implement brokered authentication on Android: 21 | 22 | - **Redirect URI** - Add a redirect URI to your application registration in the [Azure portal](https://portal.azure.com/). A missing or incorrect redirect URI is a common issue encountered by developers. 23 | - **Broker version** - Install the minimum required version of the broker apps. Either of these two apps can be used for brokered authentication on Android. 24 | - [InTune Company Portal](https://play.google.com/store/apps/details?id=com.microsoft.windowsintune.companyportal) (version 5.0.4689.0 or greater) 25 | - [Microsoft Authenticator](https://play.google.com/store/apps/details?id=com.azure.authenticator) (version 6.2001.0140 or greater). 26 | - **Broker precedence** - MSAL communicates with the *first broker installed* on the device when multiple brokers are installed. 27 | 28 | Example: If you first install Microsoft Authenticator and then install Intune Company Portal, brokered authentication will *only* happen on the Microsoft Authenticator. 29 | - **Logs** - If you encounter an issue with brokered authentication, viewing the broker's logs might help you diagnose the cause. 30 | - Acquiring Microsoft Authenticator logs: 31 | 32 | 1. Select the menu button in the top-right corner of the app. 33 | 1. Select **Send Feedback** > **Having Trouble?**. 34 | 1. Select one of the options under **What are you trying to do?** to add a description 35 | 1. You can then hit the arrow on the top right of the screen to send the logs. 36 | 1. Once you send the logs you will be presented with a popup that will contain an **Incident ID**. Please provide this incident ID when requesting assistance. 37 | 38 | - Acquiring Intune Company Portal logs: 39 | 40 | 1. Select the menu button on the top-left corner of the app 41 | 1. Select **Help** > **Email Support** 42 | 1. Select **Upload Logs Only** to send the logs. 43 | 1. Once you send the logs you will be presented with a popup that will contain an **Incident ID**. Please provide this incident ID when requesting assistance. 44 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/exceptions/device-authentication-errors.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Device authentication errors 3 | description: "Errors that can show up when using device authentication with MSAL.NET." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Device authentication errors 17 | 18 | ## What are the symptoms? 19 | 20 | You get errors like "AADSTS50097" or "Device authentication is required". 21 | 22 | ## What happens? 23 | 24 | This error happens when a conditional access policy is applied to the resource you are accessing, which required that the device from which the token is acquired be managed by the organization, and that MSAL.NET proves this identity. 25 | 26 | This is a conditional access policy applied by the tenant admin. For details see [How To: Require managed devices for cloud app access with Conditional Access](/azure/active-directory/conditional-access/require-managed-devices) 27 | 28 | ## How to fix this? 29 | 30 | To satisfy this requirement you will have to leverage WAM on Windows or the system browser. On mobile platforms, you'll need to enable the brokers (Microsoft Authenticator and Company portal) 31 | 32 | - If you are writing a desktop application running on Windows, see [WAM integration for Desktop applications](../../acquiring-tokens/desktop-mobile/wam.md). 33 | - [On iOS and Android](../../acquiring-tokens/desktop-mobile/mobile-applications.md), we recommend [enabling the authentication broker](/azure/active-directory/develop/msal-net-use-brokers-with-xamarin-apps) 34 | - The same principles apply to Web Applications, though given you are in a browser you must leverage a browser which can "talk to" WAM (that is either Edge on Chromium or Chrome with the Microsoft Entra extensions). For details see [Conditional access conditions](/azure/active-directory/conditional-access/concept-conditional-access-conditions#chrome-support). 35 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/exceptions/retry-policy.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Retry policies 3 | description: Learn how to implement a custom retry policy for token acquisition operations in .NET with MSAL. Increase your service availability with our detailed guide. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Retry Policies are baked in the libary 17 | 18 | MSAL has its own retry policies. In rare cases you can choose to disable the internal retry policies and add your own. See [HttpClient tips](../httpclient.md). 19 | 20 | ### MSAL implements a simple "retry-once" for errors with HTTP error codes 5xx 21 | 22 | MSAL.NET implements a simple retry-once with 1 second delay mechanism for errors with HTTP error codes 500-600, for the token endpoint. 23 | For managed identity, the retry follows the guidelines of each source. 24 | 25 | ## Customize the HTTP stack 26 | 27 | In some cases, such as using proxies, you might want to customize the Http Stack. See [HttpClient tips](../httpclient.md) for details. 28 | 29 | 30 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/exceptions/tls-issues.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: TLS issues 3 | description: "How to diagnose and address TLS issues when using MSAL.NET" 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # TLS issues 17 | 18 | ## What is happening 19 | 20 | Microsoft has an initiative to disable anything less that TLS 1.2 for security reasons. The [Microsoft TLS 1.0 implementation](https://support.microsoft.com/help/3117336/schannel-implementation-of-tls-1-0-in-windows-security-status-update-n) has no known security vulnerabilities. But because of the potential for future protocol downgrade attacks and other TLS vulnerabilities, Office, for instance are [discontinuing](/microsoft-365/compliance/prepare-tls-1.2-in-office-365) support for TLS 1.0 and 1.1 in Microsoft Office 365. 21 | 22 | As this initiative is going through, you ask more and more questions about the fact that some services deployed to Azure require TLS 2.0, and this is caught by MSAL.NET. See for instance [#657](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/657) 23 | 24 | MSAL.NET already supports TLS 2.0 (as previous versions). Some of you have proposed to set System.Net.ServicePointManager.SecurityProtocol to System.Net.SecurityProtocolType.Tls12, however this is not the right fix as when TLS 1.3 shows up, the apps would have to change. 25 | 26 | ## What is the right fix? 27 | 28 | We suggest you read [Transport Layer Security (TLS) best practices with the .NET Framework](/dotnet/framework/network-programming/tls). The simplest fix would be, if you can, to make sure your app moves to .NET Framework 4.7+, otherwise the best practices document details your options. 29 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/exceptions/understanding-statemismatcherror.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Understanding StateMismatchError 3 | dscription: "Learn about StateMismatchError in MSAL.NET, its properties, and how to handle it effectively." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Understanding `StateMismatchError` 17 | 18 | MSAL verifies the state returned by the server with the original state as a security protocol. In case the state is different this exception is thrown. 19 | 20 | ## Known issues 21 | 22 | For apps when using a long Facebook Id observed to be 33 characters or more for example somelongemailaddressfortest@gmail.com, this exception is thrown. Embedded web view in desktop apps uses Internet Explorer and it truncates the URL to 2083 characters which causes the value of state parameter in the URL to be truncated. This causes the returned state to be different from the original state. 23 | 24 | To mitigate please use `.WithUseEmbeddedWebView(false)` and refer to [Using web browsers (MSAL.NET)](/azure/active-directory/develop/msal-net-web-browsers). 25 | 26 | ## References 27 | 28 | - [Maximum URL length is 2,083 characters in Internet Explorer](https://support.microsoft.com/help/208427/maximum-url-length-is-2-083-characters-in-internet-explorer) 29 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/exceptions/unity.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Troubleshooting MSAL.NET in Unity applications 3 | description: Learn how to troubleshoot MSAL.NET in Unity applications. Understand the cause of runtime exceptions and discover effective solutions. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: troubleshooting-general 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Troubleshooting MSAL.NET in Unity applications 17 | 18 | MSAL 4.48.0 and above stopped using reflection on its `net6` target. This is the only path forward with Unity. 19 | 20 | ## Member not found at runtime 21 | 22 | ### The issue 23 | 24 | When using MSAL.NET in a Unity app, the application builds successfully. However at runtime, exceptions, like the ones below, are thrown that some members don't exist in MSAL.NET's code: 25 | 26 | ```bash 27 | Error on deserializing read-only members in the class: No set method for property 'Claims' in type 'Microsoft.Identity.Client.OAuth2.OAuth2ResponseBase'. 28 | at System.Runtime.Serialization.DataContract+DataContractCriticalHelper.ThrowInvalidDataContractException 29 | (System.String message, System.Type type) [0x00000] in <00000000000000000000000000000000>:0 30 | at System.Runtime.Serialization.DataContract.ThrowInvalidDataContractException 31 | (System.String message, System.Type type) [0x00000] in <00000000000000000000000000000000>:0 32 | ``` 33 | 34 | ```bash 35 | Error setting value to 'TenantDiscoveryEndpoint' on 'Microsoft.Identity.Client.Instance.Discovery.InstanceDiscoveryResponse'. 36 | at Microsoft.Identity.Json.Serialization.ExpressionValueProvider.SetValue 37 | (System.Object target, System.Object value) [0x00000] in <00000000000000000000000000000000>:0 \r\n 38 | at Microsoft.Identity.Json.Serialization.JsonSerializerInternalReader.SetPropertyValue 39 | (Microsoft.Identity.Json.Serialization.JsonProperty property, Microsoft.Identity.Json.JsonConverter propertyConverter, 40 | Microsoft.Identity.Json.Serialization.JsonContainerContract containerContract, Microsoft.Identity.Json.Serialization.JsonProperty containerProperty, 41 | Microsoft.Identity.Json.JsonReader reader, System.Object target) [0x00000] in <00000000000000000000000000000000>:0 42 | ``` 43 | 44 | ### Cause and solution 45 | 46 | The issue comes from Unity IL2CPP plugin. When optimizing code (using code stripping), it removes needed dependencies for reflection to work (because it can't properly detect that usage). The MSAL.NET team investigated removing reflection related code from MSAL but it proved to be very impractical. Unity themselves have this documented in their docs ([Managed code stripping](https://docs.unity3d.com/Manual/ManagedCodeStripping.html#LinkXML)) and recommend to use Link XML method as one of the solutions to this issue. This is our recommendation as well. 47 | 48 | Add below entries into the root `Assets/link.xml` folder: 49 | 50 | ```xml 51 | 52 | 53 | 54 | 55 | 56 | ``` 57 | 58 | ### See also 59 | 60 | [#1185](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/1185), [#2231](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/2231) 61 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/experimental-features.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Experimental features in MSAL.NET 3 | description: "Explore experimental features in MSAL.NET, including regional discovery and other advanced capabilities." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Experimental features in MSAL.NET 17 | 18 | ## API promise 19 | 20 | MSAL is strict about semantic versioning and will not introduce breaking changes without incrementing the major version. 21 | 22 | ## Experimental APIs 23 | 24 | Some of the new APIs exposed by MSALs are marked as `Experimental`. These APIs may change without fulfilling the promise above. As such, it is not recommended to use these APIs in production, but you are encouraged to try them out, provide feedback etc. 25 | 26 | Starting with MSAL 4.8, developers need to add a flag to be able to use experimental features, otherwise an exception will be thrown. 27 | 28 | ```csharp 29 | var pca = PublicClientApplicationBuilder 30 | .Create(clientId) 31 | .WithExperimentalFeatues() 32 | .Build(); 33 | ``` 34 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/extensibility-points.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: MSAL.NET extensibility points 3 | description: Explore advanced extensibility points in MSAL.NET for scalable apps. Adapt HttpClient factories, modify token requests, inject query parameters, and more. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # MSAL.NET extensibility points 17 | 18 | MSAL adopts the strategy of "make simple scenarios simple, make complex scenarios possible". 19 | 20 | ## Use your own HttpClient 21 | 22 | Allows apps to adapt highly scalable HttpClient factories such as ASP.NET Core's [IHttpClientFactory](/aspnet/core/fundamentals/http-requests?view=aspnetcore-6.0). 23 | Helps desktop and mobile apps which have to deal with complex proxy configurations. 24 | Allows apps to fully control the HTTP messages. 25 | 26 | Details in . 27 | 28 | ## Modify the /token request 29 | 30 | Allows applications to make changes to the `/token` request, by providing access to the list of parameters and headers and to the URI where it is performed. Useful for trying out new flows which MSAL doesn't yet support. 31 | 32 | ```csharp 33 | public string GetTokenAsync() 34 | { 35 | var result = await app.AcquireTokenForClient(scope) 36 | .OnBeforeTokenRequest(ModifyRequestAsync) 37 | .ExecuteAsync(); 38 | 39 | // log result.AuthenticationResultMetadata.DurationTotalInMs and other metrics 40 | 41 | return result.Token; 42 | } 43 | 44 | private static Task ModifyRequestAsync(OnBeforeTokenRequestData requestData) 45 | { 46 | requestData.BodyParameters.Add("param1", "val1"); 47 | requestData.BodyParameters.Add("param2", "val2"); 48 | 49 | requestData.Headers.Add("header1", "hval1"); 50 | requestData.Headers.Add("header2", "hval2"); 51 | 52 | return Task.CompletedTask; 53 | } 54 | 55 | ``` 56 | 57 | ## Inject extra query parameters 58 | 59 | Allows apps to add query (GET) parameters to applications, customizing the experience. This mainly controls the UX login experience exposed by the `/authorize` endpoint, but the parameters are sent to the `/token` endpoint request as well. 60 | 61 | Useful to target Microsoft Entra service slices where new features or bug fixes are deployed first and to customize the UX experience with features not exposed by MSAL. Note that MSAL doesn't perform the `/authorize` request in ASP.NET / ASP.NET Core scenarios, so those calls are not affected! 62 | 63 | Details [here](/dotnet/api/microsoft.identity.client.abstractacquiretokenparameterbuilder-1.withextraqueryparameters?view=azure-dotnet#microsoft-identity-client-abstractacquiretokenparameterbuilder-1-withextraqueryparameters(system-string)) 64 | 65 | ## Desktop / Mobile Apps - ICustomWebUi 66 | 67 | Allows desktop and mobile apps to use their own browser instead of the embedded / system browsers provided by MSAL. 68 | 69 | Details [here](/dotnet/api/microsoft.identity.client.extensibility.icustomwebui?view=azure-dotnet) 70 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/httpclient.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Providing your own HttpClient, supporting HTTP proxies, and customization of user agent headers 3 | description: "There are cases where developers want fine-grained control of the HttpClient instance, such as configuring a proxy or using ASP.NET Core's efficient ways of pooling the HttpClient." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Providing your own HttpClient, supporting HTTP proxies, and customization of user agent headers 17 | 18 | There are cases where developers want fine-grained control of the `HttpClient` instance, such as configuring a proxy or using ASP.NET Core's efficient ways of pooling the `HttpClient`. You can read more in the [HttpClientFactory to implement resilient HTTP requests](/dotnet/standard/microservices-architecture/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests) document. To customize `HttpClient`, developers will need to implement `IMsalHttpClientFactory`, which MSAL will then use to get a `HttpClient` for each HTTP request. 19 | 20 | ## IMsalHttpClientFactory implementation guidelines 21 | 22 | - See for examples of scalable .NET factories which can be adapted for this interface, such as [ASP.NET Core's `IHttpClientFactory`](/aspnet/core/fundamentals/http-requests). 23 | - Implementations must be thread-safe. 24 | - Do not create a new `HttpClient` in `GetHttpClient`, as this will lead to port exhaustion. 25 | - MSAL will not call `Dispose()` on the `HttpClient`. 26 | - If your app uses [Integrated Windows Authentication](../acquiring-tokens/desktop-mobile/integrated-windows-authentication.md), ensure is set to `true`. 27 | 28 | ## Example implementation 29 | 30 | ```csharp 31 | IMsalHttpClientFactory httpClientFactory = new MyHttpClientFactory(); 32 | 33 | var pca = ConfidentialClientApplication.Create("client_id") 34 | .WithHttpClientFactory(httpClientFactory) 35 | .Build(); 36 | ``` 37 | 38 | A simple implementation of `IMsalHttpClientFactory` 39 | 40 | ```csharp 41 | public class StaticClientWithProxyFactory : IMsalHttpClientFactory 42 | { 43 | private static readonly HttpClient s_httpClient; 44 | 45 | static StaticClientWithProxyFactory() 46 | { 47 | var webProxy = new WebProxy( 48 | new Uri("http://my.proxy"), 49 | BypassOnLocal: false); 50 | 51 | webProxy.Credentials = new NetworkCredential("user", "pass"); 52 | 53 | var proxyHttpClientHandler = new HttpClientHandler 54 | { 55 | Proxy = webProxy, 56 | UseProxy = true, 57 | }; 58 | 59 | s_httpClient = new HttpClient(proxyHttpClientHandler); 60 | 61 | } 62 | 63 | public HttpClient GetHttpClient() 64 | { 65 | return s_httpClient; 66 | } 67 | } 68 | ``` 69 | 70 | 71 | ## HttpClient and Xamarin iOS 72 | 73 | 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). 74 | 75 | ## Troubleshooting 76 | 77 | **Problem**: On a desktop application, the authorization experience do not use the HttpClient I defined 78 | 79 | **Solution**: 80 | 81 | On desktop and mobile apps, MSAL opens a browser and navigates to the authorization URL. It does not use HttpClient 82 | When using the embedded browser, you can control the proxy for it by following the technique at: https://blogs.msdn.microsoft.com/jpsanders/2011/04/26/how-to-set-the-proxy-for-the-webbrowser-control-in-net/ 83 | This cannot be achived on .NET Core, where only the system browser is available. MSAL has no control over the system browser. 84 | 85 | **Problem**: My browser can connect to the proxy, but I get HTTP 407 errors from MSAL 86 | 87 | **Solution**: HTTP 407 shows a proxy authentication issue. .NET framework uses the proxy settings from IE, which by default does not include the "UseDefaultCredential" setting. Some users have reported fixing this issue by adding the following to their .config file: 88 | 89 | ```xml 90 | 91 | 92 | 93 | ``` 94 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/multicloud-support-instance-awareness.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Multicloud support and instance awareness 3 | description: "The instance awareness feature helps complete the scenario where any an account from any cloud can be signed-in using the default value for environment." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Multicloud support and instance awareness 17 | 18 | >[!WARNING] 19 | >This feature is only available to first-party applications (Microsoft applications), which have the same client ID across all clouds. Third-party applications have different client IDs for each cloud, and cannot use this feature. 20 | 21 | ## What is instance awareness? 22 | 23 | * The instance awareness feature helps complete the scenario where any an account from any cloud can be signed-in using the default value for environment. If instance awareness is not activated, the calling app has to provide the correct environment for the account. 24 | * It enables applications to pass in a default public cloud authority to the library and can still get tokens for resources (Graph) from national clouds. 25 | * The user and the resource should belong to single national cloud. 26 | * It is applicable only when using `/organizations` or `/common` authority URL and not a tenanted URL. 27 | 28 | ## What does it mean to enable multi-cloud support in MSAL? 29 | 30 | With multi-cloud support enabled, user will have the option to create a `PublicClientApplication` with global authority, and if a user enters a username from a national cloud, MSAL will return the token to access resource on the national cloud. 31 | 32 | Currently, multi-cloud support is available when acquiring token interactively. 33 | 34 | ## Sample to enable multi-cloud support 35 | 36 | ```csharp 37 | IPublicClientApplication pca = PublicClientApplicationBuilder 38 | .Create(AppId) 39 | .WithAuthority("https://login.microsoftonline.com/common") 40 | .WithMultiCloudSupport(true) 41 | .Build(); 42 | 43 | // Acquire a token interactively 44 | AuthenticationResult result = await pca 45 | .AcquireTokenInteractive(s_scopes) 46 | .ExecuteAsync() 47 | .ConfigureAwait(false); 48 | 49 | // Get accounts 50 | var accounts = await pca.GetAccountsAsync().ConfigureAwait(false); 51 | 52 | // Acquire a token silently 53 | result = await pca 54 | .AcquireTokenSilent(s_scopes, accounts.FirstOrDefault()) \\ Use the account to make the silent call 55 | .ExecuteAsync(CancellationToken.None) 56 | .ConfigureAwait(false); 57 | ``` 58 | 59 | >[!NOTE] 60 | >The environment used to acquire a token can be found using `account.Environment` to create a mapping to respective resource endpoint on the national cloud. 61 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/powershell-support.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using MSAL.NET with PowerShell 3 | description: "How to use MSAL.NET to acquire tokens from a PowerShell script." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Using MSAL.NET with PowerShell 17 | 18 | There is **no official PowerShell module or wrapper** for MSAL libraries maintained by the Entra SDK team. Consider using maintained higher level SDKs: 19 | 20 | - [Microsoft Graph PowerShell SDK](/powershell/microsoftgraph/installation) 21 | - [Azure PowerShell SDK](/powershell/azure/new-azureps-module-az) 22 | 23 | PowerShell was designed to be able to call into .NET code and there are [additional resources](https://stackoverflow.com/questions/3079346/how-to-reference-net-assemblies-using-powershell) that describe how to do this. 24 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/ssh-certificates.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using SSH certificates with MSAL.NET 3 | description: "Microsoft Entra ID is capable of issuing SSH certificates instead of bearer tokens." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Using SSH certificates with MSAL.NET 17 | 18 | >[!NOTE] 19 | >This feature is available from MSAL 4.3.2 onward 20 | 21 | Microsoft Entra ID is capable of issuing SSH certificates instead of bearer tokens. These are not the same as SSH public keys. Currently this is available as an extension method on `AcquireTokenSilent` and `AcquireTokenInteractive`. 22 | 23 | ```csharp 24 | var result = await pca 25 | .AcquireTokenSilent(s_scopes, account) 26 | .WithSSHCertificateAuthenticationScheme(jwk, "keyID1") 27 | .ExecuteAsync(); 28 | ``` 29 | 30 | Paramters: 31 | 32 | - `jwk` - The public SSH key in JWK format as described at https://tools.ietf.org/html/rfc7517 . Currently only RSA with a minimum key size of 2048 bytes is supported. 33 | - `keyID` - Any string that distinguishes between keys (usually hash of the key, but format is not important) 34 | 35 | Example creating a JWK 36 | 37 | ```csharp 38 | private string CreateJwk() 39 | { 40 | RSACryptoServiceProvider rsa = new RSACryptoServiceProvider(2048); 41 | RSAParameters rsaKeyInfo = rsa.ExportParameters(false); 42 | 43 | // Algorithm behind Base64UrlHelpers.Encode is described here https://www.rfc-editor.org/rfc/rfc7515.html#appendix-C 44 | string modulus = Base64UrlHelpers.Encode(rsaKeyInfo.Modulus); 45 | string exp = Base64UrlHelpers.Encode(rsaKeyInfo.Exponent); 46 | string jwk = $"{{\"kty\":\"RSA\", \"n\":\"{modulus}\", \"e\":\"{exp}\"}}"; 47 | 48 | return jwk; 49 | } 50 | ``` 51 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/testing-apps-using-msal.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Testing applications using MSAL.NET 3 | description: "How to test applications that use MSAL.NET for token acquisition." 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Testing applications using MSAL.NET 17 | 18 | ## Unit testing 19 | 20 | MSAL.NET's API uses the builder pattern heavily. Builders are difficult and tedious to mock. Instead, we recommend that you wrap all your authentication logic behind an interface and mock that in your app. 21 | 22 | ## End-to-end testing 23 | 24 | For end to end testing, you can setup test accounts, test applications or even separate directories. Username and passwords can be deployed via the Continuous Integration pipeline (e.g. secret build variables in Azure DevOps). Another strategy is to keep test credentials in KeyVault and configure the machine that runs the tests to access KeyVault, for example by installing a certificate. Feel free to use MSAL's [strategy for accessing KeyVault](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/master/tests/Microsoft.Identity.Test.LabInfrastructure/KeyVaultSecretsProvider.cs#L112). 25 | 26 | Note that once token acquisition occurs, both an Access Token and a Refresh Token are cached. The first has a lifetime of 1h, the latter of several months. When the Access Token expires, MSAL will automatically use the Refresh Token to acquire a new one, without user interaction. You can rely on this behaviour to provision your tests. 27 | 28 | If you have Conditional Access configured, automating around it will be difficult. It will be easier to have a manual step that deals with Conditional Access (e.g. MFA), which will add tokens to the MSAL cache and then rely on silent token acquisitions, i.e. rely on a pre-logged in user. 29 | 30 | ### Web apps 31 | 32 | **Strategy 1**: Use Selenium or an equivalent technology to automate your web app. Fetch usernames and password from KeyVault. 33 | 34 | Pros: end to end testing with real tokens 35 | 36 | Cons: UI automation is flaky. It's tedious to automate the login screens. Live accounts and "Work and School" have slightly different UI flows. 37 | 38 | **Strategy 2**: Use ROPC (Username/Password flow) to get tokens and test only your controllers. Microsoft does not recommend using the ROPC flow in production as it presents some security risks not present in other flows. Use this flow for testing purposes only. 39 | 40 | Pros: No ui automation 41 | 42 | Cons: Does not work for Live accounts, where ROPC is not supported. 43 | 44 | **Strategy 3**: Login manually to prepopulate the token cache. Call `AcquireTokenSilent` to get a fresh access token based on the refresh token **silently**. Refresh tokens are valid for 90 days, but they are also refreshed. 45 | 46 | Pros: no ui automation; works for both "Live" and "Work and School" accounts; 47 | 48 | Cons: some Conditional Access policies will not work cross machine; some manual setup at first; 49 | 50 | Sample showcasing token cache sharing between apps: https://github.com/Azure-Samples/ms-identity-dotnet-advanced-token-cache 51 | 52 | ### Daemon apps 53 | 54 | Daemon apps use pre-deployed secrets (passwords or certificates) to talk to Microsoft Entra ID. You can deploy a secret to your test environment or use the token caching technique to provision your tests. Note that the Client Credential Grant, used by daemon apps, does NOT fetch refresh tokens, just access tokens, which expire in 1h. 55 | 56 | ### Native client apps 57 | 58 | For native clients, there are several approaches to testing: 59 | 60 | - Use the [Username / Password](../acquiring-tokens/desktop-mobile/username-password-authentication.md) grant to fetch a token in a non-interactive way. This flow is not recommended in production, but it is reasonable to use it for testing. 61 | - Use a framework, like Appium or Xamarin.Test, that provides an automation interface for both your app and the MSAL created browser. 62 | - MSAL exposes an extensibility point that allows developers to inject their own browser experience. The MSAL team uses this internally to test interactive auth scenarios. 63 | 64 | ## Library feedback 65 | 66 | Please [log issues](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues) or ask questions related to testing. Providing a good test experience is one of the goals of the team. 67 | -------------------------------------------------------------------------------- /msal-dotnet-articles/advanced/using-in-azure-functions.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using MSAL.NET with Azure Functions 3 | description: Learn how to use MSAL.NET in Azure Functions 4 | author: Dickson-Mwendia 5 | manager: CelesteDG 6 | ms.author: dmwendia 7 | ms.date: 03/17/2023 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: how-to 12 | ms.custom: devx-track-csharp, aaddev 13 | #Customer intent: 14 | # Customer intent: As an application developer, I want to learn how to use MSAL.NET in Azure Functions 15 | --- 16 | 17 | # Using MSAL.NET with Azure Functions 18 | 19 | When using MSAL.NET in Azure Functions, it can happen that libraries are not copied to the directory. 20 | 21 | You can add `<_FunctionsSkipCleanOutput>true` to your .csproj file to prevent that. 22 | 23 | See details in [Azure/azure-functions-host#5894](https://github.com/Azure/azure-functions-host/issues/5894) 24 | 25 | See also how to build [Azure functions with Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web/wiki/Azure-Functions) 26 | -------------------------------------------------------------------------------- /msal-dotnet-articles/breadcrumb/toc.yml: -------------------------------------------------------------------------------- 1 | - name: Docs 2 | tocHref: / 3 | topicHref: /index 4 | items: 5 | - name: Microsoft Entra 6 | tocHref: /entra/ 7 | topicHref: /entra/index 8 | items: 9 | - name: MSAL 10 | tocHref: /entra/msal/ 11 | topicHref: /entra/msal/index 12 | items: 13 | - name: MSAL.NET 14 | tocHref: /entra/msal/dotnet 15 | topicHref: /entra/msal/dotnet/index 16 | -------------------------------------------------------------------------------- /msal-dotnet-articles/docfx.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "content": [ 4 | { 5 | "files": [ 6 | "**/*.md", 7 | "**/*.yml" 8 | ], 9 | "exclude": [ 10 | "**/obj/**", 11 | "**/includes/**", 12 | "_themes/**", 13 | "_themes.pdf/**", 14 | "**/docfx.json", 15 | "_repo.en-us/**", 16 | "README.md", 17 | "LICENSE", 18 | "LICENSE-CODE", 19 | "ThirdPartyNotices.md", 20 | "SECURITY.md" 21 | ] 22 | } 23 | ], 24 | "resource": [ 25 | { 26 | "files": [ 27 | "**/*.png", 28 | "**/*.jpg", 29 | "**/*.gif" 30 | ], 31 | "exclude": [ 32 | "**/obj/**", 33 | "**/includes/**", 34 | "_themes/**", 35 | "_themes.pdf/**", 36 | "**/docfx.json", 37 | "_repo.en-us/**" 38 | ] 39 | } 40 | ], 41 | "overwrite": [], 42 | "externalReference": [], 43 | "globalMetadata": { 44 | "breadcrumb_path": "/entra/msal/dotnet/breadcrumb/toc.json", 45 | "extendBreadcrumb": true, 46 | "uhfHeaderId": "MSDocsHeader-Entra", 47 | "feedback_system": "GitHub", 48 | "feedback_github_repo": "MicrosoftDocs/microsoft-authentication-library-dotnet", 49 | "feedback_product_url": "https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues", 50 | "recommendations": true, 51 | "recommendation_types": [ 52 | "Training", 53 | "Certification" 54 | ] 55 | }, 56 | "fileMetadata": { 57 | "author": { 58 | "*.md": "localden", 59 | "*/**.md": "localden" 60 | }, 61 | "ms.author": { 62 | "*.md": "ddelimarsky", 63 | "*/**.md": "ddelimarsky" 64 | }, 65 | "ms.service": { 66 | "*.md": "msal", 67 | "*/**.md": "msal" 68 | }, 69 | "titleSuffix": { 70 | "*.md": "Microsoft Authentication Library for .NET", 71 | "*/**.md": "Microsoft Authentication Library for .NET" 72 | }, 73 | "ms.topic": { 74 | "*.md": "conceptual", 75 | "*/**.md": "conceptual" 76 | } 77 | }, 78 | "template": [], 79 | "dest": "msal-dotnet-conceptual" 80 | } 81 | } -------------------------------------------------------------------------------- /msal-dotnet-articles/file-content/example_logging_no_pii.txt: -------------------------------------------------------------------------------- 1 | Info (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:22 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) MSAL MSAL.NetCore with assembly version '4.0.0.0'. CorrelationId(aaaa0000-bb11-2222-33cc-444444dddddd) 2 | Info (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:22 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) === InteractiveParameters Data === 3 | LoginHint provided: False 4 | User provided: False 5 | UseEmbeddedWebView: NotSpecified 6 | ExtraScopesToConsent: 7 | Prompt: select_account 8 | HasCustomWebUi: True 9 | 10 | Info (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:22 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) === InteractiveParameters Data === 11 | LoginHint provided: False 12 | User provided: False 13 | UseEmbeddedWebView: NotSpecified 14 | ExtraScopesToConsent: 15 | Prompt: select_account 16 | HasCustomWebUi: True 17 | 18 | Verbose (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:22 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) [Instance Discovery] Tried to use network cache provider for login.microsoftonline.com. Success? False 19 | Verbose (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:24 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) [Instance Discovery] Tried to use network cache provider for login.microsoftonline.com. Success? True 20 | Verbose (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:24 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) [Instance Discovery] After hitting the discovery endpoint, the network provider found an entry for login.microsoftonline.com ? True 21 | Info (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:24 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) Resolving authority endpoints... Already resolved? - FALSE 22 | Info (False) MSAL 4.0.0.0 MSAL.NetCore Microsoft Windows 10.0.18362 [08/02/2019 08:50:24 - 3518b10a-d79f-4c9e-8b3d-f13560ed16f7] (UnknownClient: 0.0.0.0) Using CustomWebUi to acquire the authorization code 23 | Error Specified argument was out of the range of valid values. 24 | Parameter name: Expected a valid port number, > 0, not 80 25 | Error at NetCoreTestApp.Experimental.SingleMessageTcpListener..ctor(Int32 port) in C:\g\msal\tests\devapps\NetCoreTestApp\Experimental\SingleMessageTcpListener.cs:line 31 26 | at NetCoreTestApp.Experimental.DefaultOsBrowserWebUi.InterceptAuthorizationUriAsync(Uri authorizationUri, Uri redirectUri, CancellationToken cancellationToken) in C:\g\msal\tests\devapps\NetCoreTestApp\Experimental\DefaultOsBrowserWebUi.cs:line 132 27 | at NetCoreTestApp.Experimental.DefaultOsBrowserWebUi.AcquireAuthorizationCodeAsync(Uri authorizationUri, Uri redirectUri, CancellationToken cancellationToken) in C:\g\msal\tests\devapps\NetCoreTestApp\Experimental\DefaultOsBrowserWebUi.cs:line 51 28 | at Microsoft.Identity.Client.UI.CustomWebUiHandler.AcquireAuthorizationAsync(Uri authorizationUri, Uri redirectUri, RequestContext requestContext, CancellationToken cancellationToken) in C:\g\msal\src\Microsoft.Identity.Client\UI\CustomWebUiHandler.cs:line 39 29 | at Microsoft.Identity.Client.Internal.Requests.InteractiveRequest.AcquireAuthorizationAsync(CancellationToken cancellationToken) in C:\g\msal\src\Microsoft.Identity.Client\Internal\Requests\InteractiveRequest.cs:line 111 30 | at Microsoft.Identity.Client.Internal.Requests.InteractiveRequest.ExecuteAsync(CancellationToken cancellationToken) in C:\g\msal\src\Microsoft.Identity.Client\Internal\Requests\InteractiveRequest.cs:line 68 31 | at Microsoft.Identity.Client.Internal.Requests.RequestBase.RunAsync(CancellationToken cancellationToken) in C:\g\msal\src\Microsoft.Identity.Client\Internal\Requests\RequestBase.cs:line 132 32 | at Microsoft.Identity.Client.ApiConfig.Executors.PublicClientExecutor.ExecuteAsync(AcquireTokenCommonParameters commonParameters, AcquireTokenInteractiveParameters interactiveParameters, CancellationToken cancellationToken) in C:\g\msal\src\Microsoft.Identity.Client\ApiConfig\Executors\PublicClientExecutor.cs:line 45 33 | at NetCoreTestApp.Program.FetchTokenAndCallGraphAsync(IPublicClientApplication pca, Task`1 authTask) in C:\g\msal\tests\devapps\NetCoreTestApp\Program.cs:line 217 34 | at NetCoreTestApp.Program.RunConsoleAppLogicAsync(IPublicClientApplication pca) in C:\g\msal\tests\devapps\NetCoreTestApp\Program.cs:line 138 -------------------------------------------------------------------------------- /msal-dotnet-articles/getting-started/best-practices.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Best practices for MSAL.NET 3 | description: Learn the best practices when using MSAL.NET in your application development scenario. 4 | author: cilwerner 5 | manager: CelesteDG 6 | ms.author: cwerner 7 | ms.date: 03/17/2023 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: devx-track-csharp, aaddev 13 | #Customer intent: 14 | # Customer intent: As an application developer, I want to learn the best practices for using MSAL.NET in my development scenario 15 | --- 16 | 17 | 18 | # Best practices for MSAL.NET 19 | 20 | ## Never parse an access token 21 | 22 | While you can have a look at the contents of an access token (for instance, using https://jwt.ms), for education, or debugging purposes, you should never parse an access token as part of your client code. The access token is only meant for the Web API or the resource it was acquired for. In most cases, web APIs use a middleware layer (for instance [Identity model extension for .NET](https://github.com/AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet/wiki) in .NET), as this is complex code, about the protection of your web apps and Web APIs, and you don't want to introduce security vulnerabilities by forgetting some important paths. 23 | 24 | 25 | 26 | ## Don't acquire tokens from Microsoft Entra ID too often 27 | 28 | The standard pattern of acquiring tokens is: (i) acquire a token from the cache silently and (ii) if it doesn't work, acquire a new token from Microsoft Entra ID. If you skip the first step, your app may be acquiring tokens from Microsoft Entra too often. This provides a bad user experience, because it is slow and error prone as the identity provider might throttle you. 29 | 30 | ## Don't handle token expiration on your own 31 | 32 | Even if `AuthenticationResult` returns the expiry of the token, you should not handle the expiration and the refresh of the access tokens on your own. MSAL.NET does this for you. For flows retrieving tokens for a user account, you'd want to use the recommended pattern as these write tokens to the user token cache, and tokens are retrieved and refreshed (if needed) silently by `AcquireTokenSilent` 33 | 34 | ```csharp 35 | AuthenticationResult result; 36 | try 37 | { 38 | // will handle expired Access Tokens by fetching new ones using the Refresh Token 39 | result = await AcquireTokenSilent(scopes).ExecuteAsync(); 40 | } 41 | catch(MsalUiRequiredException ex) 42 | { 43 | result = AcquireTokenXXXX(scopes, ..).WithXXX(…).ExecuteAsync(); 44 | } 45 | ``` 46 | 47 | If you use `AcquireTokenForClient` in the client credentials flow, you don't need to worry about the cache as this method not only stores tokens to the application cache, but also looks them up and refreshes them if needed. This is the only method interacting with the application token cache, the cache for tokens for the application itself. 48 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/build-apps-on-linux-ubuntu.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Building MSAL.NET applications on Linux 3 | description: Building MSAL.NET applications on Linux 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: how-to 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Building MSAL.NET applications on Linux 17 | 18 | Create a console app for linux testing. Right now, it tests [#2839](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/2839). 19 | 20 | ```csharp 21 | class Program 22 | { 23 | public static string ClientID = "your client id"; //msidentity-samples-testing tenant 24 | public static string[] Scopes = { "User.Read" }; 25 | static void Main(string[] args) 26 | { 27 | Console.WriteLine("Hello World!"); 28 | 29 | var pcaBuilder = PublicClientApplicationBuilder.Create(ClientID) 30 | .WithRedirectUri("http://localhost") 31 | .Build(); 32 | 33 | AcquireTokenInteractiveParameterBuilder atparamBuilder = pcaBuilder.AcquireTokenInteractive(Scopes); 34 | 35 | AuthenticationResult authenticationResult = atparamBuilder.ExecuteAsync().GetAwaiter().GetResult(); 36 | System.Console.WriteLine(authenticationResult.AccessToken); 37 | } 38 | } 39 | ``` 40 | 41 | ## How to setup 42 | 43 | On an Ubuntu machine 44 | 45 | - Download VS Code 46 | - Copy the files from the download folder to an "App" folder. 47 | - Download the NuGet package in `~/LocalNuget` folder. 48 | 49 | ## How to build 50 | 51 | From the VS Code terminal: 52 | 53 | - Go to the "App" folder 54 | - Run command 55 | ```dotnet add package Microsoft.Identity.Client --prerelease -s ~/LocalNuget``` 56 | This will add the latest package to the project 57 | - Run command 58 | ```dotnet build``` 59 | This will build the app in debug mode 60 | 61 | ## How to run 62 | 63 | From the PowerShell terminal: 64 | 65 | - Got to `app/bin/Debug/net6` folder. 66 | - Run `dotnet TestApp.dll`. This runs the app. 67 | - To test in sudo mode, run the following command `sudo dotnet TestApp.dll` 68 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/cache-options.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Cache options in MSAL.NET 3 | description: Cache options in MSAL.NET 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Cache options in MSAL.NET 17 | 18 | ## Setting cache options 19 | 20 | ```csharp 21 | 22 | var app = ConfidentialClientApplicationBuilder.Create(ClientId) 23 | .WithCertificate(cert) 24 | .Build(); 25 | 26 | // The App token cache is used by `AcquireTokenForClient`, which gets tokens on behalf of service principals 27 | app.AppTokenCache.SetCacheOptions(CacheOptions.EnableSharedCacheOptions); 28 | 29 | // The User token cache is used by all other AcquireToken* methods, which get tokens on behalf of users 30 | app.UserTokenCache.SetCacheOptions(CacheOptions.EnableSharedCacheOptions); 31 | ``` 32 | 33 | ## Cache options 34 | 35 | `EnableSharedCacheOptions` - makes the cache static, so that it is shared between all instances of `ConfidentialClientApplication`. 36 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/default-reply-uri.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Default reply URI 3 | description: "How to customize the reply URI in applications using MSAL.NET." 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Default reply URI 17 | 18 | In MSAL.NET The default redirect URI (also known as the reply URI) can be set with . This method will set the public client applications redirect uri property to the default recommended redirect uri for public client applications. 19 | 20 | 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: 21 | 22 | | Platform | Redirect URI | 23 | |----------------------------------|-----------------------------------------------------------------------| 24 | | Desktop (.NET Framework) | `https://login.microsoftonline.com/common/oauth2/nativeclient` | 25 | | .NET Core | `http://localhost` | 26 | 27 | For .NET Core, we are setting the value to the local host to enable the user to use the system browser for interactive authentication since .NET Core does not have a UI for the embedded web view at the moment. 28 | 29 | > [!NOTE] 30 | > 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 therefor 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 translate this to another uri as long as you configure the redirect uri correctly with MSAL. Specifying the above in the application registration means there is the least amount of setup in MSAL. 31 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/get-tenant-profiles.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting tenant profiles with MSAL.NET 3 | description: Getting tenant profiles with MSAL.NET 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Getting tenant profiles with MSAL.NET 17 | 18 | Here is a code sample that acquires tokens for the same account, but in different tenant, and then displays the tenants 19 | and the claims of the ID token in each tenant 20 | 21 | ```csharp 22 | using Microsoft.Identity.Client; 23 | using System; 24 | using System.Threading.Tasks; 25 | 26 | class Program 27 | { 28 | static async Task Main(string[] args) 29 | { 30 | IPublicClientApplication app = PublicClientApplicationBuilder.Create("4a1aa1d5-c567-49d0-ad0b-cd957a47f842") 31 | .WithDefaultRedirectUri() 32 | .Build(); 33 | 34 | // Authenticate in my home tenant (Authority is 'common') 35 | AuthenticationResult result = await app.AcquireTokenInteractive(new[] { "user.read" }) 36 | .ExecuteAsync(); 37 | 38 | // Get a new token for myself, but in another tenant. 39 | result = await app.AcquireTokenSilent(new[] { "user.read" }, result.Account) 40 | .WithAuthority(app.Authority.Replace("common", "msidentitysamplestesting.onmicrosoft.com")) 41 | .ExecuteAsync(); 42 | 43 | // Display tenants, and claims 44 | foreach (var tenantProfile in result.Account.GetTenantProfiles()) 45 | { 46 | Console.WriteLine($"Tenant= {tenantProfile.TenantId}"); 47 | foreach(var claim in tenantProfile.ClaimsPrincipal.Claims) 48 | { 49 | Console.WriteLine($" {claim.Type}={claim.Value}"); 50 | } 51 | } 52 | } 53 | } 54 | ``` 55 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/install-nuget-custom-source.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Installing MSAL.NET from custom NuGet package source 3 | description: "How to install NuGet from a source other than the NuGet package feed." 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: concept-article 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Installing MSAL.NET from custom NuGet package source 17 | 18 | There are times when you need to take a dependency on a non official version of MSAL: 19 | 20 | * A MSAL developer hands has put in a fix for a bug and would like you to validate it 21 | * You are making changes to MSAL on your own, package MSAL and want to try it out with an app 22 | 23 | ## Install a package from a local source 24 | 25 | The easiest approach is to use a [local folder](/nuget/hosting-packages/local-feeds) as a NuGet package source. This enables developers to read content from their own machine without uploading the package to a remote server. 26 | 27 | ## What not to do 28 | 29 | * Do not extract the `*.nupkg` file and take a reference on the dynamic linked library (DLL) itself - there are many DLLs in the package and you might use the wrong one. 30 | * Do not try to copy, paste, or rename the new package over an existing package in the NuGet cache - you'll have problems moving away from the non-official version back to an official version and clearing out the cache properly. 31 | 32 | ## Check the signatures 33 | 34 | You should check that a package is signed. MSAL has to be signed by Microsoft. NuGet will display this information and you can always check a package with a tool such as [NuGet Package Explorer](https://github.com/NuGetPackageExplorer/NuGetPackageExplorer). Microsoft will always sign both packages as well as the DLLs inside, even for non-official and preview releases. 35 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/override-target-framework.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overriding target framework 3 | description: "In rare circumstances you might want to override NuGet's algorithm of determining the framework version of MSAL." 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Overriding target framework 17 | 18 | In rare circumstances you might want to override NuGet's algorithm of determining the framework version of MSAL. This is useful if you have a confidential client application and need to target `net5.0-windows10.x` because MSAL uses Windows Forms on these platforms, which leads to build errors in some environments (e.g., Azure Functions). 19 | 20 | Please see the [`TfmOverride`](https://github.com/bgavrilMS/TfmOverride) project for a sample that shows how to implement the requirement. -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/overriding-authority.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overriding authority 3 | description: "How to override the default authority in MSAL.NET applications." 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Overriding authority 17 | 18 | In many scenarios, such as [client credential flow in multi-tenant apps](../advanced/client-credential-multi-tenant.md), it is useful to specify the Microsoft Entra tenant in the request builder instead of the application builder. `WithTenantId` is the recommended API to use in this scenario, which accepts the tenant ID string. `WithTenantIdFromAuthority` is another similar method that is available in MSAL 4.46.0+. You can also use `WithAuthority`, however, the authority in the application and the request builders must always be for the same cloud, i.e. the host of the authority URL must not be different. 19 | 20 | ```csharp 21 | var app = ConfidentialClientApplicationBuilder 22 | .Create(PublicCloudConfidentialClientID) 23 | .WithAuthority("https://login.microsoftonline.com/common", true) 24 | .Build(); 25 | 26 | var result = await app.AcquireTokenForClient(scopes) 27 | .WithTenantId("123456-1234-2345-1234561234"); 28 | // OR 29 | var result = await app.AcquireTokenForClient(scopes) 30 | .WithTenantIdFromAuthority("https://login.microsoftonline.com/123456-1234-2345-1234561234"); 31 | ``` 32 | 33 | A public or confidential client application instance can only be associated with one cloud. If your client application needs to handle multiple clouds at the same time, create a separate public or confidential client instance for each of them. 34 | -------------------------------------------------------------------------------- /msal-dotnet-articles/how-to/synchronous-programming.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Synchronous programming with MSAL.NET 3 | description: "MSAL.NET is based on Task-based Asynchronous Pattern (TAP). This page provides links to guidance about how to use async methods in a synchronous way. This has no one solution that fits all. So various best practices are recommended." 4 | author: cilwerner 5 | manager: 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: how-to 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Synchronous programming with MSAL.NET 17 | 18 | It is strongly recommended to use async programming practices for better performance and responsive apps. However, some legacy apps cannot use asynchronous programming. 19 | 20 | MSAL.NET is based on Task-based Asynchronous Pattern (TAP). This page provides links to guidance about how to use async methods in a synchronous way. This has no one solution that fits all. So various best practices are recommended. 21 | 22 | ## Asynchronous programming 23 | 24 | If you are not familiar with asynchronous programming, check out [Asynchronous programming with async and await](/dotnet/csharp/programming-guide/concepts/async/). 25 | 26 | You can also check out the [Advanced Programming in C#](https://www.linkedin.com/learning/async-programming-in-c-sharp/introduction?u=3322) course on LinkedIn. 27 | 28 | ## Calling Asynchronous methods from synchronous code 29 | 30 | There are several ways to run asynchronous code from a synchronous code. Various links are listed here. 31 | 32 | [Task.RunSynchronously](/dotnet/api/system.threading.tasks.task.runsynchronously) 33 | 34 | ```csharp 35 | var getAcctsTasks = PCA.RemoveAsync(acct); 36 | // there is no timeout for RunSynchronously 37 | if (!getAcctsTasks.IsCompleted) 38 | { 39 | getAcctsTasks.RunSynchronously(); 40 | } 41 | ``` 42 | 43 | [Wait for a task to complete with Task.Wait](/dotnet/api/system.threading.tasks.task.wait) 44 | 45 | ```csharp 46 | // wait can optionally have timeout, and cancellation token (not shown) 47 | int timeoutMilliSec = 3000; 48 | PCA.RemoveAsync(acct).Wait(timeoutMilliSec); 49 | ``` 50 | 51 | [Wait to get result with Task.Result](/dotnet/api/system.threading.tasks.task-1.result#remarks) 52 | 53 | ```csharp 54 | var authResult = PCA.AcquireTokenSilent(Scopes, acct).ExecuteAsync().Result; 55 | return authResult; 56 | ``` 57 | 58 | If you need to run multiple tasks at a time prior to wrapping them, it may be useful to take a look at [Consuming the Task-based Asynchronous Pattern](/dotnet/standard/asynchronous-programming-patterns/consuming-the-task-based-asynchronous-pattern). 59 | 60 | ## Watch out for exceptions and deadlocks 61 | 62 | Here is how to catch exceptions and prevent deadlocks with `.ConfigureAwait(false)`. 63 | 64 | ```csharp 65 | try 66 | { 67 | Console.WriteLine("Pre AcquireTokenInteractive"); 68 | // Run with wait command 69 | // create the builder 70 | var builder = PCA.AcquireTokenInteractive(Scopes); 71 | 72 | // run it interactively. 73 | // make sure to have ConfigureAwait(false) to avoid any potential deadlocks 74 | var authResult = builder.ExecuteAsync() 75 | .ConfigureAwait(false) 76 | .GetAwaiter() 77 | .GetResult(); 78 | Console.WriteLine("Post AcquireTokenInteractive - Got the token"); 79 | 80 | return result; 81 | } 82 | catch (MsalClientException ex) 83 | { 84 | // catch MSAL exception 85 | Console.WriteLine(ex.Message); 86 | } 87 | catch (Exception ex) 88 | { 89 | Console.WriteLine(ex.Message); 90 | } 91 | ``` 92 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/adal-migration-note.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: cilwerner 3 | manager: 4 | ms.author: cwerner 5 | ms.date: 05/22/2025 6 | ms.service: msal 7 | ms.subservice: msal-dotnet 8 | ms.reviewer: 9 | ms.topic: include 10 | ms.custom: 11 | #Customer intent: 12 | --- 13 | 14 | >[!WARNING] 15 | >Azure Active Directory Authentication Library (ADAL) **has been deprecated**. While existing apps that use ADAL will continue to work, Microsoft will no longer release security fixes on ADAL. Use the [Microsoft Authentication Library (MSAL)](/entra/msal/) to avoid putting your app's security at risk. 16 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/error-handling-claims-challenges.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: cilwerner 3 | manager: 4 | ms.author: cwerner 5 | ms.date: 05/22/2025 6 | ms.service: msal 7 | ms.subservice: msal-dotnet 8 | ms.reviewer: 9 | ms.topic: include 10 | ms.custom: 11 | #Customer intent: 12 | # Purpose: 13 | # Ingested by Microsoft identity platform articles in /articles/active-directory/develop/* that document the error handling Conditional Access and claims challenges for the different platforms. 14 | --- 15 | ## Conditional Access and claims challenges 16 | 17 | When getting tokens silently, your application may receive errors when a [Conditional Access claims challenge](/azure/active-directory/develop/v2-conditional-access-dev-guide) such as MFA policy is required by an API you're trying to access. 18 | 19 | The pattern for handling this error is to interactively acquire a token using MSAL. This prompts the user and gives them the opportunity to satisfy the required Conditional Access policy. 20 | 21 | In certain cases when calling an API requiring Conditional Access, you can receive a claims challenge in the error from the API. For instance if the Conditional Access policy is to have a managed device (Intune) the error will be something like [AADSTS53000: Your device is required to be managed to access this resource](/azure/active-directory/develop/reference-error-codes) or something similar. In this case, you can pass the claims in the acquire token call so that the user is prompted to satisfy the appropriate policy. 22 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/error-handling-introduction.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: cilwerner 3 | manager: 4 | ms.author: cwerner 5 | ms.date: 11/25/2020 6 | ms.service: msal 7 | ms.subservice: msal-dotnet 8 | ms.reviewer: 9 | ms.topic: include 10 | ms.custom: 11 | #Customer intent: 12 | --- 13 | 14 | This article gives an overview of the different types of errors and recommendations for handling common sign-in errors. 15 | 16 | ## MSAL error handling basics 17 | 18 | Exceptions in Microsoft Authentication Library (MSAL) are intended for app developers to troubleshoot, not for displaying to end users. Exception messages are not localized. 19 | 20 | When processing exceptions and errors, you can use the exception type itself and the error code to distinguish between exceptions. For a list of error codes, see [Microsoft Entra authentication and authorization error codes](/azure/active-directory/develop/reference-error-codes). 21 | 22 | During the sign-in experience, you may encounter errors about consents, Conditional Access (MFA, Device Management, Location-based restrictions), token issuance and redemption, and user properties. 23 | 24 | The following section provides more details about error handling for your app. 25 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/error-handling-retries.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: cilwerner 3 | manager: 4 | ms.author: cwerner 5 | ms.date: 05/22/2025 6 | ms.service: msal 7 | ms.subservice: msal-dotnet 8 | ms.reviewer: 9 | ms.topic: include 10 | ms.custom: 11 | #Customer intent: 12 | # Purpose: 13 | # Ingested by Microsoft identity platform articles in /articles/active-directory/develop/* that document the error handling retries for the different platforms. 14 | --- 15 | ## Retrying after errors and exceptions 16 | 17 | You're expected to implement your own retry policies when calling MSAL. MSAL makes HTTP calls to the Microsoft Entra service, and occasionally failures can occur. For example the network can go down or the server is overloaded. 18 | 19 | ### HTTP 429 20 | 21 | 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. 22 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/importance-of-logging.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: cilwerner 3 | manager: 4 | ms.author: cwerner 5 | ms.date: 05/22/2025 6 | ms.service: msal 7 | ms.subservice: msal-dotnet 8 | ms.reviewer: 9 | ms.topic: include 10 | ms.custom: 11 | #Customer intent: 12 | --- 13 | 14 | ## Importance of logging with MSAL 15 | 16 | Among its many capabilities, Microsoft Authentication Library (MSAL) has robust built-in [logging features](../advanced/exceptions/msal-logging.md). Enabling logging in your applications ensures that you have a direct line of sight on any authentication issues and can both diagnose them easier for your own application and help the MSAL team quickly address potential problems. We strongly recommend that you enable logging for your applications when deployed in any production scenarios. 17 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/msal-net-adoption-steps-confidential-clients.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: cilwerner 3 | manager: 4 | ms.author: cwerner 5 | ms.date: 05/22/2025 6 | ms.service: msal 7 | ms.subservice: msal-dotnet 8 | ms.reviewer: 9 | ms.topic: include 10 | ms.custom: 11 | #Customer intent: 12 | --- 13 | 14 | The following steps for updating code apply across all the confidential client scenarios: 15 | 16 | 1. Add the MSAL.NET namespace in your source code: `using Microsoft.Identity.Client;`. 17 | 2. Instead of instantiating `AuthenticationContext`, use `ConfidentialClientApplicationBuilder.Create` to instantiate `IConfidentialClientApplication`. 18 | 3. Instead of the `resourceId` string, MSAL.NET uses scopes. Because applications that use ADAL.NET are preauthorized, you can always use the following scopes: `new string[] { $"{resourceId}/.default" }`. 19 | 4. Replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IConfidentialClientApplication.AcquireTokenXXX`, where *XXX* depends on your scenario. 20 | -------------------------------------------------------------------------------- /msal-dotnet-articles/includes/msal-net-adoption-steps-public-clients.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Common steps for public client migration to MSAL 3 | description: Include file that explains the common steps you need to take for all public client apps when it comes to migration from ADAL to MSAL. 4 | author: cilwerner 5 | manager: CelesteDG 6 | ms.author: cwerner 7 | ms.date: 05/22/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: include 12 | ms.custom: aaddev 13 | #Customer intent: 14 | --- 15 | 16 | The following steps for updating code apply across all the confidential client scenarios: 17 | 18 | 1. Add the MSAL.NET namespace in your source code: `using Microsoft.Identity.Client;`. 19 | 2. Instead of instantiating `AuthenticationContext`, use `PublicClientApplicationBuilder.Create` to instantiate `IPublicClientApplication`. 20 | 3. Instead of the `resourceId` string, MSAL.NET uses scopes. Because applications that use ADAL.NET are preauthorized, you can always use the following scopes: `new string[] { $"{resourceId}/.default" }`. 21 | 4. Replace the call to `AuthenticationContext.AcquireTokenAsync` with a call to `IPublicClientApplication.AcquireTokenXXX`, where *XXX* depends on your scenario. -------------------------------------------------------------------------------- /msal-dotnet-articles/media/a-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/a-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/access-token-fiddler.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/access-token-fiddler.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/aspnet-core-project-templates.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/aspnet-core-project-templates.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/auth-parameters-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/auth-parameters-diagram.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/authenticationresult-graph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/authenticationresult-graph.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/azure-ad-b2c-appsettings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/azure-ad-b2c-appsettings.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/azure-ad-b2c-controller.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/azure-ad-b2c-controller.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/azure-ad-calling-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/azure-ad-calling-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/azure-ad-certificates.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/azure-ad-certificates.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/azure-ad-client-type.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/azure-ad-client-type.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/certificate-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/certificate-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/complex-web-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/complex-web-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/configureservices-startup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/configureservices-startup.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/console-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/console-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/daemon-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/daemon-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/daemon-certificate-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/daemon-certificate-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/daemon-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/daemon-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/desktop-web-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/desktop-web-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/device-code-flow-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/device-code-flow-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/devicecoderesult-class.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/devicecoderesult-class.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/errorList.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/errorList.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/groupmanager-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/groupmanager-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/iconfidentialclientapplication-interface.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/iconfidentialclientapplication-interface.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/idweb-msal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/idweb-msal.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/ipublicclientapplication-interface.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/ipublicclientapplication-interface.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/iwa-console-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/iwa-console-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/latency-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/latency-diagram.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/linux/dotnet-msal-wsl.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/linux/dotnet-msal-wsl.gif -------------------------------------------------------------------------------- /msal-dotnet-articles/media/linux/linux-entra-login.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/linux/linux-entra-login.gif -------------------------------------------------------------------------------- /msal-dotnet-articles/media/loggerTypes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/loggerTypes.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-compare-msaldotnet-and-adaldotnet/differences.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-compare-msaldotnet-and-adaldotnet/differences.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-exceptions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-exceptions.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-folder-content.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-folder-content.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-logging/fiddler-exempt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-logging/fiddler-exempt.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-logging/msft-sts-fiddler.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-logging/msft-sts-fiddler.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-logging/otel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-logging/otel.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-migration/confidential-client-application.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-migration/confidential-client-application.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-migration/decision-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-migration/decision-diagram.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-token-cache-serialization/class-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-token-cache-serialization/class-diagram.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-token-cache-serialization/topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-token-cache-serialization/topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-use-brokers-with-xamarin-apps/portal-01-ios-platform-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-use-brokers-with-xamarin-apps/portal-01-ios-platform-settings.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-uwp-considerations/topology-native-uwp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-uwp-considerations/topology-native-uwp.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-uwp-considerations/topology-xamarin-native.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-uwp-considerations/topology-xamarin-native.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-web-browsers/embedded-webview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-web-browsers/embedded-webview.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-net-web-browsers/system-browser.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-net-web-browsers/system-browser.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-serializers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-serializers.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/msal-templates-support.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/msal-templates-support.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/nativeinterop-library.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/nativeinterop-library.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-api-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-api-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-app-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-app-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-daemon-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-daemon-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-desktop-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-desktop-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-iot-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-iot-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-mobile-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-mobile-api.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/net-oauth.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/net-oauth.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/obo-flow-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/obo-flow-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/on-behalf-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/on-behalf-flow.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/p-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/p-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/proof-of-possession-tokens/example-www-authenticate-headers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/proof-of-possession-tokens/example-www-authenticate-headers.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/ropc-enable-azure-portal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/ropc-enable-azure-portal.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/user-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/user-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/user-sync-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/user-sync-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/uwp-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/uwp-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wam-demo.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wam-demo.gif -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wam-per-tenant.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wam-per-tenant.gif -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wsl1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wsl1.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wsl2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wsl2.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wsl3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wsl3.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wsl4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wsl4.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wsl5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wsl5.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wam/wsl6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wam/wsl6.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/web-api-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/web-api-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/web-app-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/web-app-icon.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/web-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/web-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/wpf-app-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/wpf-app-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/media/xamarin-forms-topology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/microsoft-authentication-library-dotnet/fd2d8a56dd6eaa76e8147eb8fb99837970cbfd46/msal-dotnet-articles/media/xamarin-forms-topology.png -------------------------------------------------------------------------------- /msal-dotnet-articles/microsoft-identity-web/getting-started/scenarios.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Microsoft Identity Web scenarios 3 | description: Learn the application scenarios and authentication flows supported by Microsoft Identity Web. 4 | author: Dickson-Mwendia 5 | manager: CelesteDG 6 | ms.author: dmwendia 7 | ms.date: 03/17/2023 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: devx-track-csharp, aaddev 13 | # Customer intent: As an application developer, I want to know the application scenarios and authentication flows supported by Microsoft Identity Web. 14 | --- 15 | 16 | # Microsoft identity web scenarios 17 | 18 | ## Introduction 19 | 20 | Microsoft.Identity.Web proposes a higher level API, over MSAL.NET, to protect web APIs, and acquire tokens in web apps, web APIs and services/daemon apps. You can choose to describe your application through a configuration file, or programmatically, or use a combination of both approaches. 21 | 22 | ## The Scenarios 23 | 24 | Microsoft identity web is focused on services, and confidential client applications. 25 | 26 | ### Web app that signs in users and calls a web API on behalf of the user 27 | 28 | To protect a web app (signing in the user) you'll use ASP.NET or ASP.NET Core with the ASP.NET Open ID Connect middleware. You'll reference the [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) NuGet package if you use ASP.NET Core, and [Microsoft.Identity.Web.OWIN](https://www.nuget.org/packages/Microsoft.Identity.Web.OWIN) if you are still using ASP.NET (OWIN). 29 | 30 | If moreover, your web apps call web APIs in the name of the user (or as itself), you'll add the following NuGet packages: 31 | 32 | - [Microsoft.Identity.Web.MicrosoftGraph](https://www.nuget.org/packages/Microsoft.Identity.Web.MicrosoftGraph) if you want to call Microsoft Graph 33 | - [Microsoft.Identity.Web.Azure](https://www.nuget.org/packages/Microsoft.Identity.Web.Azure) if you want to access an Azure resource with one of the Azure SDKs (Storage, etc ...) 34 | - [Microsoft.Identity.Web.DownstreamApi](https://www.nuget.org/packages/Microsoft.Identity.Web.DownstreamApi) if you want to call a downstream web API 35 | 36 | ### Desktop or service daemon app that calls a web API as itself (in its own name) 37 | 38 | You can write a daemon app that acquires a token using its own identity with a few lines of code, using the [Microsoft.Identity.Web.TokenAcquisition](https://www.nuget.org/packages/Microsoft.Identity.Web.TokenAcquisition) Nuget package. 39 | 40 | ### Web API calling another downstream Web API in the name of the user for whom it was called, or in its own name 41 | 42 | To protect a web API you'll use ASP.NET or ASP.NET Core. You'll reference the [Microsoft.Identity.Web](https://www.nuget.org/packages/Microsoft.Identity.Web) NuGet package if you use ASP.NET Core, and [Microsoft.Identity.Web.OWIN](https://www.nuget.org/packages/Microsoft.Identity.Web.OWIN) if you are still using ASP.NET (OWIN). 43 | 44 | If moreover, your web apps calls web APIs in the name of the user (or in its own name), you'll add the following NuGet packages: 45 | 46 | - [Microsoft.Identity.Web.MicrosoftGraph](https://www.nuget.org/packages/Microsoft.Identity.Web.MicrosoftGraph) if you want to call Microsoft Graph 47 | - [Microsoft.Identity.Web.Azure](https://www.nuget.org/packages/Microsoft.Identity.Web.Azure) if you want to access an Azure resource with one of the Azure SDKs (Storage, etc ...) 48 | - [Microsoft.Identity.Web.DownstreamApi](https://www.nuget.org/packages/Microsoft.Identity.Web.DownstreamApi) if you want to call a downstream web API -------------------------------------------------------------------------------- /msal-dotnet-articles/resources/handling-pii.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Handling of personally-identifiable information in MSAL.NET 3 | description: Outlines what MSAL considers to be personally identifiable information. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: sfi-ropc-nochange 13 | #Customer intent: 14 | --- 15 | 16 | # Handling of personally-identifiable information in MSAL.NET 17 | 18 | ## Data classification 19 | 20 | Microsoft defines the following [data classification](https://www.microsoft.com/trust-center/privacy/customer-data-definitions). MSAL libraries, for simplicity, expose a single PII (personally identifiable information) enablement flag for logging. This single flag combines all categories covered by the data classification document. 21 | 22 | ## Logging approach 23 | 24 | To read more about how MSAL.NET does logging, refer to [Logging in MSAL.NET](../advanced/exceptions/msal-logging.md). Specifically, logging data that contains personally-identifiable information (PII) will require the use of the `enablePiiLogging` flag when using . 25 | 26 | >[!NOTE] 27 | >Using `enablePiiLogging` will influence what PII is shown in MSAL exception messages, including those that stem from the [using the Web Account Manager (WAM)](../acquiring-tokens/desktop-mobile/wam.md). This also coveres end-user identifiable information (EUII), such as UPN, name, or email. 28 | 29 | ## What MSAL will never log 30 | 31 | - Tokens, including access tokens, ID tokens, refresh tokens, and client assertions generated by MSAL. 32 | - Passwords, as MSAL is only given the password during the username and password flow. MSAL does not have access to the password entered by the user in a browser. 33 | - Authorization codes. 34 | - PKCE code. 35 | - Successful network responses from the `/authorize` or `/token` endpoints because they may contain tokens or auth codes. 36 | - Network requests, as they may contain passwords. 37 | - Private keys of certificates. 38 | 39 | ## What MSAL considers as PII 40 | 41 | - Username. 42 | - Login hint. 43 | - ID token claims, which include names, address, or other user details. MSAL only parses the ID token, it never looks at access or refresh tokens. 44 | - Authorization URI, as it may contain a login hint. 45 | - Object ID (i.e. `oid` claim). 46 | 47 | ## What MSAL does not consider as PII 48 | 49 | - IDs related to an organization or tenant (not the user) like tenant ID, directory ID, or directory name (e.g. `contoso.onmicrosoft.com`). 50 | - Authority. 51 | - Scopes and resource names. 52 | - Client (application) ID. 53 | - Service principal details, such as object ID and client ID. 54 | - Exception messages and stack traces, including error codes coming from Microsoft Entra ID. 55 | - HTTP details other than request and response (for example, HTTP status codes or payload size). 56 | - Correlation IDs. 57 | - Runtime details, such as OS name, .NET platform version. 58 | - Internal API details, such as class names, method names. 59 | - Request details, such as algorithm names (e.g. RSA) or OIDC constants. 60 | - Certificate thumbprints other than key IDs. 61 | 62 | ## PII in exceptions 63 | 64 | MSAL generates exception messages that do not contain PII. instances, generated by MSAL or passed from Microsoft Entra ID, are considered to not contain PII. 65 | 66 | Some framework exception may contain PII, although this is rare (e.g. a `PathInvalidException` may contain the username). MSAL takes care to not log framework exceptions which may contain PII. 67 | 68 | ## Organization identifiable information 69 | 70 | MSAL can log organization identifiable information (OII) because, as per the official data classification, organization identifiable information is not considered PII. OII includes data like tenant ID, object ID for service principals, or scope names. The application developer still controls the destination of this logging data. 71 | -------------------------------------------------------------------------------- /msal-dotnet-articles/resources/known-issues.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Known issues with MSAL.NET 3 | description: Troubleshoot MSAL.NET with our guide on known issues, including device compliance failures, AndroidActivityNotFound exceptions, and build issues. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Known issues with MSAL.NET 17 | 18 | MSAL throws a few types of exceptions, please see [Exceptions](../advanced/exceptions/index.md). 19 | 20 | ## Confidential Client 21 | 22 | Please read the guide on [High Availability](../advanced/high-availability.md). 23 | 24 | ## Public Client 25 | 26 | ### Device Compliance failures on Windows 10 27 | 28 | Users are unable to login interactively and a "Device is not compliant" error is shown when: 29 | 30 | * The tenant admin has enabled the "Require device to be marked as compliant" Conditional Access policy 31 | * The app is invoking public client flows (i.e. rich client apps, not web sites) 32 | * The app is using the embedded browser control available in ADAL or MSAL (this is the default for .NET Framework apps) 33 | 34 | #### Mitigation 35 | 36 | * The recommended approach is to use [WAM](../acquiring-tokens/desktop-mobile/wam.md). 37 | * You can also configure MSAL to use the system (default OS) browser. Details in [Using web browsers (MSAL.NET)](/azure/active-directory/develop/msal-net-web-browsers#how-to-use-the-default-os-browser). Both Microsoft Edge and Chrome browsers are able to satisfy the device policy. 38 | * If using ADAL, [**migrate to MSAL**](/entra/identity-platform/msal-migration). There is no mitigation for ADAL. 39 | 40 | ### Android 41 | 42 | On Android, an `AndroidActivityNotFound` exception is thrown when the device does not have a browser with tabs. See [Xamarin Android system browser considerations for using MSAL.NET](/azure/active-directory/develop/msal-net-system-browser-android-considerations#known-issues) 43 | 44 | ### iOS 45 | 46 | Please see [Xamarin iOS Considerations](/azure/active-directory/develop/msal-net-xamarin-ios-considerations#known-issues-with-ios-12-and-authentication). 47 | 48 | ### Desktop 49 | 50 | On a Desktop app, a `StateMismatchError` exception is thrown when the using a long Facebook ID (via B2C) in conjunction with the embedded browser. 51 | For more details, please [refer to our documentation](../advanced/exceptions/understanding-statemismatcherror.md). 52 | 53 | ## Build issues 54 | 55 | Behavior: an error similar to `Microsoft.Windows.SDK.Contracts.targets(4,5): error : Must use PackageReference` is thrown 56 | 57 | Starting with version 4.23, MSAL references `Microsoft.Windows.SDK.Contracts`. NuGet can only resolve this reference if the application consuming MSAL references it as `` and not via the legacy `packages.config` mechanism. See [#2247](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/issues/2247) for details on how to fix this. 58 | -------------------------------------------------------------------------------- /msal-dotnet-articles/resources/region-discovery-troubleshooting.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Region discovery troubleshooting 3 | description: Troubleshoot regional STS (ESTS-Regional) in Microsoft Entra ID. Learn about the service-to-service flow and opt-in process for first-party apps. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | #Customer intent: 13 | 14 | --- 15 | 16 | # Region discovery troubleshooting 17 | 18 | Microsoft Entra ID has adding support for regional STS (ESTS-Regional). Currently only the service to service flow (client_credentials / AcquireTokenForClient) is available via opt-in only to first party apps. 19 | 20 | For more details refer to [internal guidance](https://aka.ms/msal/estsr/guidance). 21 | -------------------------------------------------------------------------------- /msal-dotnet-articles/resources/semantic-versioning-api-change-management.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Semantic versioning and API change management 3 | description: "MSAL.NET strategy for versioning library releases" 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # Semantic versioning and API change management 17 | 18 | MSAL.NET has adopted [semantic versioning](https://semver.org/), the industry standard for open-source projects. 19 | 20 | Per the semantic versioning specification, breaking changes (i.e., incompatible changes) will only be released with a major version bump. When that happens, we will document that change in the [release notes](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/releases). 21 | -------------------------------------------------------------------------------- /msal-dotnet-articles/resources/telemetry-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: MSAL.NET telemetry overview 3 | description: Explore MSAL.NET's telemetry capabilities for Microsoft Entra token endpoint requests. Learn about client-side state, error tracking, and SDK API usage metadata. 4 | author: Dickson-Mwendia 5 | manager: 6 | ms.author: dmwendia 7 | ms.date: 05/20/2025 8 | ms.service: msal 9 | ms.subservice: msal-dotnet 10 | ms.reviewer: 11 | ms.topic: reference 12 | ms.custom: 13 | #Customer intent: 14 | --- 15 | 16 | # MSAL.NET telemetry overview 17 | 18 | MSAL.NET sends basic telemetry about the client side state on requests to the Microsoft Entra token endpoint. Telemetry data will be logged by Microsoft Entra ID. This telemetry will give us visibility into both first and third party app health without introducing an additional telemetry pipeline dependency into the open source SDK. 19 | 20 | MSAL.NET collects this telemetry to proactively detect server side failures or library regressions in order to provide a better service. 21 | 22 | Basic library telemetry includes: 23 | 24 | * Client side state at the time of the request. It shows the reason for the request execution, for example client app requested prompt, no cached tokens, expired access, or others. 25 | * Errors for preceding requests that failed. 26 | * SDK API usage metadata, such as which API and parameters were used for the request. 27 | 28 | >[!IMPORTANT] 29 | >For details on how personally identifiable information (PII) or organizational identifiable information (OII) is handled, refer to [Handling of personally-identifiable information in MSAL.NET](handling-pii.md). 30 | 31 | ## Data 32 | 33 | MSAL requests to the token endpoint will have 2 additional headers: 34 | 35 | * Current request header: `x-client-current-telemetry` 36 | * Current request will contain information about the current public API request. 37 | * Last request header: `x-client-last-telemetry` 38 | * Last request contains information about failures for any previous requests. 39 | 40 | Current request and last request are appended to calls to the token endpoint. 41 | 42 | ### Current request example 43 | 44 | Current requests are used in telemetry to help proactively detect server side issues or library regressions with as little impact to the customer as possible. An example of the current request header format is found [here](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/3d9cb46d824820a580b7f826a71ecd5beb8131a8/src/client/Microsoft.Identity.Client/TelemetryCore/Http/HttpTelemetryManager.cs#L108). 45 | 46 | ### Last request example 47 | 48 | Failed requests are used in telemetry to help proactively detect server side issues or library regressions with as little impact to the customer as possible. An example of the last request header format is found [here](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet/blob/3d9cb46d824820a580b7f826a71ecd5beb8131a8/src/client/Microsoft.Identity.Client/TelemetryCore/Http/HttpTelemetryManager.cs#L51). 49 | --------------------------------------------------------------------------------