Microsoft Entra ID API Essential Guide

What type of API does Microsoft Entra ID provide?

Microsoft Entra ID primarily uses REST APIs exposed through Microsoft Graph. The key points are:

API Type

Microsoft Entra ID (formerly Azure AD) uses REST APIs, specifically through the Microsoft Graph API.

API Capabilities

The Microsoft Graph API for Microsoft Entra ID enables developers to:

• Manage user identities and control access to apps, data, and resources.
• Perform user management tasks like managing profiles, licenses, memberships, and privileges.
• Handle group management, including creating groups and controlling access to resources.
• Manage applications, including registering cloud apps and managing permissions.
• Secure access for external identities like customers and business partners.
• Implement governance features such as entitlement management and access reviews.
• Configure authentication methods and enforce conditional access policies.

API Access

Developers access these APIs through Microsoft Graph, which provides a unified endpoint for Microsoft 365 and other Microsoft cloud services. The APIs are RESTful and can be accessed using standard HTTP methods.

Comparison to Other API Types

While Microsoft Entra ID primarily uses REST APIs, it's worth noting the characteristics of other API types:

• SOAP APIs: Use XML for data exchange and are more complex but offer built-in security features.
• GraphQL APIs: Provide more flexible querying capabilities and efficient data fetching, but can be more complex to set up.

Does the Microsoft Entra ID API have webhooks?

Webhooks in Microsoft Entra ID API

Yes, the official Microsoft Entra ID API does support webhooks, but not directly. Instead, webhooks are supported through Azure Event Grid, which can be integrated with Microsoft Entra ID.

Event Types and Subscription

Azure Event Grid can be used to subscribe to various events from Microsoft Entra ID. While the search results don't provide a comprehensive list of event types, they do mention some key points:

1. Event Grid can deliver events to webhook endpoints protected by Microsoft Entra ID.

2. You can secure the webhook endpoint that's used to receive events from Event Grid by using Microsoft Entra ID.

3. To set this up, you need to:

   • Create a Microsoft Entra application
   • Create a role and a service principal in your application authorizing Event Grid
   • Configure the event subscription to use the Microsoft Entra application

Key Considerations

1. Authentication Methods: Event Grid uses different authentication methods to deliver events to event handlers, including access keys, managed system identity with role-based access control, bearer token authentication with Microsoft Entra protected webhook, and client secret as a query parameter.

2. Secure Delivery: You can secure webhook delivery using Microsoft Entra ID applications or users.

3. Cross-Tenant Scenarios: It's possible to deliver events to a webhook in a different Microsoft Entra tenant, but this requires specific configuration.

4. Role Assignment: The script creates a role named AzureEventGridSecureWebhookSubscriber in the Microsoft Entra app for your webhook.

5. Service Principal: A service principal for Microsoft.EventGrid is created if it doesn't already exist.

Best Practices

1. When rotating client secrets, make the webhook accept both old and new secrets for a limited duration before updating the event subscription with the new secret.

2. Use system-assigned identities for event delivery when possible.

3. Be cautious with query parameters as they may contain client secrets. They are stored encrypted and not accessible to service operators.

4. When retrieving Event Subscription properties, destination query parameters aren't returned by default for security reasons.

While the search results don't provide a comprehensive list of event types you can subscribe to, they do confirm that webhook support exists through Azure Event Grid integration with Microsoft Entra ID. For a detailed list of supported event types, you would need to consult the official Microsoft Entra ID documentation or Azure Event Grid documentation.

Rate Limits and other limitations

Here are the key API rate limits for Microsoft Entra ID based on the search results:

General Rate Limits

• For Directory, Sign in and Provisioning logs in Entra ID, the rate limit is 5 requests per 10 seconds [1].

• This default limit of 5 requests per 10 seconds is set by Microsoft to ensure stability and reliability of the service, and to prevent excessive API usage [1].

Application Proxy Limits

• Maximum of 500 transactions per second per Application Proxy application [5].

• Maximum of 750 transactions per second for the entire Microsoft Entra organization [5].

• A transaction is defined as a single HTTP request and response for a unique resource [5].

Resource Limits

• By default, a maximum of 50,000 Microsoft Entra resources can be created in a single tenant by users of the Microsoft Entra ID Free edition [5].

• If you have at least one verified domain, the default quota is extended to 300,000 Microsoft Entra resources [5].

• A non-admin user can create no more than 250 Microsoft Entra resources [5].

Best Practices for Handling Rate Limits

1. Implement a retry mechanism with exponential backoff to handle throttling errors [1].

2. Use filters to target queries to only the necessary data, using $filter and $select query parameters [4].

3. For broad data sets, use $filter on createdDateTime to limit the number of events queried in a single call [4].

4. Iterate through shorter timespans if requests are being throttled [4].

Key Points to Consider

• Rate limits are in place to ensure fair access to the service for all customers [1].

• Exceeding rate limits can result in throttling, slower response times, or request failures [1].

• The limits for Microsoft Entra External ID (for customers) are not yet available as it is in preview [3].

• Rate limits for existing B2B collaboration features remain unchanged [3].

In summary, developers need to be aware of these rate limits when working with Microsoft Entra ID APIs and implement appropriate strategies to handle throttling and optimize their requests. The specific limits vary depending on the type of operation and the edition of Microsoft Entra ID being used.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Microsoft Entra ID API:

Current API Version

The search results do not explicitly mention a specific version number for the Microsoft Entra ID API. However, they do provide information about recent updates and changes to Microsoft Entra ID services.

Key Points to Consider

1. Microsoft Entra ID (previously known as Azure Active Directory) receives ongoing improvements [1].

2. The most recent significant update mentioned is the General Availability of TLS 1.3 support for Microsoft Entra endpoints [1].

3. API-driven inbound provisioning has recently become Generally Available, allowing integration with any system of record [1].

4. Starting August 2024, new Microsoft Entra applications will have the default value of the 'requestedAccessTokenVersion' property set to '2' instead of 'null' (meaning '1') [1].

5. Microsoft Graph APIs are used for Microsoft Entra services to automate identity and access management tasks [3].

6. The Azure AD Graph API service is in the retirement cycle. Applications created after June 30, 2024, will receive an error (HTTP 403) for any requests to Azure AD Graph APIs [5].

Best Practices

1. Use the Microsoft Graph APIs for Microsoft Entra features instead of the deprecated Azure AD Graph API [3][5].

2. Keep up to date with the latest releases and changes by regularly checking the Microsoft Entra documentation and release notes [1].

3. Consider migrating from legacy user risk policies and sign-in risk policies to modern risk-based policies in Conditional Access [5].

4. Ensure you're using supported versions of Microsoft Entra Connect Sync (currently 2.1.20.0 or later) [5].

5. Be aware of upcoming changes, such as the retirement of legacy change password experiences and the automatic aging out of low-risk detections older than 6 months [5].

While the search results don't provide a specific API version number, they indicate that Microsoft Entra ID is continuously evolving, with recent updates focusing on security improvements, new features, and the transition from older Azure AD services to newer Microsoft Entra capabilities.

How to get a Microsoft Entra ID developer account and API Keys?

To get a developer account for Microsoft Entra ID and create an API integration, you can follow these steps:

1. Sign up for an Azure account

If you don't already have one, sign up for a free Azure account at https://azure.microsoft.com/free/. This will give you access to Azure services, including Microsoft Entra ID (formerly Azure Active Directory).

2. Access the Azure portal

Sign in to the Azure portal (https://portal.azure.com) using your Azure account credentials.

3. Create a Microsoft Entra ID tenant

If you don't already have a Microsoft Entra ID tenant:

• In the Azure portal, search for and select "Microsoft Entra ID"
• Click on "Create a tenant" and follow the prompts to create a new directory

4. Register your application

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

• In the Azure portal, navigate to "Microsoft Entra ID" > "App registrations"
• Click on "New registration"
• Provide a name for your application
• Choose the supported account types (e.g., accounts in this organizational directory only)
• Set the redirect URI if needed (for web applications)
• Click "Register"

5. Configure your application

After registration, you'll need to configure your application:

• Note down the Application (client) ID and Directory (tenant) ID
• If needed, create a client secret under "Certificates & secrets"
• Configure API permissions under the "API permissions" section
• Set up authentication settings as required for your application type

6. Implement authentication in your application

Use the Microsoft Authentication Library (MSAL) to implement authentication in your application. This will allow you to acquire tokens for accessing Microsoft Graph or other APIs.

What can you do with the Microsoft Entra ID API?

Based on the information provided, here are the key data models you can interact with using the Microsoft Entra ID API:

User Management

• User profiles: Look up and manage user information, licenses, memberships, and privileges
• Authentication methods: Manage authentication methods for users

Group Management

• Groups: Create and manage groups to control access to resources
• Administrative units: Organize groups, users, and devices for easier management

Application Management

• Application registration: Register cloud applications
• Application permissions: Manage app permissions and privileges
• Remote access: Provide secure remote access to on-premises applications

Role Management

• Administrative roles: Manage roles that grant specific permissions

Identity Governance

• Entitlement management: Automatically grant access for internal and external users
• Access reviews: Review access to groups, applications, and privileged roles
• Lifecycle workflows: Automate employee onboarding, internal movement, and offboarding
• Privileged Identity Management (PIM):
  • For Microsoft Entra roles: Manage time-bound administrator privileges
  • For groups: Govern access to groups with privileged access

Security

• Authentication methods: Configure multifactor authentication
• Conditional access policies: Enforce risk-based access policies
• Risk detection: Detect and report anomalies for potentially compromised accounts

External Identities

• Invite external users to your organization
• Customize sign-in and sign-up experiences for customers
• Manage collaboration with other Microsoft Entra ID tenants

Provisioning

• Inbound provisioning: Retrieve user data from HR sources like Workday and SuccessFactors
• User provisioning: Create, update, and remove user accounts in other applications

Data Consistency

• Replica management: Maintain data consistency across distributed replicas

This list covers the main data models and capabilities you can interact with using the Microsoft Entra ID API. Each of these areas provides various endpoints and operations for managing and securing identities and access within your organization.