Microsoft identity platform (v2.0) - Gary-Moore/developmentwiki GitHub Wiki

Overview

Microsoft identity platform is an evolution of the Azure Active Directory (Azure AD) developer platform. It allows developers to build applications that sign in all Microsoft identities and get tokens to call Microsoft APIs, such as Microsoft Graph, or APIs that developers have built. The Microsoft identity platform consists of:

OAuth 2.0 and OpenID Connect standard-compliant authentication service that enables developers to authenticate any Microsoft identity, including:

  • Work or school accounts (provisioned through Azure AD)
  • Personal Microsoft accounts (such as Skype, Xbox, and Outlook.com)
  • Social or local accounts (via Azure AD B2C)
  • Open-source libraries: Microsoft Authentication Libraries (MSAL) and support for other standards-compliant libraries
  • Application management portal: A registration and configuration experience built in the Azure portal, along with all your other Azure management capabilities.
  • Application configuration API and PowerShell: which allows programmatic configuration of your applications through REST API (Microsoft Graph and Azure Active Directory Graph 1.6) and PowerShell, so you can automate your DevOps tasks.

The basics

You must register each app that uses the Microsoft identity platform endpoint in the new App registrations portal. The app registration process collects and assigns these values for your app:

  • An Application (client) ID that uniquely identifies your app
  • A Redirect URI that you can use to direct responses back to your app
  • A few other scenario-specific values such as supported account types

After the app is registered, the app communicates with Microsoft identity platform by sending requests to the endpoint. You also have the option to implement the authentication logic yourself by creating requests to these endpoints:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize
https://login.microsoftonline.com/common/oauth2/v2.0/token

Single-page apps (JavaScript)

Many modern apps have a single-page app front end that primarily is written in JavaScript. Often, it's written by using a framework like Angular, React, or Vue. The Microsoft identity platform endpoint supports these apps by using the OAuth 2.0 implicit flow.

In this flow, the app receives tokens directly from the Microsoft identity platform authorize endpoint, without any server-to-server exchanges. All authentication logic and session handling takes place entirely in the JavaScript client, without extra page redirects.

Web apps

For web apps (.NET, PHP, Java, Ruby, Python, Node) that the user accesses through a browser, you can use OpenID Connect for user sign-in. In OpenID Connect, the web app receives an ID token. An ID token is a security token that verifies the user's identity and provides information about the user in the form of claims:

// Partial raw ID token
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImtyaU1QZG1Cd...

// Partial content of a decoded ID token
{
    "name": "John Smith",
    "email": "[email protected]",
    "oid": "d9674823-dffc-4e3f-a6eb-62fe4bd48a58"
    ...
}

You can ensure the user's identity by validating the ID token with a public signing key that is received from the Microsoft identity platform endpoint. A session cookie is set, which can be used to identify the user on subsequent page requests.

In addition to simple sign-in, a web server app might need to access another web service, such as a REST API. In this case, the web server app engages in a combined OpenID Connect and OAuth 2.0 flow, by using the OAuth 2.0 authorization code flow.

Web APIs

You can use the Microsoft identity platform endpoint to secure web services, such as your app's RESTful Web API. Instead of ID tokens and session cookies, a Web API uses an OAuth 2.0 access token to secure its data and to authenticate incoming requests. The caller of a Web API appends an access token in the authorization header of an HTTP request, like this:

GET /api/items HTTP/1.1
Host: www.mywebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6...
Accept: application/json
...

The Web API uses the access token to verify the API caller's identity and to extract information about the caller from claims that are encoded in the access token. Further details of different types of tokens used in the Microsoft identity platform endpoint are available in the access token reference and id_token reference

A Web API can give users the power to opt in or opt out of specific functionality or data by exposing permissions, also known as scopes. For a calling app to acquire permission to a scope, the user must consent to the scope during a flow. The Microsoft identity platform endpoint asks the user for permission, and then records permissions in all access tokens that the Web API receives. The Web API validates the access tokens it receives on each call and performs authorization checks.

A Web API can receive access tokens from all types of apps, including web server apps, desktop and mobile apps, single-page apps, server-side daemons, and even other Web APIs.

In many cases, web APIs also need to make outbound requests to other downstream web APIs secured by Microsoft identity platform. To do so, web APIs can take advantage of the On-Behalf-Of flow, which allows the web API to exchange an incoming access token for another access token to be used in outbound requests.

Microsoft Identity Platform