Exceptions in ADAL.NET

Exceptions in ADAL.NET

ADAL.NET proposes 5 exception classes:

• AdalException is used directly for exceptions which are local to the library (such as trying to call AcquireTokenSilent whereas there is nothing in the cache), or as a base class for service exceptions (see below). AdalException exposes one member named ErrorCode which values are the static members of the AdalError class
• AdalSilentTokenAcquisitionException is thrown when a call to AcquireTokenSilentAsync fails. In this case the ErrorCode is AdalError.FailedToAcquireTokenSilently
• AdalUserMismatchException
• AdalServiceException provides a representation of the STS errors: along with the error code, the Http StatusCode is exposed, as well as the HttpResponseHeaders and ServiceErrorCodes
• Finally, AdalClaimChallengeException is an exception thrown by the service in case a resource requires more claims from the user (for instance 2-factors authentication).

Handling AdalClaimChallengeException

Principle

The Claims member of AdalClaimChallengeException contains some json fragment with the claims which are expected. - when this exception is received by a public client application, the application needs to call AcquireTokenAsync passing these claims in the optional claim parameters.

• If the exception is received in a Web API (for instance in the context of an OAuth 2.0 On-behalf-of flow), it needs to be surfaced back to the public client application one way or another, so that this one can call AcquireTokenAsync with the right claims. More details are provided in the Developer Guidance for Azure Active Directory Conditional Access.

Sample

Handling Claim challenge exception is illustrated in the active-directory-dotnet-webapi-onbehalfof-ca sample (See the AccessCaApiController.cs lines 95 to 100) We mentioned the AdalError class which contains all the error codes.

How to handle errors, depending on AdalError

Adal Error	Associated ADAL.NET Error message	Possible action to fix?
Unknown	Unknown error	Not actionable. The best is to enable logging (See � 6.8) to understand more about the problem
NonHttpsRedirectNotSupported	Non-HTTPS url redirect is not supported in webview	App registration issue: the Redirect URL should be https, not httpRuntime issue all segments need to be tursted. See https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/wiki/Understanding-'non_https_redirect_failed'-AdalServiceException
InvalidArgument		API call issue. An invalid argument was passed to an API. See the ArgumentException inner exception
AuthenticationFailed		User issue probably: the user did not provide the right credentials, or MFA is needed
AuthenticationCanceled	User canceled authentication	The user canceled the authentication dialog. This might be a consequence of a bad application configuration (see � 6.4.1)
UnauthorizedResponseExpected	Unauthorized http response (status code 401) was expected	?
AuthorityNotInValidList	'authority' is not in the list of valid addresses	Authority validation issue. The authority passed in the constructor of AuthenticationContext is not in the while list of authority. Verify that this is the right one and set the validateAuthority to false
AuthorityValidationFailed	Authority validation failed
AssemblyLoadFailed		Development or deployment issue. For instance a platform specific assembly was not deployed with the application leveraging Adal.NET
AssemblyNotFound
InvalidOwnerWindowType		The windowOwner parameter in the constructor of PlatformParameters for the .NET Framework, UWP, or WinRT platforms does not correspond to a window.
MultipleTokensMatched	The cache contains multiple tokens satisfying the requirements. Call AcquireToken again providing more arguments (e.g. UserId)
InvalidAuthorityType
InvalidCredentialType	Invalid credential type
InvalidServiceUrl		The URL for the service is invalid
FailedToAcquireTokenSilently	Failed to acquire token silently as no token was found in the cache. Call method AcquireToken	See �6.4.2
CertificateKeySizeTooSmall		For the Client credentials with certificate flow, the size of the certificate key was too small. Use a certificate with a bigger key
IdentityProtocolLoginUrlNull	The LoginUrl property in identityProvider cannot be null	Change the authority
IdentityProtocolMismatch	No identity provider matches the requested protocol
EmailAddressSuffixMismatch	No identity provider email address suffix matches the provided address
IdentityProviderRequestFailed	Token request made to identity provider failed. Check InnerException for more details
StsTokenRequestFailed	Token request to security token service failed. Check InnerException for more details
EncodedTokenTooLong	Encoded token size is beyond the upper limit
ServiceUnavailable		The STS is temporary unavailable. If the http response headers contain a Retry-After information the application should wait for the recommended delay and retry once.
ServiceReturnedError	Service returned error. Check InnerException for more details
FederatedServiceReturnedError		ADFS specific
StsMetadataRequestFailed	Metadata request to Access Control service failed. Check InnerException for more details
NoDataFromSts
UserMismatch	User '{0}' returned by service does not match user '{1}' in the request
UnknownUserType	Unknown User Type	This error happens when, in non-interactive flows (resource owner password credentials grant), ADAL.NET is not able to identify whether the user is a federated or managed (which is needed in order to know where to send the credentials). Managed users are user of an Azure AD tenant. Federated users are managed by another authority than Azure AD. If you look at the logs with PII (See New way of logging, controlling PII (ADAL.Net > 3.18) ), they state the username and the account type found in the discovery response, which can help you understanding the issue
UnknownUser	Could not identify logged in user
UserRealmDiscoveryFailed	User realm discovery failed
AccessingWsMetadataExchangeFailed		ADFS specific. The WS metadata manifest was not retrieved
ParsingWsMetadataExchangeFailed		ADFS specific. The WS metadata manifest does not have the format expected by ADAL.NET
WsTrustEndpointNotFoundInMetadataDocument	WS-Trust endpoint not found in metadata document	ADFS specific. The WS metadata manifest does not contain the expected WS-Trust end point.
ParsingWsTrustResponseFailed	Parsing WS-Trust response failed
NetworkNotAvailable		The STS is out of reach. If the http response headers contain a Retry-After information the application should wait for the recommended delay and retry once
AuthenticationUiFailed	The browser based authentication dialog failed to complete
UserInteractionRequired	One of two conditions was encountered: The PromptBehavior.Never flag was passed, but the constraint could not be honored, because user interaction was required. An error occurred during a silent web authentication that prevented the http authentication flow from completing in a short enough time frame	Programming issue. After the call to AcquireTokenSilentAsync failed, call AcquireTokenAsync to ensure that user interaction happens
PasswordRequiredForManagedUserError	Password is required for managed user
GetUserNameFailed	Failed to get user name
MissingFederationMetadataUrl	Federation Metadata Url is missing for federated user. This user type is unsupported.	ADFS specific
FailedToRefreshToken	Failed to refresh access token
IntegratedAuthFailed	Integrated authentication failed. You may try an alternative authentication method.
DuplicateQueryParameter		Check your extraQueryParameters parameter in AcquireTokenAsync, as you probably have passed a parameter which is also passed by ADAL.NET
BrokerReponseHashMismatch	Unencrypted broker response hash did not match the expected hash
DeviceCertificateNotFound
InteractionRequired	interaction_required	Programming issue. After the call to AcquireTokenSilentAsync failed, call AcquireTokenAsync to ensure that user interaction happens