README.md

Active Directory Authentication Library (ADAL) for .NET, Windows Store, .NET Core, Xamarin iOS and Xamarin Android.

Code Samples	Reference Docs	Developer Guide

Active Directory Authentication Library (ADAL) provides easy to use authentication functionality for your .NET/.NET Core client, Windows Store/Xamarin.iOS/Xamarin.Android apps by taking advantage of Windows Server Active Directory and Windows Azure Active Directory.

Stable (master branch)	Nightly (dev branch)

Build status

Branch	Status
dev (AppVeyor)

Versions

Current version - latest one at nuget.org.
Minimum recommended version - 2.29.0 You can find the changes for each version in the change log.

Security Issue in Multiple Versions of ADAL .Net

A defect in ADAL .Net can result in an elevation of privilege in specific problem scenarios. The problem scenarios involve the On Behalf Of protocol flow and specific use cases of a ClientAssertion/ClientAssertionCertificate/ClientCredential and UserAssertion being passed to the AcquireToken* API. Multiple versions of the library are affected. Affected versions are listed below.

We have emailed owners of active applications that are using an impacted version of the library in the specific problem scenarios.

The latest stable version of the library does not have the defect. To avoid being impacted we strongly recommend you update to at least 2.28.1 for 2.x, 3.13.4 for 3.x, or the latest stable version. If you have questions about this issue, please email aadintegrate@microsoft.com.

Affected 2.x versions: 2.27.306291202, 2.26.305102204, 2.26.305100852, 2.25.305061457, 2.21.301221612, 2.20.301151232, 2.19.208020213, 2.18.206251556, 2.17.206230854, 2.16.204221202, 2.15.204151539, 2.14.201151115, 2.13.112191810, 2.12.111071459, 2.11.10918.1222, 2.10.10910.1511, 2.9.10826.1824, 2.8.10804.1442-rc, 2.7.10707.1513-rc, 2.6.2-alpha, 2.6.1-alpha, 2.5.1-alpha

Affected 3.x versions: 3.11.305310302-alpha, 3.10.305231913, 3.10.305161347, 3.10.305110106, 3.5.208051316-alpha, 3.5.208012240-alpha, 3.5.207081303-alpha, 3.4.206191646-alpha, 3.3.205061641-alpha, 3.2.204281119-alpha, 3.1.203031538-alpha, 3.0.110281957-alpha

Samples and Documentation

We provide a full suite of sample applications and ADAL documentation to help you get started with learning the Azure Identity system. Our Azure AD Developer Guide includes tutorials for native clients such as Windows, Windows Phone, iOS, OSX, Android, and Linux. We also provide full walkthroughs for authentication flows such as OAuth2, OpenID Connect, Graph API, and other awesome features.

Community Help and Support

We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one! We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browser existing issues to see if someone has had your question before.

We recommend you use the "adal" tag so we can see it! Here is the latest Q&A on Stack Overflow for ADAL: http://stackoverflow.com/questions/tagged/adal

Security Reporting

If you find a security issue with our libraries or services please report it to secure@microsoft.com with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

Contributing

All code is licensed under the MIT license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now, but check this document first.

Diagnostics

The following are the primary sources of information for diagnosing issues:

• Exceptions
• Logs
• Network traces

Also, note that correlation IDs are central to the diagnostics in the library. You can set your correlation IDs on a per request basis (by setting CorrelationId property on AuthenticationContext before calling an acquire token method) if you want to correlate an ADAL request with other operations in your code. If you don't set a correlations id, then ADAL will generate a random one which changes on each request. All log messages and network calls will be stamped with the correlation id.

Exceptions

This is obviously the first diagnostic. We try to provide helpful error messages. If you find one that is not helpful please file an issue and let us know. Please also provide the target platform of your application (e.g. Desktop, Windows Store, Windows Phone).

Logs

Until ADAL.Net 3.18, in order to configure logging, you had to implement the IAdalLogCallback interface

class LoggerCallbackImpl : IAdalLogCallback
{
    public void Log(LogLevel level, string message)
    {
        // process log message, for example write it to your favorite logging framework
    }
}

and then you had to set the static property Callback of the LoggerCallbackHandler class to the instance of a class implementing the IAdalLogCallback interface.

LoggerCallbackHandler.Callback = new LoggerCallbackImpl();

This interface was logging all the information including the information containing Personally Identifyable Information (PII)

From ADAL.NET 3.17.2, we help you to be GDPR compliant out of the box, by not logging PII any longer through the IAdalLogCallback interface.

Now, if you really need/want to log PII to help you with debugging, you can leverage a new mechanism in ADAL.NET 3.18:

• You can subscribe to every message (including the ones filtered out because they contain PII information), by setting the LogCallback delegate of LoggerCallbackHandler. You will be told by the containsPii parameter, if a message contains PII or not. Note that using LoggerCallbackHandler.LogCallback delegate will disable the legacy mechanism of logging the messages through the LoggerCallbackHandler.Callback property.
• Once you have set the LoggerCallbackHandler.LogCallback property, you can also control if you want to log PII or not by settting the LoggerCallbackHandler.PiiLoggingEnabled property. By default, this Boolean is set to false (still to help you being GDPR compliant). If you set it to true, messages will be logged twice (one which does not contain PII, for which containsPii will be false), and the second which will contain PII (and for which containsPii will be true) Finally, in any case, when PII information is logged, it’s systematically hashed.

  private static void Log(LogLevel level, string message, bool containsPii)
  {
   if (containsPii)
   {
    Console.ForegroundColor = ConsoleColor.Red;
   }
   Console.WriteLine($"{level} {message}");
   Console.ResetColor();
  }

  static void Main(string[] args)
  {
   LoggerCallbackHandler.LogCallback = Log;
   LoggerCallbackHandler.PiiLoggingEnabled = true;
   ...

Brokered Authentication for iOS

If your app requires conditional access or certificate authentication (currently in preview) support, you must set up your AuthenticationContext and redirectURI to be able to talk to the Azure Authenticator app. Make sure that your Redirect URI and application's bundle id is all in lower case.

Enable Broker Mode on Your Context

Broker is enabled on a per-authentication-context basis. It is disabled by default. You must set useBroker flag to true in PlatformParameters constructor if you wish ADAL to call to broker:

public PlatformParameters(UIViewController callerViewController, bool useBroker)

The userBroker flag setting will allow ADAL to try to call out to the broker.

AppDelegate changes

Update the AppDelegate.cs file to include the override method below. This method is invoked everytime the application is launched and is used as an opportunity to process response from the Broker and complete the authentication process.

public override bool OpenUrl(UIApplication application, NSUrl url, string sourceApplication, NSObject annotation)
{            
	if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
    {
		AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);    
    }
	
    return true;
}

Registering a URL Scheme

ADAL uses URLs to invoke the broker and then return back to your app. To finish that round trip you need a URL scheme registered for your app. We recommend making the URL scheme fairly unique to minimize the chances of another app using the same URL scheme.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.mycompany.myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>mytestiosapp</string>
        </array>
    </dict>
</array>

LSApplicationQueriesSchemes

ADAL uses –canOpenURL: to check if the broker is installed on the device. in iOS 9 Apple locked down what schemes an application can query for. You will need to add “msauth” to the LSApplicationQueriesSchemes section of your info.plist file.

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauth</string>
</array>

Redirect URI

This adds extra requirements on your redirect URI. Your redirect URI must be in the proper form.

<app-scheme>://<your.bundle.id>
ex: mytestiosapp://com.mycompany.myapp

This Redirect URI needs to be registered on the app portal as a valid redirect URI. Additionally a second "msauth" form needs to be registered to handle certificate authentication in Azure Authenticator.

msauth://code/<broker-redirect-uri-in-url-encoded-form>
AND
msauth://code/<broker-redirect-uri-in-url-encoded-form>/
ex: msauth://code/mytestiosapp%3A%2F%2Fcom.mycompany.myapp and msauth://code/mytestiosapp%3A%2F%2Fcom.mycompany.myapp/  

Brokered Authentication for Android

If your app or your app users require conditional access or certificate authentication support, you must set up your AuthenticationContext and redirectURI to be able to talk to the Azure Authenticator app OR Company Portal. Make sure that your Redirect URI and application's bundle id is all in lower case.

Enable Broker Mode on Your Context

Broker is enabled on a per-authentication-context basis. It is disabled by default. You must set useBroker flag to true in PlatformParameters constructor if you wish ADAL to call to broker:

public PlatformParameters(Activity callerActivity, bool useBroker)
public PlatformParameters(Activity callerActivity, bool useBroker, PromptBehavior promptBehavior)

The useBroker flag setting will allow ADAL to try to call out to the broker.

If target version is lower than 23, calling app has to have the following permissions declared in manifest(http://developer.android.com/reference/android/accounts/AccountManager.html):

• GET_ACCOUNTS
• USE_CREDENTIALS
• MANAGE_ACCOUNTS If target version is 23, USE_CREDENTIALS and MANAGE_ACCOUNTS have been deprecated and GET_ACCOUNTS is under protection level "dangerous". The calling app is responsible for requesting the runtime permission for GET_ACCOUNTS. You can reference Runtime permission request for API 23.

Registering Redirect URI

ADAL uses URLs to invoke the broker and then return back to your app. To finish that round trip you need a URL scheme registered for your app. We recommend making the URL scheme fairly unique to minimize the chances of another app using the same URL scheme. You can call generateRedirectUriForBroker.ps1 (requires updates from the developer to fill in values and details about the app) to compute the redirect uri.

App Activity changes

Update the MainActivity.cs file to include the override method below. This method is invoked when the activity receives a callback from webview or the broker application. This code snippet is required complete the authentication process.

protected override void OnActivityResult(int requestCode, Result resultCode, Intent data)
{
    base.OnActivityResult(requestCode, resultCode, data);
	AuthenticationAgentContinuationHelper.SetAuthenticationAgentContinuationEventArgs(requestCode, resultCode, data);
}

Network Traces

You can use various tools to capture the HTTP traffic that ADAL generates. This is most useful if you are familiar with the OAuth protocol or if you need to provide diagnostic information to Microsoft or other support channels.

Fiddler is the easiest HTTP tracing tool. In order to be useful it is necessary to configure fiddler to record unencrypted SSL traffic.

NOTE: Traces generated in this way may contain highly privileged information such as access tokens, usernames and passwords. If you are using production accounts, do not share these traces with 3rd parties. If you need to supply a trace to someone in order to get support, reproduce the issue with a temporary account with usernames and passwords that you don't mind sharing.

License

Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT License (the "License");

We Value and Adhere to the Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.