Azure Active Directory API Essentials

Azure Active Directory (Azure AD) API is a powerful tool that allows developers to integrate authentication and authorization into their applications. It provides a single sign-on experience for users, eliminating the need to remember multiple usernames and passwords.

Azure AD API supports industry-standard protocols such as OAuth 2.0 and OpenID Connect, making it a versatile choice for developers. This allows developers to leverage their existing knowledge and skills to build secure and scalable applications.

To get started with Azure AD API, developers need to register their applications on the Azure portal. This involves creating an Azure AD tenant, registering an application, and configuring the necessary permissions and settings.

To get started with Azure Active Directory API, you need to register your app with Azure AD. This is a crucial step before you can access Azure AD objects using the API.

The Azure Active Directory Graph API is used to access Azure AD objects using REST API OData endpoints. You can use this API in your applications to perform CRUD operations on Azure AD data and objects.

Some common operations supported by Azure AD Graph API include creating a new user, getting properties of a user, updating properties of a user, and disabling or deleting the user account. These operations are essential for managing user data in Azure AD.

To access Azure AD objects, you must register your app with Azure AD and consent your app to access Azure AD Graph API. This is a straightforward process that requires some basic information about your app.

Here are some common operations supported by Azure AD Graph API:

By registering your app and consenting to access Azure AD Graph API, you can perform these operations and manage user data in Azure AD. This is a great way to get started with Azure Active Directory API.

To configure Azure AD, you must register an app in your Azure AD configuration and add a client secret credential that Kong will use to access it. You also need to configure a redirect URI that is handled by your route.

The Azure AD interface has two versions: v1.0 and v2.0. To force Azure AD to use v2.0 tokens, you need to edit your application manifest and set accessTokenAcceptedVersion to 2.

You can add an OpenID Connect plugin to your route using an HTTP client or Kong Manager with the configuration below. Some configurations require specific values from your environment, such as the issuer URL, which can be retrieved by clicking the Endpoints button on your app registration's Overview page.

Here are the configurations you need to replace with your own values:

After setting up the plugin, visiting a URL matched by that route in a browser will redirect to Microsoft's authentication site and return you to the redirect URI after authenticating.

To add an OpenID Connect plugin to your route, you'll need to configure it with specific values from your environment. This includes the issuer URL, which can be found on the app registration’s Overview page by clicking the Endpoints button.

The redirect URI should be the URI you specified earlier, which can be added via the Authentication section of the app settings if you didn't add one initially. For client_id and scopes, replace YOUR_CLIENT_ID with the client ID shown on the app Overview page.

You'll also need to replace client_secret with the URL-encoded representation of the secret you created earlier in the Certificates & secrets section. Azure AD secrets often include reserved URL characters, which cURL might handle incorrectly if they are not URL-encoded.

Here are the configurations you'll need to use:

Visiting a URL matched by that route in a browser will now redirect to Microsoft’s authentication site and return you to the redirect URI after authenticating.

Domain restrictions can be a bit tricky to set up, but they're essential for controlling who can access your application.

The OIDC plugin doesn't support domain restrictions in the way you might expect, especially when dealing with Azure AD.

Azure AD doesn't provide identity tokens with the hd claim, which means you can't restrict users based on their domain using the OIDC plugin's domains configuration.

Using a single-tenant application will restrict access to users in your directory only, which is a good option if you want to keep things simple.

Multi-tenant apps, on the other hand, allow users with Microsoft accounts from other directories and optionally any Microsoft account to sign in, which may not be what you want.

If you're looking for ways to restrict access further, you might want to consider using Domain Restrictions, Consumer Mapping, or Pseudo-Consumer Mapping.

Here are some options to consider:

If you're looking to configure scopes for Azure Active Directory, you'll want to read up on scope-based access control. Scopes provide a way to govern access to protected resources, allowing you to define read and write permissions for your web API.

You can use scopes to control what users can do with your web API, such as giving them read and write access or just read access. This is a great way to ensure that users can only do what they need to do.

To query top-level resources in Azure AD, you can use the following URIs:

To authenticate users with Azure Active Directory (AAD), you can use the authorization code grant or client credentials grant. The authorization code grant is used by web and native clients, requiring user credentials to delegate resource access. It involves requesting an authorization code from Azure AD using the /authorize endpoint, which triggers a sign-in prompt for the user.

This grant flow requires two steps: requesting an authorization code and redeeming it for an access token. The request to the /authorize endpoint includes query string parameters specific to the client application. The response is a redirect to the specified redirect URI with a code query parameter containing the authorization code.

To restrict access to certain users, you can use domain restrictions, consumer mapping, or pseudo-consumer mapping. These options allow you to limit access to specific users or groups within the directory.

There are two ways to acquire an access token: using Azure AD's platform/language-neutral OAuth2 service endpoints or the Microsoft Authentication Libraries (MSAL). The OAuth2 endpoints include the /authorize and /token endpoints, which are used to authenticate the client and acquire an access token.

Client credentials grant is used by web clients to access resources directly, without user delegation. It requires only the /token endpoint to acquire an access token. This grant flow is typically used by non-interactive clients running as a daemon or service.

To call a protected web API from an application, you need to grant your application permissions to the API. This involves selecting the application in Azure AD, adding API permissions, and granting admin consent for the required scopes.

Here's a summary of the authorization grant flows: