Azure Active Directory Reference

This section provides detailed technical reference information for Azure Active Directory (Azure AD), including APIs, authentication protocols, and configuration settings.

Authentication Protocols

Azure AD supports several standard authentication and authorization protocols to secure access to applications and resources.

OpenID Connect (OIDC)

OIDC is an identity layer on top of the OAuth 2.0 protocol. Azure AD implements OIDC to enable secure authentication and single sign-on (SSO) for your applications.

Key endpoints:

/authorize: Used to initiate the authentication flow.
/token: Used to obtain access tokens and refresh tokens.
/userinfo: Used to retrieve information about the authenticated user.

Learn more about OIDC in Azure AD

OAuth 2.0

OAuth 2.0 is a delegation protocol that allows third-party applications to obtain limited access to an HTTP service, either on behalf of a resource owner or by allowing the HTTP service to delegate the creation of specific access requests to third-party applications.

Common flows include:

Authorization Code Flow
Client Credentials Flow
On-Behalf-Of Flow

Explore OAuth 2.0 roles and flows

SAML 2.0

Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, specifically between an identity domain provider and a service provider.

Azure AD acts as an identity provider (IdP) for SAML-based SSO. When a user attempts to access a service provider (SP) that trusts Azure AD, the SP redirects the user to Azure AD for authentication. After successful authentication, Azure AD sends a SAML assertion back to the SP.

Understand SAML integration with Azure AD

Microsoft Graph API Reference

The Microsoft Graph API is a unified endpoint that provides access to data and intelligence in Microsoft 365 and Windows. It allows you to interact with Azure AD programmatically.

Key resources you can manage:

Users
Groups
Applications
Organizational settings
Service principals

Example: Fetching user information

GET https://graph.microsoft.com/v1.0/users/{id}

Microsoft Graph User Resource Type

Microsoft Graph Documentation

Configuration Settings

This section details various configuration options available within Azure AD to manage your tenant and its security.

Tenant Settings

Manage global settings for your Azure AD tenant, including branding, custom domains, and user features.

Conditional Access Policies

Conditional Access policies are decision points that let you put controls in place to ensure only authorized access to your cloud apps. Policies can be used to enforce controls like multifactor authentication (MFA), device compliance, and location-based restrictions.

Policy components:

Assignments: Define who the policy applies to (users, groups).
Cloud Apps or Actions: Specify the target resources (applications, user actions).
Conditions: Set granular conditions (device platform, client applications, locations, sign-in risk).
Access Controls: Define the grants or blocks (grant access, require MFA, require compliant device).

Deep dive into Conditional Access policies

Identity Protection

Azure AD Identity Protection leverages machine learning and AI to detect and respond to potential vulnerabilities in your organization's identities. It provides risk detection, risk-based policies, and security reports.

REST APIs and SDKs

Beyond Microsoft Graph, Azure AD exposes several REST APIs for specific management tasks. Software Development Kits (SDKs) are available for various programming languages to simplify integration.

Key APIs include:

Azure AD Graph API (legacy, but still used in some scenarios)
Microsoft Graph API (recommended for new development)

SDKs are available for:

.NET
Java
Python
JavaScript/TypeScript
Go
PHP

Azure AD SDKs

Common Reference Tables

HTTP Status Codes

Understanding common HTTP status codes returned by Azure AD APIs is crucial for troubleshooting.

Code	Description
`200 OK`	The request succeeded.
`201 Created`	The resource was successfully created.
`400 Bad Request`	The request was malformed or invalid.
`401 Unauthorized`	Authentication failed or is required.
`403 Forbidden`	The authenticated user does not have permission to perform the action.
`404 Not Found`	The requested resource could not be found.
`429 Too Many Requests`	The client has sent too many requests in a given amount of time.
`500 Internal Server Error`	An unexpected error occurred on the server.

Error Codes

Azure AD uses specific error codes to provide more detail about API errors.

Code	Description
`invalid_request`	The request is missing a required parameter, contains invalid parameter values, cannot be parsed, or is otherwise malformed.
`unauthorized_client`	The client is not authorized to perform this request.
`access_denied`	The resource owner or authorization server denied the request.
`invalid_scope`	The requested scope is invalid, unknown, or malformed.
`server_error`	The authorization server encountered an unexpected condition.

Note: The Azure AD Graph API is being retired and will be fully retired by December 31, 2022. We recommend migrating to Microsoft Graph for all new development.