diff --git a/msal-dotnet-articles/advanced/exceptions/index.md b/msal-dotnet-articles/advanced/exceptions/index.md index 3bf01f3a6..9bb6bef1b 100644 --- a/msal-dotnet-articles/advanced/exceptions/index.md +++ b/msal-dotnet-articles/advanced/exceptions/index.md @@ -15,7 +15,7 @@ Exceptions in MSAL.NET are intended for app developers to troubleshoot and not f |---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `MsalException` | Base class for MSAL exceptions. | | `MsalClientException` | Errors which occur in the library itself, for example an incomplete configuration. | -| `MsalServiceException` | Represents errors transmitted by the token provider (Microsoft Entra ID). See [Microsoft Entra errors](/azure/active-directory/develop/reference-aadsts-error-codes#handling-error-codes-in-your-application). Servince unavialble errors (e.g. HTTP 500), indicating a problem with the service, have the error code `service_not_available` | +| `MsalServiceException` | Represents errors transmitted by the token provider (Microsoft Entra ID). See [Microsoft Entra errors](/azure/active-directory/develop/reference-aadsts-error-codes#handling-error-codes-in-your-application). Service unavailable errors (e.g. HTTP 500), indicating a problem with the service, have the error code `service_not_available` | | `MsalUiRequiredException` | Special Microsoft Entra error which indicates that the user must interactively login. | No other exception is caught by MSAL. Any network issues, cancellations etc. are bubbled up to the application. @@ -36,31 +36,31 @@ Developers are expected to implement their own retry policies when calling MSAL. ### Exception types -When processing exceptions, you can use the exception type itself and the `ErrorCode` member to distinguish between exceptions. The values of `ErrorCode` are constants of [`MsalError`](xref:Microsoft.Identity.Client.MsalError) +When processing exceptions, you can use the exception type itself and the `ErrorCode` member to distinguish between exceptions. The values of `ErrorCode` are constants of [`MsalError`](xref:Microsoft.Identity.Client.MsalError). -You can also have a look at the fields of [`MsalClientException`](xref:Microsoft.Identity.Client.MsalClientException), [`MsalServiceException`](xref:Microsoft.Identity.Client.MsalServiceException), [`MsalUiRequiredException`](xref:Microsoft.Identity.Client.MsalUiRequiredException) +You can also have a look at the fields of [`MsalClientException`](xref:Microsoft.Identity.Client.MsalClientException), [`MsalServiceException`](xref:Microsoft.Identity.Client.MsalServiceException), [`MsalUiRequiredException`](xref:Microsoft.Identity.Client.MsalUiRequiredException). -In the case of [`MsalServiceException`](xref:Microsoft.Identity.Client.MsalServiceException), the error might contain a code which you can find in [Authentication and authorization error codes](/azure/active-directory/develop/reference-aadsts-error-codes) +In the case of [`MsalServiceException`](xref:Microsoft.Identity.Client.MsalServiceException), the error might contain a code which you can find in [Authentication and authorization error codes](/azure/active-directory/develop/reference-aadsts-error-codes). #### MsalUiRequiredException -The "Ui Required" is proposed as a specialization of ``MsalServiceException`` named ``MsalUiRequiredException``. This means you have attempted to use a non-interactive method of acquiring a token (e.g. AcquireTokenSilent), but MSAL could not do it silently. this can be because: +The "UI Required" is a specialization of `MsalServiceException` named `MsalUiRequiredException`. This means you have attempted to use a non-interactive method of acquiring a token (e.g. AcquireTokenSilent), but MSAL could not do it silently. this can be because: - you need to sign-in - you need to consent - you need to go through a multi-factor authentication experience. -To remediate, call an AcquireToken* method that prompts the user, for example `AcquireTokenInteractive` in public clients, redirect the user to login in websites or respond with a 401 in a web api. +To remediate, call an AcquireToken* method that prompts the user, for example `AcquireTokenInteractive` in public clients, redirect the user to login in websites or respond with a 401 in a web API. -### Continous Access Evaluation +### Continuous Access Evaluation -See /azure/active-directory/develop/app-resilience-continuous-access-evaluation?tabs=dotnet +See [How to use Continuous Access Evaluation enabled APIs in your applications](/entra/identity-platform/app-resilience-continuous-access-evaluation). ### Handling Claim challenge exceptions in MSAL.NET In some cases, when the Microsoft Entra tenant admin has enabled conditional access policies, your application will need to handle claim challenge exceptions. This will appear as an `MsalServiceException` which `Claims` property won't be empty. 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` or something similar. -To handle the claim challenge, you will need to use the `.WithClaims(claims)` method. +To handle the claim challenge, you will need to use the method. ### Retry policies diff --git a/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md b/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md index f93db021e..349b084d8 100644 --- a/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md +++ b/msal-dotnet-articles/advanced/exceptions/msal-error-handling.md @@ -44,7 +44,7 @@ Here are the common exceptions that might be thrown and some possible mitigation | Exception | Error code | Mitigation| | --- | --- | --- | -| [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS65001: The user or administrator hasn't consented to use the application with ID '{appId}' named '{appName}'. Send an interactive authorization request for this user and resource.| Get user consent first. If you aren't using .NET Core (which doesn't have any Web UI), call (once only) `AcquireTokeninteractive`. If you're using .NET core or don't want to do an `AcquireTokenInteractive`, the user can navigate to a URL to give consent: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read`. to call `AcquireTokenInteractive`: `app.AcquireTokenInteractive(scopes).WithAccount(account).WithClaims(ex.Claims).ExecuteAsync();`| +| [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS65001: The user or administrator hasn't consented to use the application with ID '{appId}' named '{appName}'. Send an interactive authorization request for this user and resource.| Get user consent first. If you aren't using .NET Core (which doesn't have any Web UI), call (once only) `AcquireTokenInteractive`. If you're using .NET core or don't want to do an `AcquireTokenInteractive`, the user can navigate to a URL to give consent: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read`. to call `AcquireTokenInteractive`: `app.AcquireTokenInteractive(scopes).WithAccount(account).WithClaims(ex.Claims).ExecuteAsync();`| | [MsalUiRequiredException](/dotnet/api/microsoft.identity.client.msaluirequiredexception) | AADSTS50079: The user is required to use [multi-factor authentication (MFA)](/azure/active-directory/authentication/concept-mfa-howitworks).| There's no mitigation. If MFA is configured for your tenant and Microsoft Entra ID decides to enforce it, fall back to an interactive flow such as `AcquireTokenInteractive`.| | [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) |AADSTS90010: The grant type isn't supported over the */common* or */consumers* endpoints. Use the */organizations* or tenant-specific endpoint. You used */common*.| As explained in the message from Microsoft Entra ID, the authority needs to have a tenant or otherwise */organizations*.| | [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) | AADSTS70002: The request body must contain the following parameter: `client_secret or client_assertion`.| This exception can be thrown if your application wasn't registered as a public client application in Microsoft Entra ID. In the Azure portal, edit the manifest for your application and set `allowPublicClient` to `true`. | @@ -135,7 +135,7 @@ catch (MsalUiRequiredException ex) when (ex.ErrorCode == MsalError.InvalidGrantE When calling an API requiring Conditional Access from MSAL.NET, your application will need to handle claim challenge exceptions. This will appear as an [MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) where the [Claims](/dotnet/api/microsoft.identity.client.msalserviceexception.claims) property won't be empty. -To handle the claim challenge, you'll need to use the `.WithClaim()` method of the [`PublicClientApplicationBuilder`](/dotnet/api/microsoft.identity.client.publicclientapplicationbuilder) class. +To handle the claim challenge, use . [!INCLUDE [Active directory error handling retries](../../includes/error-handling-retries.md)] @@ -143,7 +143,7 @@ To handle the claim challenge, you'll need to use the `.WithClaim()` method of t MSAL.NET implements a simple retry-once mechanism for errors with HTTP error codes 500-600. -[MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) surfaces `System.Net.Http.Headers.HttpResponseHeaders` as a property `namedHeaders`. You can use additional information from the error code to improve the reliability of your applications. In the case described, you can use the `RetryAfterproperty` (of type `RetryConditionHeaderValue`) and compute when to retry. +[MsalServiceException](/dotnet/api/microsoft.identity.client.msalserviceexception) surfaces `System.Net.Http.Headers.HttpResponseHeaders` as a property `namedHeaders`. You can use additional information from the error code to improve the reliability of your applications. In the case described, you can use the `RetryAfter` property (of type `RetryConditionHeaderValue`) and compute when to retry. Here's an example for a daemon application using the client credentials flow. You can adapt this to any of the methods for acquiring a token. diff --git a/msal-dotnet-articles/how-to/differences-adal-msal-net.md b/msal-dotnet-articles/how-to/differences-adal-msal-net.md index 952130bad..aa36d315e 100644 --- a/msal-dotnet-articles/how-to/differences-adal-msal-net.md +++ b/msal-dotnet-articles/how-to/differences-adal-msal-net.md @@ -181,7 +181,7 @@ At times when acquiring a token, Microsoft Entra ID throws an exception in case In MSAL.NET, claim challenge exceptions are handled in the following way: - The `Claims` are surfaced in the `MsalServiceException`. -- There's a `.WithClaim(claims)` method that can apply to the `AcquireTokenXXX` builders. +- There's a method that can apply to the `AcquireTokenXXX` builders. For details see [Handling MsalUiRequiredException](../advanced/exceptions/msal-error-handling.md#msaluirequiredexception).