FAQ

FAQs

ADAL Scope

What is the main functionality of ADAL?

Acquiring tokens from a Security Token Service (STS) for a client application.

What standard protocols does ADAL follow for token acquisition?

ADAL is implementing the Azure AD implementation of the OAuth2 protocol.

Is ADAL a general library for token acquisition using OAuth2 protocol?

No. ADAL is a client library for Azure Active Directory (AAD) and Active Directory Federation Services (ADFS). There are some custom notions such as “resource” required by ADAL which are considered extensions to the general OAuth2 protocol spec and not supported by other STS’s.

ADAL API

Should I turn off authority validation by passing false to the AuthenticationContext?

It depends on what type of authority you talk to. If it is ADFS, you have to pass false as ADFS does not currently support authority validation. If it is AAD, you still have the option to pass false, but it is recommended to be true, especially if you get the address of the authority from a third party at runtime (e.g. via 401 challenge). This is to protect applications and users from being redirected to malicious endpoints to enter their credentials.

Which acquire token method should I call?

See the guidance documented in Acquire Tokens page.

Debugging

What are the common reasons for failure in using ADAL?

Problems in ADAL could have various reasons. These are the common culprits:

1. Your machine has connection issues.
2. Your applications/users are not properly configured on AAD or ADFS.
3. You are using an incorrect API for your task (ADAL has several methods to acquire token).
4. There is a bug in ADAL! Yes, that is always possible. If you are certain that none of the items above are the reason for the failure, please report it to us and we will investigate and fix the bug if it exists.

What tools can I use for diagnosing an issue in ADAL?

There are several diagnostics tools you can use:

1. ADAL Samples: The first best tool is the set of samples published along with ADAL. Try to find the closest sample to your application and download and run it on your machine. If the sample works properly, you need to follow the same steps of the sample app in your application.
2. ADAL diagnostic logs: You can enable ADAL logging. This will write some logs with information about the internal steps of ADAL. You may analyze the logs to find the issue. Also, in case you contact the ADAL team, you need to send the logs to help with the analysis. You can find the instruction on how to turn on ADAL logs here.
3. Network traces: Use a tool like Fiddler for recording all the http communications ADAL makes with the server. Using fiddler is especially easy on Windows desktop machines. Please share the network trace file with the ADAL team in case we are involved in diagnosing your issue.

What kind of errors are returned from ADAL as exception and what kind is reported to the user?

Most errors are returned from ADAL in forms of an exception; however, there are limited cases in which ADAL shows the Azure AD error on the browser control. These cases happen mostly when the client cannot be validated or authority server cannot be reached.

Does ADAL have any kind of retry logic inside?

No. If an operations fails, ADAL reports an error via an exception. The exception includes an error code and also a status code in case the error is returned from the authority. In such cases, it is developer’s job to examine the status code (which mostly reflects the http status code of the response) in the exception and decides whether to retry or not. 502 is usually the status code that warrants a retry.