Microsoft Entra ID Integration

This section details the API endpoints for integrating with Microsoft Entra ID (formerly Azure Active Directory). This integration enables seamless user synchronization, automated certificate provisioning for Entra ID users, and robust token validation, which are crucial for enterprise identity and access management within the PKI system.

Key Functionalities

Get Entra ID Integration Statistics

Endpoint: GET /api/v1/entra-id/statistics
Description: Retrieves aggregated statistics related to the Microsoft Entra ID integration, providing insights into its operational status and synchronized data.

Health Check

Endpoint: GET /api/v1/entra-id/health
Description: Provides a health status check for the Microsoft Entra ID integration. This endpoint is publicly accessible and does not require specific permissions.

Sync User from Entra ID

Endpoint: POST /api/v1/entra-id/sync-user
Description: Synchronizes a single user from Microsoft Entra ID into the local PKI system's user database. This creates or updates a local user record with relevant Entra ID attributes.
Parameters:
- user_principal_name (required, string, email format): The User Principal Name (UPN) of the user to synchronize.
Response: Returns details of the synchronized user, including their local id, name, email, entra_id, entra_upn, is_active status, entra_last_sync timestamp, and entra_groups.

Provision Certificate for Entra ID User

Endpoint: POST /api/v1/entra-id/provision-certificate
Description: Issues a new certificate specifically for a user who has been synchronized from Microsoft Entra ID.
Parameters:
- user_id (required, integer): The local ID of the user for whom the certificate is to be provisioned. This user must exist locally and be synchronized with Entra ID.
- certificate_type (optional, string): The type of certificate to issue. Supported values: client_auth, email_protection, code_signing. Defaults to client_auth.
- validity_days (optional, integer, min 1, max 3650): The number of days the certificate will be valid for. Defaults to config('entra.default_certificate_validity_days', 365).
- key_size (optional, integer, in 2048, 3072, 4096): The cryptographic key size. Defaults to config('entra.default_key_size', 2048).
Precondition: The specified user_id must correspond to a user who has been synchronized with Entra ID.
Response: Returns details of the newly provisioned certificate and the associated user.

Validate Entra ID Token

Endpoint: POST /api/v1/entra-id/validate-token
Description: Validates a Microsoft Entra ID (JWT) token, verifying its signature, claims, and expiration. This can be used by other services to authenticate or authorize requests based on Entra ID identities.
Parameters:
- token (required, string): The JWT token to validate.
Response: Returns valid status and, if valid, the token's payload (including sub, upn, email, name, roles, groups, exp, iat). Returns 401 Unauthorized for invalid tokens.

List Entra ID Synchronized Users

Endpoint: GET /api/v1/entra-id/users
Description: Retrieves a paginated list of users who have been synchronized from Microsoft Entra ID into the local system.
Parameters (Optional):
- active (boolean): Filters users by their active status.
- recently_synced (integer, hours): Filters users synchronized within the last specified number of hours (defaults to 24).
- search (string): Searches users by name, email, or entra_upn.
- per_page (integer): Number of users per page (defaults to 15).
Response: Returns a paginated list of synchronized users, including their active certificates of type entra_user.

Get User Details with Entra ID Information

Endpoint: GET /api/v1/entra-id/users/{user}
Description: Retrieves detailed information for a specific user, including their synchronized Entra ID attributes and associated certificates.
Parameters:
- user (path parameter): The local ID of the user.
Precondition: The user must be synchronized with Entra ID.
Response: Returns comprehensive user details (local and Entra ID attributes) and a list of their associated certificates.

Bulk Sync Users from Entra ID

Endpoint: POST /api/v1/entra-id/bulk-sync-users
Description: Synchronizes multiple users from Microsoft Entra ID in a single request, based on a list of User Principal Names.
Parameters:
- user_principal_names (required, array of strings, min 1, max 50): An array of UPNs to synchronize.
Response: Returns a summary of the bulk synchronization (total, successful, failed counts) and individual results for each UPN.

Inferred Specifications

Deep Microsoft Entra ID Integration: The system provides extensive integration with Microsoft Entra ID for identity management, user synchronization, and authentication.
Automated User Provisioning: Supports both individual and bulk synchronization of users from Entra ID, streamlining user onboarding and maintaining up-to-date user records.
Certificate Provisioning for Entra ID Identities: Enables the automated issuance of certificates specifically tied to Entra ID user identities, facilitating secure access to resources for enterprise users.
Entra ID Token Validation Service: Offers a robust API for validating Entra ID JWT tokens, which is critical for implementing secure authentication and authorization mechanisms across distributed services.
Queryable Synchronized User Directory: Provides comprehensive API capabilities for listing, searching, and retrieving details of users synchronized from Entra ID.
Security: All API interactions (except health checks) are protected by auth:sanctum middleware and require the manage-entra-integration permission, ensuring secure and authorized access to Entra ID functionalities.
Configurable Certificate Provisioning: Allows for customization of certificate type, validity, and key size during provisioning for Entra ID users.
Bulk Operations for Efficiency: The bulkSyncUsers endpoint enhances efficiency for managing a large number of user synchronizations.
Error Handling: Provides detailed error responses for various failure scenarios, aiding in integration and troubleshooting.