Azure Active Directory API Essential Guide

What type of API does Azure Active Directory provide?

REST API

Azure AD exposes its functionality through a REST API, which is part of the Microsoft Graph API. This means:

• It uses standard HTTP methods (GET, POST, PUT, DELETE, etc.) for operations
• It follows RESTful principles like resource-based URLs and stateless communication
• Data is typically exchanged in JSON format

GraphQL Support

While Azure AD itself doesn't natively offer a GraphQL API, Microsoft has introduced features to support GraphQL:

• Azure API Management now offers "Synthetic GraphQL" which allows building a GraphQL service from existing REST APIs
• This feature enables modernizing API infrastructure without losing investment in existing REST API development

SOAP API

Azure AD does not use SOAP as its primary API type. SOAP is an older protocol that is less commonly used in modern web services compared to REST.

Key Considerations

1. REST APIs are widely adopted and have a large ecosystem of tools and libraries
2. GraphQL offers more flexibility in data fetching, allowing clients to request exactly what they need
3. The Synthetic GraphQL feature in Azure API Management bridges the gap between REST and GraphQL, offering benefits of both

Best Practices

1. When working with Azure AD, familiarize yourself with RESTful principles and the Microsoft Graph API documentation
2. Consider using Azure API Management's Synthetic GraphQL if you need GraphQL-like functionality over existing REST APIs
3. Keep in mind that while REST is the primary API type for Azure AD, the ecosystem around it is evolving to support more modern API paradigms like GraphQL

Does the Azure Active Directory API have webhooks?

Yes, Azure AD supports webhooks for receiving change notifications, but they are implemented through Microsoft Graph rather than directly in the Azure AD API.

You can subscribe to change notifications for various resources in Azure AD through Microsoft Graph, including:

• Azure Active Directory resources
• Microsoft Exchange resources
• OneDrive resources
• SharePoint resources
• Security Graph resources
• Microsoft Teams resources (conversations, meetings, shifts, presence status)
• Microsoft Outlook resources
• To Do resources
• Universal Print resources

Webhooks are implemented through Microsoft Graph change notifications. You can use traditional webhooks or Azure Event Hubs to receive notifications. Azure Event Hubs is recommended for high-throughput scenarios, as it eliminates the need for notification URL validation. To use Event Hubs delivery, you need to provision an Azure Event Hub and Azure Key Vault.

When using Event Hubs, the Event Hubs SDK is used to receive change notifications. Consider using Azure Event Hubs for high-throughput scenarios or when you can't expose a public notification URL. Implement proper authentication and validation for webhook endpoints to prevent security issues, and use Microsoft Entra authentication to secure your webhook endpoints.

Rate Limits and other limitations

Based on the search results, here are the key points regarding API rate limits for Azure Active Directory (Azure AD):

General Azure Resource Manager API Limits

• There are limits for API calls to Azure Resource Manager. You can make API calls at a rate within these limits.

Azure AD B2C Specific Limits

For Azure AD B2C tenants:

• Maximum requests per IP per Azure AD B2C tenant: 6,000 per 5 minutes
• Maximum requests per Azure AD B2C tenant: 200 per second

Azure AD Graph API Limits

While not officially documented, some sources indicate:

• There is a limit of 1000 requests per second to the Graph API service from a single source IP address.
• There is also a separate ApplicationID+TenantID limit of 120 requests per second.

Key Points to Consider

• The limits may vary depending on the specific API and service tier you are using.
• Limits are often applied per tenant, per application, or per IP address.
• Microsoft recommends implementing retry logic with exponential backoff to handle potential throttling.

Best Practices

1. Implement proper error handling and retry logic in your applications.
2. If you need higher limits, consider spreading requests across multiple source IPs and applications.
3. Monitor your API usage and stay within the documented limits to avoid throttling.
4. For official and up-to-date information on limits, it's best to consult the latest Microsoft documentation or contact Microsoft Support directly.

It's important to note that API limits and throttling policies can change over time, so always refer to the most recent official documentation for the most accurate information.

Latest API Version

Here are the key points about the most recent version of the Azure Active Directory API:

1. The most recent generally available version of the Azure AD Management REST API is 2022-09-01 [3].

2. This version added authentication properties to the Create or Update Service and Update Service operations [3].

3. It also made role-based access control generally available [3].

4. There is a newer preview version 2021-04-01-Preview that adds additional functionality like:

   • Preview support for role-based access control
   • Ability to enable/disable semantic search
   • Enforce encryption of data plane resources via Customer Managed Keys
   • Disable workloads that push data from Azure AD Search to external resources [3]

5. For the Azure AD Graph API specifically, Microsoft is in the process of retiring it in stages:

   • After June 30, 2024, new applications created will not be able to access Azure AD Graph APIs by default [2]
   • Existing applications created before June 30, 2024 will still be able to access Azure AD Graph APIs at this stage [2]
   • Microsoft recommends migrating to Microsoft Graph instead of Azure AD Graph [2]

6. For Azure AD PowerShell modules:

   • As of March 30, 2024, AzureAD, AzureAD-Preview, and Microsoft Online (MSOL) PowerShell modules are deprecated [2]
   • Microsoft recommends migrating to Microsoft Graph PowerShell instead [2]

So in summary, while 2022-09-01 is the latest GA version, Microsoft is actively moving away from Azure AD Graph API and older PowerShell modules in favor of Microsoft Graph. Developers should plan to migrate to Microsoft Graph for future compatibility.

How to get a Azure Active Directory developer account and API Keys?

1. Create an Azure account

If you don't already have one, you'll need to create a Microsoft Azure account. This will give you access to Azure Active Directory.

2. Set up an Azure Active Directory tenant

Once you have an Azure account:

• Go to the Azure portal (portal.azure.com)
• Create a new Azure AD tenant or use an existing one
• This will be the directory where you'll register your application

3. Register an application in Azure AD

To create an API integration, you need to register an application:

• In the Azure portal, go to Azure Active Directory
• Select "App registrations" and click "New registration"
• Give your app a name and select the supported account types
• For the redirect URI, select "Web" and enter a URL (can be updated later)
• Click "Register"

4. Configure API permissions

After registering the app:

• Go to "API permissions" for your registered app
• Add any permissions needed for Microsoft Graph or other APIs
• Grant admin consent for the permissions if required

5. Get credentials

You'll need these to authenticate your application:

• Application (client) ID - found on the app's Overview page
• Directory (tenant) ID - also on the Overview page
• Client secret - create one in "Certificates & secrets"

What can you do with the Azure Active Directory API?

Here's the markdown text with the trailing list of URLs and citation references removed, and any URLs inside the content formatted correctly for the markdown file format:

Here's a list of data models you can interact with using the Azure Active Directory API, along with what is possible for each:

User

• Create, read, update, and delete user accounts
• Manage user properties like display name, job title, department, etc.
• Assign and remove licenses
• Manage group memberships
• Reset passwords
• Enable/disable accounts

Group

• Create, read, update, and delete groups
• Manage group properties like description, visibility, etc.
• Add and remove group members
• Assign group owners
• Manage dynamic group membership rules

Application

• Register and manage applications
• Configure app properties, permissions, and credentials
• Manage app roles and assignments
• Configure single sign-on settings

Device

• Register and manage devices
• Enable/disable devices
• Manage device compliance state
• Assign device owners

Role

• Create and manage custom roles
• Assign and remove role assignments
• Manage role properties and permissions

Policy

• Create and manage conditional access policies
• Configure authentication methods policies
• Manage identity protection policies

Directory

• Manage directory settings
• Configure multi-factor authentication settings
• Manage custom security attributes

Administrative Unit

• Create and manage administrative units
• Assign resources and roles to administrative units

Service Principal

• Create and manage service principals
• Manage app permissions and consent
• Configure certificate and secret credentials

Domain

• Add and verify custom domains
• Manage domain authentication settings

Invitation

• Create and manage guest user invitations
• Configure external collaboration settings

These data models allow you to programmatically manage various aspects of Azure Active Directory, including users, groups, applications, devices, roles, policies, and more. The API provides comprehensive capabilities for creating, reading, updating, and deleting these entities, as well as managing their associated properties and relationships.