Table Of ContentTTaabbllee ooff CCoonntteennttss
Overview
Why Azure AD
Auth basics
Types of apps
Get Started
Mobile & Desktop apps
Overview
iOS
Android
.NET
Windows
Xamarin
Cordova
OAuth 2.0
Web apps
Overview
ASP.NET
ASP.NET Core
Java
NodeJS
OpenID Connect
Single Page Apps
Overview
Angular JS
Javascript
Web APIs
Overview
ASP.NET
NodeJS
Service to Service
Overview
.NET
OAuth 2.0 client credentials
Guides
Application registration
Multi-tenant apps
Conditional access
OAuth & OpenID Connect
OpenID Connect protocol
OAuth 2.0 auth code grant
OAuth 2.0 implicit grant
SAML 2.0
Customize claims
Debug SAML-based SSO
Single sign-on SAML protocol
Single sign-out SAML protocol
Create a tenant
Branding guidelines
Mobile & Desktop SSO
Enable SSO on Android
Enable SSO on iOS
Azure AD B2B
User provisioning with SCIM
Azure AD Graph API
Get started with AAD Graph
AppSource certification
Azure AD app gallery
Office 365 Seller Dashboard
Working with Visual Studio
Get started with Visual Studio connected services
Error during authentication detection
Get started with WebApi
What happened to my web API project
Windows Server ADFS
ACS Migration
Error handling best practices for ADAL
Reference
Code samples
Auth libraries (ADAL)
Code samples article
Glossary
Authentication protocols
OpenID Connect
Oauth
Service to service calls
On-behalf-of flow
Supported token and claim types
Signing key rollover
Federation metadata
Certificate credentials
Application objects
Apps and Azure AD
Application manifest
Token lifetimes
Service limits
v2.0 endpoint
Overview
Types of apps
Limitations
v1-v2 comparison
Get Started
Mobile & Desktop apps
Web apps
Guides
Register an app
Reference
Authentication libraries
v2.0 authentication protocols
Scopes
Resources
Getting help
Azure roadmap
Pricing calculator
Azure Active Directory for developers
1/9/2018 • 1 min to read • Edit Online
Azure Active Directory (Azure AD) is a cloud identity service that allows developers to securely sign in users
with a Microsoft work or school account. This documentation shows you how to add Azure AD support to
your application by using the industry standard protocols: OAuth2.0 and OpenID Connect.
Authentication basics An introduction to authentication with Azure AD.
Types of applications An overview of the authentication scenarios that are
supported by Azure AD.
Get started
The following guided setups walk you through using the Microsoft authentication libraries to sign in Azure
AD users.
Overview .NET (WPF) Cordova
iOS .NET (UWP)
Android Xamarin
Mobile and desktop apps
Overview Node.js
ASP.NET
Java
Web apps
Overview
AngularJS
JavaScript
Single page apps
Overview
ASP.NET
Node.js
Web APIs
Overview
.NET
Service-to-service
How-to guides
The following guides inform you how to perform common tasks with Azure AD.
Application registration How to register an application in Azure AD.
Multi-tenant applications How to sign in any Microsoft work account.
OAuth and OpenID Connect protocols How to sign in users and call web APIs by using the
Microsoft authentication protocols.
Additional guides A list of guides that are available for Azure AD.
Reference topics
The following articles provide detailed information on APIs, protocol messages, and terms that are used in
Azure AD.
Authentication Libraries (ADAL) An overview of the libraries and SDKs that are provided by
Azure AD.
Code samples A list of all of the Azure AD code samples.
Glossary Terminology and definitions of words that are used
throughout this documentation.
Additional reference topics A list of reference topics that are available for Azure AD.
NNOOTTEE
If you need to sign in Microsoft personal accounts, you may want to consider using the Azure AD v2.0 endpoint. The
Azure AD v2.0 endpoint is the unification of Microsoft personal accounts and Microsoft work accounts (from Azure
AD) into a single authentication system.
Help and support
If you need help, want to report an issue, or want to learn more about your support options, see the following
article:
Help and support for developers
Authentication Scenarios for Azure AD
12/11/2017 • 31 min to read • Edit Online
Azure Active Directory (Azure AD) simplifies authentication for developers by providing identity as a service, with
support for industry-standard protocols such as OAuth 2.0 and OpenID Connect, as well as open source libraries for
different platforms to help you start coding quickly. This document will help you understand the various scenarios
Azure AD supports and will show you how to get started. It’s divided into the following sections:
Basics of Authentication in Azure AD
Claims in Azure AD Security Tokens
Basics of Registering an Application in Azure AD
Application Types and Scenarios
Web Browser to Web Application
Single Page Application (SPA)
Native Application to Web API
Web Application to Web API
Daemon or Server Application to Web API
Basics of Authentication in Azure AD
If you are unfamiliar with basic concepts of authentication in Azure AD, read this section. Otherwise, you may want
to skip down to Application Types and Scenarios.
Let’s consider the most basic scenario where identity is required: a user in a web browser needs to authenticate to a
web application. This scenario is described in greater detail in the Web Browser to Web Application section, but it’s
a useful starting point to illustrate the capabilities of Azure AD and conceptualize how the scenario works. Consider
the following diagram for this scenario:
With the diagram above in mind, here’s what you need to know about its various components:
Azure AD is the identity provider, responsible for verifying the identity of users and applications that exist in an
organization’s directory, and ultimately issuing security tokens upon successful authentication of those users
and applications.
An application that wants to outsource authentication to Azure AD must be registered in Azure AD, which
registers and uniquely identifies the app in the directory.
Developers can use the open source Azure AD authentication libraries to make authentication easy by handling
the protocol details for you. See Azure Active Directory Authentication Libraries for more information.
• Once a user has been authenticated, the application must validate the user’s security token to ensure that
authentication was successful for the intended parties. Developers can use the provided authentication libraries to
handle validation of any token from Azure AD, including JSON Web Tokens (JWT) or SAML 2.0. If you want to
perform validation manually, see the JWT Token Handler documentation.
IIMMPPOORRTTAANNTT
Azure AD uses public key cryptography to sign tokens and verify that they are valid. See Important Information About
Signing Key Rollover in Azure AD for more information on the necessary logic you must have in your application to ensure it’s
always updated with the latest keys.
• The flow of requests and responses for the authentication process is determined by the authentication protocol
that was used, such as OAuth 2.0, OpenID Connect, WS-Federation, or SAML 2.0. These protocols are discussed in
more detail in the Azure Active Directory Authentication Protocols topic and in the sections below.
NNOOTTEE
Azure AD supports the OAuth 2.0 and OpenID Connect standards that make extensive use of bearer tokens, including bearer
tokens represented as JWTs. A bearer token is a lightweight security token that grants the “bearer” access to a protected
resource. In this sense, the “bearer” is any party that can present the token. Though a party must first authenticate with Azure
AD to receive the bearer token, if the required steps are not taken to secure the token in transmission and storage, it can be
intercepted and used by an unintended party. While some security tokens have a built-in mechanism for preventing
unauthorized parties from using them, bearer tokens do not have this mechanism and must be transported in a secure
channel such as transport layer security (HTTPS). If a bearer token is transmitted in the clear, a man-in the middle attack can
be used by a malicious party to acquire the token and use it for an unauthorized access to a protected resource. The same
security principles apply when storing or caching bearer tokens for later use. Always ensure that your application transmits
and stores bearer tokens in a secure manner. For more security considerations on bearer tokens, see RFC 6750 Section 5.
Now that you have an overview of the basics, read the sections below to understand how provisioning works in
Azure AD and the common scenarios Azure AD supports.
Claims in Azure AD Security Tokens
Security tokens issued by Azure AD contain claims, or assertions of information about the subject that has been
authenticated. These claims can be used by the application for various tasks. For example, they can be used to
validate the token, identify the subject's directory tenant, display user information, determine the subject's
authorization, and so on. The claims present in any given security token are dependent upon the type of token, the
type of credential used to authenticate the user, and the application configuration. A brief description of each type
of claim emitted by Azure AD is provided in the table below. For more information, refer to Supported Token and
Claim Types.
CLAIM DESCRIPTION
Application ID Identifies the application that is using the token.
Audience Identifies the recipient resource the token is intended for.
Application Authentication Context Class Reference Indicates how the client was authenticated (public client vs.
confidential client).
Authentication Instant Records the date and time when the authentication occurred.
CLAIM DESCRIPTION
Authentication Method Indicates how the subject of the token was authenticated
(password, certificate, etc.).
First Name Provides the given name of the user as set in Azure AD.
Groups Contains object Ids of Azure AD groups the user is a member
of.
Identity Provider Records the identity provider that authenticated the subject of
the token.
Issued At Records the time at which the token was issued, often used for
token freshness.
Issuer Identifies the STS that emitted the token as well as the Azure
AD tenant.
Last Name Provides the surname of the user as set in Azure AD.
Name Provides a human readable value that identifies the subject of
the token.
Object Id Contains an immutable, unique identifier of the subject in
Azure AD.
Roles Contains friendly names of Azure AD Application Roles that
the user has been granted.
Scope Indicates the permissions granted to the client application.
Subject Indicates the principal about which the token asserts
information.
Tenant Id Contains an immutable, unique identifier of the directory
tenant that issued the token.
Token Lifetime Defines the time interval within which a token is valid.
User Principal Name Contains the user principal name of the subject.
Version Contains the version number of the token.
Basics of Registering an Application in Azure AD
Any application that outsources authentication to Azure AD must be registered in a directory. This step involves
telling Azure AD about your application, including the URL where it’s located, the URL to send replies after
authentication, the URI to identify your application, and more. This information is required for a few key reasons:
Azure AD needs coordinates to communicate with the application when handling sign-on or exchanging
tokens. These include the following:
Application ID URI: The identifier for an application. This value is sent to Azure AD during authentication
to indicate which application the caller wants a token for. Additionally, this value is included in the token
so that the application knows it was the intended target.
Reply URL and Redirect URI: In the case of a web API or web application, the Reply URL is the location to
which Azure AD will send the authentication response, including a token if authentication was successful.
In the case of a native application, the Redirect URI is a unique identifier to which Azure AD will redirect
the user-agent in an OAuth 2.0 request.
Application ID: The ID for an application, which is generated by Azure AD when the application is
registered. When requesting an authorization code or token, the Application ID and key are sent to Azure
AD during authentication.
Key: The key that is sent along with a Application ID when authenticating to Azure AD to call a web API.
Azure AD needs to ensure the application has the required permissions to access your directory data, other
applications in your organization, and so on
Provisioning becomes clearer when you understand that there are two categories of applications that can be
developed and integrated with Azure AD:
Single tenant application: A single tenant application is intended for use in one organization. These are typically
line-of-business (LoB) applications written by an enterprise developer. A single tenant application only needs to
be accessed by users in one directory, and as a result, it only needs to be provisioned in one directory. These
applications are typically registered by a developer in the organization.
Multi-tenant application: A multi-tenant application is intended for use in many organizations, not just one
organization. These are typically software-as-a-service (SaaS) applications written by an independent software
vendor (ISV). Multi-tenant applications need to be provisioned in each directory where they will be used, which
requires user or administrator consent to register them. This consent process starts when an application has
been registered in the directory and is given access to the Graph API or perhaps another web API. When a user
or administrator from a different organization signs up to use the application, they are presented with a dialog
that displays the permissions the application requires. The user or administrator can then consent to the
application, which gives the application access to the stated data, and finally registers the application in their
directory. For more information, see Overview of the Consent Framework.
Some additional considerations arise when developing a multi-tenant application instead of a single tenant
application. For example, if you are making your application available to users in multiple directories, you need a
mechanism to determine which tenant they’re in. A single tenant application only needs to look in its own directory
for a user, while a multi-tenant application needs to identify a specific user from all the directories in Azure AD. To
accomplish this task, Azure AD provides a common authentication endpoint where any multi-tenant application can
direct sign-in requests, instead of a tenant-specific endpoint. This endpoint is
https://login.microsoftonline.com/common for all directories in Azure AD, whereas a tenant-specific endpoint might
be https://login.microsoftonline.com/contoso.onmicrosoft.com. The common endpoint is especially important to
consider when developing your application because you’ll need the necessary logic to handle multiple tenants
during sign-in, sign-out, and token validation.
If you are currently developing a single tenant application but want to make it available to many organizations, you
can easily make changes to the application and its configuration in Azure AD to make it multi-tenant capable. In
addition, Azure AD uses the same signing key for all tokens in all directories, whether you are providing
authentication in a single tenant or multi-tenant application.
Each scenario listed in this document includes a sub-section that describes its provisioning requirements. For more
in-depth information about provisioning an application in Azure AD and the differences between single and multi-
tenant applications, see Integrating Applications with Azure Active Directory for more information. Continue
reading to understand the common application scenarios in Azure AD.
Application Types and Scenarios
Each of the scenarios described in this document can be developed using various languages and platforms. They
are all backed by complete code samples which are available in our Code Samples guide, or directly from the
