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 a custom version of the OAuth2 protocol. Also, for some specific scenarios, it may internally use other protocols (e.g. WS-Trust).

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 constructor?

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, 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.

What overload of AcquireToken should I call?

It depends on the type of client application you use and the scenario you need a token for. This is the brief guideline:

1. ADAL supports two types of clients: public clients for native apps and confidential clients used mostly in web apps. If you have a client credential or certificate, your client is confidential and you can use any overload which has a parameter of type ClientCredential, ClientAssertion or AsymetricKeyCredential. Otherwise, you have a native client and can user any overload which does not need any of the above parameters.
2. ADAL can acquire a token with either a user, an application, or both being the subject. If your scenario involves no user, you should call an overload of AcquireToken which does not have any mention of a user. For user flows or user plus application flows you can use the rest.
3. For user only scenarios, ADAL can acquire token in interactive or non-interactive way. Interactive scenario involves a user entering his/her credential inside a browser control. Non-interactive scenario is used when the application already has user’s credential and can pass is using UserCredential class. This flow is however not recommended and should be only used in very limited cases with good reason not to use interactive flow instead.
4. ADAL also has overloads for advanced scenarios such as token acquisition for web apps by passing authorization code and also for on behalf of flow in which a user token is exchanged with a user plus app token.

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 similar overloads for the method AcquireToken).
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 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 turn on ADAL logs and then call the ADAL API. 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. Fiddler: is a powerful external tool for recording all the http communications ADAL makes with the server. Using fiddler is especially easy on Windows desktop machines. Fiddler trace is another useful document to share with the ADAL team in case we are involved in diagnosing your issue.
4. ADAL Symbols and source files: ADAL is an open source project which makes it very convenient to debug. You can download the symbols file from the symbols server or even download the entire source code and reference it in your project instead of Maven. More information about using ADAL source code can be found here.

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 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.