# Microsoft Entra ID

Configure Microsoft Entra ID (Azure AD) integration with Risotto

Connect your Microsoft Entra ID (formerly Azure Active Directory) to Risotto to enable automated access management and group-based application provisioning.

> **Note:** **Looking for Dashboard SSO?** This integration is for managing user access to
> applications through Risotto. To configure SSO for signing into the Risotto
> dashboard itself, see [Dashboard Authentication
> Setup](https://www.tryrisotto.com/docs/guides/dashboard-authentication).

## Prerequisites

Before setting up the Microsoft Entra ID integration, ensure you have:

1. **Global Administrator Access** - Administrative privileges in your Microsoft Entra ID tenant
2. **Application Registration Rights** - Ability to register applications in your tenant
3. **Microsoft Graph API Permissions** - Access to configure application permissions

## Setup Process

### Step 1: Register Application in Microsoft Entra ID

1. **Access Azure Portal**

   1. Sign in to the [Azure Portal](https://portal.azure.com)
   2. Navigate to **Microsoft Entra ID**
   3. Select **App registrations** from the left menu

2. **Create New Registration**

   1. Click **New registration**
   2. Enter application details:
      - **Name**: `Risotto Integration`
      - **Supported account types**: Accounts in this organizational directory only
      - **Redirect URI**: Leave blank for now
   3. Click **Register**

3. **Note Application Details**

   After registration, copy and securely store:

   - **Application (client) ID**
   - **Directory (tenant) ID**

### Step 2: Configure API Permissions

1. **Add Microsoft Graph Permissions**

   1. In your app registration, select **API permissions**
   2. Click **Add a permission** > **Microsoft Graph** > **Application permissions**. Do not use delegated permissions.
   3. Add the following permissions:
      - `User.Read.All` - Read all user profiles
      - `Group.ReadWrite.All` - Read and write all groups
      - `GroupMember.ReadWrite.All` - Read and write all group memberships
      - `Application.Read.All` - Read all applications

2. **Grant Admin Consent**

   1. Click **Grant admin consent for \[Your Organization]**
   2. Confirm by clicking **Yes**
   3. Verify all permissions show **Granted for \[Your Organization]**

### Step 3: Create Client Secret

1. **Generate Secret**

   1. Navigate to **Certificates & secrets**
   2. Click **New client secret**
   3. Add description: `Risotto Integration`
   4. Set expiration (recommended: 24 months)
   5. Click **Add**

2. **Secure the Secret**

   **Immediately copy** the client secret value - it won't be shown again. Store it securely.

### Step 4: Configure Integration in Risotto

1. **Open the Microsoft Entra ID page**

   In your Risotto dashboard, go to **Settings > Integrations** and click the **Microsoft Entra ID** card. On the **App registration** card, click **Connect**.

   *Product example: The Microsoft Entra ID integration page in the Risotto dashboard, not connected, with Connect on the App registration card.*

2. **Enter the app registration details**

   The **Microsoft Entra ID** dialog opens, with the Entra steps in its **Instructions** pane. Enter:

   - **Tenant ID**: your Directory (tenant) ID from Step 1
   - **Client ID**: your Application (client) ID from Step 1
   - **Client Secret**: the secret value from Step 3

   The Tenant ID and Client ID must be GUIDs, like `a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d`. Click **Save**.

   *Product example: The Microsoft Entra ID setup dialog in the Risotto dashboard, with the Tenant ID, Client ID and Client Secret filled in and the Save button.*

3. **Check the connection**

   When you click **Save**, Risotto asks Microsoft for an access token with these credentials. If the Tenant ID, Client ID, or Client Secret is wrong, or the secret has expired, the dialog shows the error and nothing is saved. When the save succeeds, the **App registration** card shows the Tenant ID, the Client ID, and **Client Secret: Set**.

> **Note:** The save check does not test the Microsoft Graph permissions or the admin
> consent. A missing permission shows later, as a "Microsoft Graph Permission
> Error" the first time Risotto reads or changes a group. Grant admin consent
> for all four permissions before you rely on the connection.

## Sign-in Verification

See [Sign-in Verification](https://www.tryrisotto.com/docs/dashboard/settings/identity/sign-in-verification).

## Configuration Details

### Required Information

| Field             | Description                                   | Example                                |
| ----------------- | --------------------------------------------- | -------------------------------------- |
| **Tenant ID**     | Your Microsoft Entra ID tenant identifier     | `12345678-1234-1234-1234-123456789012` |
| **Client ID**     | Application (client) ID from app registration | `87654321-4321-4321-4321-210987654321` |
| **Client Secret** | Secret value generated in app registration    | `abc123...xyz789`                      |

### API Permissions

The integration requires these Microsoft Graph API permissions:

- **User.Read.All**: Read user profiles and the groups a user belongs to
- **Group.ReadWrite.All**: Read groups and their properties
- **GroupMember.ReadWrite.All**: Add users to groups and remove them for access control
- **Application.Read.All**: Read the applications in your tenant

The [Reset User Password](https://www.tryrisotto.com/docs/integrations/tools/entra/reset_password) and [Reset User MFA Factors](https://www.tryrisotto.com/docs/integrations/tools/entra/reset_mfa_factors) runbook tools need more permissions and a directory role. Their pages list them.

## Best Practices

> **Note:** **Group Strategy**: Use security groups to organize access levels. Examples: -
> `APP-Salesforce-Admins` - Administrative access to Salesforce -
> `APP-Salesforce-Users` - Standard user access to Salesforce -
> `APP-Salesforce-ReadOnly` - View-only access to Salesforce

> **Tip:** **Security**: Set client secret expiration reminders and rotate secrets before
> they expire to maintain continuous access.

> **Warning:** **Permissions**: Only grant the minimum required permissions. Regularly review
> and audit application permissions in your tenant.

## Troubleshooting

### Common Issues

**Authentication Failed**

- Verify the Tenant ID, Client ID, and Client Secret are correct
- Check that the client secret hasn't expired
- Ensure the application registration is in the correct tenant

**Permission Denied**

- Verify admin consent has been granted for all required permissions
- Check that the Global Administrator has approved the permissions
- Ensure the application has the correct Microsoft Graph permissions

**Groups Not Syncing**

- Confirm `Group.ReadWrite.All` and `GroupMember.ReadWrite.All` permissions are granted
- Verify group membership in Microsoft Entra ID
- Check that groups are security groups (not distribution groups)

> **Note:** There is no import wizard for Microsoft Entra ID applications. Create the
> application in Risotto and add its access rules by hand.

### Permission Reference

If you encounter permission errors, verify these Microsoft Graph permissions are configured:

```text
Application Permissions:
- User.Read.All
- Group.ReadWrite.All
- GroupMember.ReadWrite.All
- Application.Read.All
```

## Security Considerations

> **Warning:** **Least Privilege**: Follow the principle of least privilege. Only grant
> permissions that Risotto actually needs for your use case.

- **Secret rotation**: Risotto connects with the client secret. Before it expires, create a new secret in **Certificates & secrets**, then open the **App registration** card's **Connected** menu, choose **Configure...**, and save the new value
- **Conditional Access**: Configure conditional access policies to restrict when and how the application can access your tenant
- **Monitoring**: Enable audit logging and monitor application activity in Microsoft Entra ID logs

## Support

For additional help with Microsoft Entra ID integration:

- Review [Microsoft Graph permissions documentation](https://docs.microsoft.com/en-us/graph/permissions-reference)
- Check the [Applications documentation](https://www.tryrisotto.com/docs/dashboard/applications) for access rule configuration
- Consult [Microsoft Entra ID app registration guide](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app)
- Contact your Risotto administrator for organization-specific questions

Source: https://www.tryrisotto.com/docs/integrations/idp/microsoft-entra
