Setup

Connect Microsoft Entra ID to Ravenna using OAuth 2.0 with admin consent to enable user, group, and application synchronization from your tenant.

Connect your Microsoft Entra ID (formerly Azure Active Directory) organization to Ravenna through OAuth 2.0 with admin consent.

Prerequisites

Before you begin, ensure you have:

• Microsoft Entra ID administrator access (Global Administrator or Application Administrator role)
• Your Microsoft Entra tenant domain
• Permissions to grant admin consent for applications

Setup guide

Register Ravenna in Microsoft Entra ID

1. Navigate to integrations

   Go to Settings > Integrations in your Ravenna workspace

2. Select Microsoft Entra ID

   Select Microsoft Entra ID from the available integrations

3. Start OAuth flow

   Click Connect with Microsoft to begin the OAuth 2.0 authorization flow

4. Grant admin consent

   Sign in with your Microsoft administrator account and review the permissions Ravenna requests:

   • Read user profiles
   • Read group memberships
   • Read application assignments
   • Manage group memberships (for workflow actions)
   • Manage application access (for workflow actions)

   Click Accept to grant admin consent for your organization

5. Complete setup

   You’ll be redirected back to Ravenna with the integration connected

Admin consent is required because Ravenna needs organization-wide access to manage users, groups, and applications through Microsoft Graph API. Individual user consent is insufficient for these operations.

Required permissions

Ravenna requests the following Microsoft Graph API permissions:

Permission	Type	Purpose
User.ReadWrite.All	Application	Read user profiles, create users, suspend/restore accounts, reset passwords
Group.ReadWrite.All	Application	Create, update, delete groups and manage memberships
Application.Read.All	Application	Read application assignments for provisioning workflows
UserAuthenticationMethod.ReadWrite.All	Application	Reset MFA for users through workflows

Enable privileged operations

To use the Reset Password, Reset MFA, and Delete User workflow actions, you must assign an admin role to the Ravenna application in Microsoft Entra ID. This is required because Entra enforces role-based access control for sensitive operations.

Without this role assignment, these actions will fail with an “Insufficient privileges” error.

Assign the Privileged Authentication Administrator role

1. Open Microsoft Entra admin center

   Navigate to Microsoft Entra admin center and sign in with a Global Administrator account

2. Go to Roles and administrators

   In the left navigation, expand Entra ID > Roles & admins

3. Find the Privileged Authentication Administrator role

   Search for Privileged Authentication Administrator and click the role name (not the checkbox) to open the role details

4. Add assignment

   Click + Add assignments

5. Select the Ravenna application

   In the “Select member(s)” panel, search for Ravenna

   Select the Ravenna Enterprise application and click Add

6. Confirm the assignment

   The role assignment takes effect immediately. You can now use Reset Password and Reset MFA actions in workflows.

Role options

Choose the appropriate role based on your security requirements:

Role	Actions enabled	Use case
Password Administrator	Reset Password (non-admin users only)	Standard helpdesk operations
User Administrator	Delete User	User lifecycle management
Privileged Authentication Administrator	Reset Password, Reset MFA, Delete User (all users)	Full credential and user management

We recommend Privileged Authentication Administrator for most deployments as it enables all privileged workflow actions without unexpected failures.

Troubleshooting

Admin consent required error

Cause: Only users with administrator roles can grant admin consent

Solution:

• Ensure you’re signed in with a Global Administrator or Application Administrator account
• Contact your organization’s administrator to grant consent
• Check your Entra ID role assignments in the Azure portal

Insufficient privileges error

Cause: Missing required Microsoft Graph API permissions

Solution:

• Review the permissions requested during OAuth flow
• Ensure admin consent was granted for all requested permissions
• Try disconnecting and reconnecting the integration
• Verify your Entra ID tenant allows third-party app integrations

Password or MFA reset fails with insufficient privileges

Cause: The Ravenna application is missing the required admin role assignment

Solution:

• Follow the steps in Enable password and MFA management to assign the Privileged Authentication Administrator role
• Ensure you’re assigning the role to the Ravenna service principal, not a user account
• If resetting passwords for admin users, you must use Privileged Authentication Administrator (not Password Administrator)
• Role assignments take effect immediately - no restart required

Tenant not found error

Cause: Incorrect tenant domain or tenant is unavailable

Solution:

• Verify your Microsoft Entra tenant domain is correct
• Ensure the tenant is active and accessible
• Check Azure portal for tenant status
• Contact Microsoft support if tenant issues persist

OAuth redirect error

Cause: Redirect URI mismatch or OAuth configuration issue

Solution:

• Ensure pop-ups are not blocked in your browser
• Try clearing browser cache and cookies
• Use a different browser if the issue persists
• Contact Ravenna support if OAuth flow continues to fail

Security considerations

Ravenna uses OAuth 2.0 with admin consent to securely access your Microsoft Entra ID organization. Tokens are encrypted and stored securely, and Ravenna only accesses data necessary for configured workflows.

• Token security: OAuth tokens are encrypted at rest and in transit
• Least privilege: Only requested permissions are granted
• Audit trail: All API calls are logged for compliance and security review
• Revocation: You can revoke Ravenna’s access at any time through Azure portal