To call Microsoft Graph, your app must acquire an access token from Azure Active Directory (Azure AD), Microsoft's cloud identity service. The access token contains information (or claims) about your app and the permissions it has for the resources and APIs available through Microsoft Graph. To get an access token, your app must be able to authenticate with Azure AD and be authorized by either a user or an administrator for access to the Microsoft Graph resources it needs.
This topic provides an overview of access tokens, Azure AD, and how your app can get access tokens. If you are already familiar with integrating an app with Azure AD to get tokens, then you can skip ahead to Next Steps for information and samples specific to Microsoft Graph.
Access tokens issued by Azure AD are base 64 encoded JSON Web Tokens (JWT). They contain information (claims) that web APIs secured by Azure AD, like Microsoft Graph, use to validate the caller and to ensure that the caller has the proper permissions to perform the operation they're requesting. When calling Microsoft Graph, you can treat access tokens as opaque. You should always transmit access tokens over a secure channel, such as transport layer security (HTTPS).
Here's an example of an Azure AD access token:
To call Microsoft Graph, you attach the access token as a Bearer token to the Authorization header in an HTML request. For example, here's a call that returns the profile information of the signed-in user (the access token has been truncated for readability):
HTTP/1.1 Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg== Host: graph.microsoft.com` GET https://graph.microsoft.com/v1.0/me/
Microsoft Graph exposes a rich set of granular permissions over the resources it controls. These permissions are expressed as strings and grant apps access to Microsoft Graph resources like users, groups, user mail, etc. For example:
There are two types of permissions:
For a complete list of Microsoft Graph permissions, as well as the differences between Delegated and Application permissions, see the Permissions reference.
Your app gets access tokens from Azure Active Directory (Azure AD), Microsoft's cloud identity service. To get an access token, your app exchanges HTTP requests and responses with Azure AD using industry-standard protocols defined in the OAuth 2.0 and OpenID Connect 1.0 specifications. These protocols describe the Azure AD endpoints and exchanges with them -- or authentication flows -- that your app uses to securely authenticate with Azure AD and get access tokens.
On a very simple level, to get an access token, your app exchanges HTTP requests with the following endpoints:
/authorizeendpoint, where your app can send a user to authenticate with Azure AD and consent to the permissions your app needs.
/tokenendpoint where your app can get an access token once user consent has been granted.
(Note: These definitions are not rigid. Depending on the protocol your app uses, it may get access tokens directly from the
/authorize endpoint or it may authenticate directly with the
Here's an example of one set of the
/token endpoints exposed by Azure AD v2.0:
Azure AD exposes two sets of endpoints, Azure AD and Azure AD v2.0. The main difference between them is that Azure AD endpoint supports only work or school accounts (that is, accounts that are associated with an Azure AD tenant), while Azure AD v2.0 also supports Microsoft accounts like Live.com or outlook.com accounts. This means that if you use the Azure AD endpoint, your app can target only organizations, but with Azure AD v2.0 it can target both consumers and organizations.
Tokens from the Azure AD endpoint are not interchangeable with those from the Azure AD v2.0 endpoint, so before you begin work on an app for production, you must choose between the endpoints. Because the Azure AD v2.0 endpoint is newer and features are still being added, there are some important limitations that you need to factor into your decision about which endpoint to use for your app in production. For more information, see Deciding between the Azure AD and Azure AD v2.0 endpoints.
OAuth 2.0 is an authorization protocol. It defines how your app can get access tokens by authenticating directly with Azure AD or by redirecting a user to authenticate with Azure AD and consent to the permissions your app requests. In the first case, your app gets an access token that it can use to call Microsoft Graph as itself. In second case, your app gets an access token that it can use to call Microsoft Graph on behalf of a user. With OAuth 2.0, however, your app does not receive any information about the user or how they were authenticated by Azure AD. OAuth 2.0 flows are most often used by mobile or native apps, which already know the identity of the user; or by apps like background services or daemons, which call Microsoft Graph under their own identity and not on behalf of a user.
OpenID Connect extends OAuth 2.0 to provide an identity layer. With OpenID Connect, in addition to an access token, your app can also get an id token from Azure AD. OpenID Connect id tokens contain claims about the user's identity and details about how and where they were authenticated. OpenID Connect flows are typically used by web apps, including single page apps (SPAs). These apps can use the id token to customize their behavior for the user they've requested an access token for, and, in many cases, will outsource sign-in of their users to Azure AD and enable experiences like Single Sign-on (SSO).
You can call Microsoft Graph from the following kinds of apps:
Before your app can get a token from Azure AD, it must be registered. For the Azure AD v2.0 endpoint, you use the Microsoft App Registration Portal to register your app. For the Azure AD endpoint, you use the Azure portal. Registration integrates your app with Azure AD and establishes the coordinates and identifiers that it uses to get tokens. These are:
For apps that use the Azure AD endpoint, you'll also pre-configure the Microsoft Graph permissions that your app needs during registration. For apps that use the Azure AD v2.0 endpoint, you may or may not need to pre-configure permissions.
The properties configured during registration are used on the wire. For example, in the following token request: client_id is the Application Id, redirect_uri is one of your app's registered Redirect URIs, and client_secret is the Application Secret.
// Line breaks for legibility only POST /common/oauth2/v2.0/token HTTP/1.1 Host: https://login.microsoftonline.com Content-Type: application/x-www-form-urlencoded client_id=6731de76-14a6-49ae-97bc-6eba6914391e &scope=user.read%20mail.read &code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr... &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F &grant_type=authorization_code &client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Like most developers, you will probably use authentication libraries to manage your interactions with Azure AD. Authentication libraries abstract many protocol details, like validation, cookie handling, token caching, and maintaining secure connections, away from the developer and let you focus your development on your app. Microsoft publishes open source client libraries and server middleware for both the Azure AD and Azure AD v2.0 endpoints.
For the Azure AD v2.0 endpoint:
For a complete list of Microsoft client libraries, Microsoft server middleware, and compatible third-party libraries, see Azure Active Directory v2.0 authentication libraries.
For the Azure AD endpoint:
For a complete list of Microsoft client libraries and server middleware, see Azure Active Directory Authentication Libraries.
Azure AD exposes two sets of endpoints, Azure AD and Azure AD v2.0, where you can get access tokens to use when you call Microsoft Graph. Tokens received from each endpoint are not interchangeable. To run samples or explore the functionality of Microsoft Graph, your choice of Azure AD endpoints is not critical. However, before you begin development on a production app, you need to decide which endpoint makes the best sense for your scenario. The following discussion provides some general guidelines that you can use to help make your decision, but for the most current and comprehensive information you must see Should I use the v2.0 endpoint? in the Azure Active Directory documentation.
The main difference between Azure AD and Azure AD v2.0 is that:
There are some additional advantages with Azure AD v2.0. For example:
Because Azure AD v2.0 is newer than Azure AD and features are still being added, there are some limitations with the v2.0 endpoint that you need to factor into your decision. For example:
For more information about differences between the Azure AD v2.0 endpoint and the Azure AD endpoint, see What's different about the v2.0 endpoint?.
Before making a decision about which endpoint to use when developing an app for production, consult Should I use the v2.0 endpoint?.
Once you've registered your app, you're ready to get started!
If you're ready to jump into code, you can use the following resources to help you implement authentication and authorization with Azure AD in your app.
Microsoft publishes Connect samples for Microsoft Graph for a wide variety of platforms, including: Android, Angular.JS, ASP.NET, iOS (Obj-C and Swift), Node.JS, PHP, Python, Ruby, UWP, and Xamarin. You can use these samples to examine code that uses various authentication libraries to get tokens from Azure AD. Currently, most samples use third-party authentication libraries; however, the ASP.NET and UWP samples use Microsoft libraries.
The Azure AD documentation contains articles and samples that specifically focus on authentication and authorization with Azure AD.
For the Azure AD v2.0 endpoint:
For the Azure AD endpoint: