> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Navigate to integrations">
    Go to **Settings > Integrations** in your Ravenna workspace
  </Step>

  <Step title="Select Microsoft Entra ID">
    Select **Microsoft Entra ID** from the available integrations
  </Step>

  <Step title="Start OAuth flow">
    Click **Connect with Microsoft** to begin the OAuth 2.0 authorization flow
  </Step>

  <Step title="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
  </Step>

  <Step title="Complete setup">
    You'll be redirected back to Ravenna with the integration connected
  </Step>
</Steps>

<Info>
  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.
</Info>

## 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.

<Warning>
  Without this role assignment, these actions will fail with an "Insufficient privileges" error.
</Warning>

### Assign the Privileged Authentication Administrator role

<Steps>
  <Step title="Open Microsoft Entra admin center">
    Navigate to [Microsoft Entra admin center](https://entra.microsoft.com) and sign in with a Global Administrator account
  </Step>

  <Step title="Go to Roles and administrators">
    In the left navigation, expand **Entra ID** > **Roles & admins**
  </Step>

  <Step title="Find the Privileged Authentication Administrator role">
    Search for **Privileged Authentication Administrator** and click the role name (not the checkbox) to open the role details
  </Step>

  <Step title="Add assignment">
    Click **+ Add assignments**
  </Step>

  <Step title="Select the Ravenna application">
    In the "Select member(s)" panel, search for **Ravenna**

    Select the Ravenna Enterprise application and click **Add**
  </Step>

  <Step title="Confirm the assignment">
    The role assignment takes effect immediately. You can now use Reset Password and Reset MFA actions in workflows.
  </Step>
</Steps>

### 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 |

<Info>
  We recommend **Privileged Authentication Administrator** for most deployments as it enables all privileged workflow actions without unexpected failures.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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](#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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Security considerations

<Info>
  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.
</Info>

* **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