# Microsoft 365 SCIM

  Steps,
  TabItem,
  LinkCard,
  CardGrid,
} from "@astrojs/starlight/components";

Microsoft Entra ID (Microsoft 365) can keep Probo people in sync through either the **SCIM Bridge** (recommended) or **Native** push provisioning. Use the tabs below to follow the path that matches how you want to synchronize.

:::tip[Recommended]
For Microsoft Entra ID, prefer the **SCIM Bridge**. Entra’s outbound SCIM support is limited in practice; the Bridge reads Microsoft Graph on a schedule and reconciles organization people reliably.
:::

This guide walks you through setting up the Probo Bridge to automatically synchronize users from Microsoft 365 (Entra ID) into Probo via SCIM.

## Prerequisites

- Microsoft Entra ID administrator access (to register an app and grant admin consent)
- Probo organization administrator access
- Ability to create an app registration in your Entra tenant

## How it works

The Microsoft 365 Bridge connects to Microsoft Graph using OAuth2, retrieves your organization’s directory users, and synchronizes them with Probo through the SCIM endpoint. The Bridge runs on a regular schedule and handles:

- **New users**: Creates Probo accounts for home-tenant members found in Entra ID
- **Updated users**: Syncs attribute changes (name, title, department, and so on)
- **Removed or disabled users**: Deactivates Probo accounts when members leave or are disabled
- **Excluded users**: Skips users you’ve explicitly excluded by email
- **Guests**: B2B guest users (`userType` Guest) are not provisioned

### Mapped attributes

| Microsoft Graph field | SCIM Attribute |
| --------------------- | --------------------------- |
| `mail` (fallback `userPrincipalName`) | `userName`, `emails` |
| `displayName` | `displayName` |
| `givenName` | `name.givenName` |
| `surname` | `name.familyName` |
| `accountEnabled` | `active` |
| `jobTitle` | `title` |
| `department` | `enterprise:department` |
| `companyName` | `enterprise:organization` |
| `employeeId` | `enterprise:employeeNumber` |
| `preferredLanguage` | `preferredLanguage` |
| `id` | `externalId` |

## Step 1: Register an Entra ID application

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com)
2. Go to **Identity** → **Applications** → **App registrations** → **New registration**
3. Configure the application:

   | Field | Value |
   | ----- | ----- |
   | **Name** | `Probo SCIM Bridge` |
   | **Supported account types** | Accounts in this organizational directory only |
   | **Redirect URI** | Platform **Web**, URI `https://your-probo-domain.com/api/console/v1/connectors/complete` |

4. Click **Register**
5. On the app **Overview**, copy the **Application (client) ID**
6. Go to **Certificates & secrets** → **New client secret**, create a secret, and copy its **Value** (shown only once)

## Step 2: Grant Microsoft Graph permissions

1. In the app registration, go to **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated permissions**
2. Add:

   | Permission | Purpose |
   | ---------- | ------- |
   | `openid`, `profile`, `offline_access` | Sign-in and refresh token |
   | `User.Read.All` | Read directory user profiles |
   | `Directory.Read.All` | Read organizational directory data |

   If you also use Microsoft 365 as an [access review source](/docs/product/access-review/overview), Probo’s connector may request additional Graph permissions such as `AuditLog.Read.All` and `RoleManagement.Read.Directory` during authorization.

3. Click **Grant admin consent for your tenant** and confirm

## Step 3: Configure the Bridge in Probo

1. Log in to Probo as an organization administrator
2. Go to **Organization Settings** → **Authentication** → **Auto-Provisioning**
3. Click **Add Connector** and select **Microsoft 365**
4. Enter your OAuth credentials:

   | Field | Value |
   | ----- | ----- |
   | **Client ID** | Your Entra Application (client) ID |
   | **Client Secret** | The client secret value from Step 1 |

5. Click **Authorize** to complete the OAuth flow — you’ll be redirected to Microsoft to grant access
6. After authorization, the Bridge connector will appear as **Pending**

## Step 4: Configure exclusions (optional)

If you have service accounts, shared mailboxes, or other users that should not be provisioned into Probo:

1. In the Bridge connector settings, go to **Excluded Users**
2. Add email addresses of users to exclude (case-insensitive)
3. Click **Save**

Excluded users will be skipped during synchronization. If an excluded user was previously provisioned, they will be removed on the next sync cycle.

## Step 5: Verify synchronization

After the Bridge is configured, it will begin synchronizing on its regular schedule (approximately every 30 seconds for polling, with a 5-minute sync timeout).

1. Go to **Organization Settings** → **Authentication** → **Auto-Provisioning**
2. Check the Bridge state — it should transition from **Pending** to **Syncing** and then to **Active**
3. Go to **People** to verify users have been provisioned
4. Check the **Event Log** for detailed sync activity

## Setting a user's role

Probo membership roles (**Owner**, **Admin**, and so on) are assigned in [People](/docs/product/roles-and-permissions) or mapped with the SAML [Role Attribute](/docs/product/sso/overview#membership-roles-from-saml). SCIM creates people as **Employee** by default.

Separately, syncing a job title helps Probo attribute policies and run meaningful access reviews. Without those profile fields, a user can still sign in but is harder to evaluate for least-privilege access.

Microsoft Graph syncs **Job title** (`jobTitle`) to Probo via the SCIM Bridge. Set it on the user in Entra ID under **Job information**, then wait for the next sync cycle.

:::tip
Keep job titles consistent across your team (avoid free-form variations like Eng, SWE, Engineer for the same role) so access reviews group people cleanly.
:::

## Troubleshooting

### Bridge stuck in "Pending"

- **Cause**: OAuth authorization was not completed, admin consent is missing, or the token has expired
- **Solution**: Confirm admin consent for `User.Read.All` and `Directory.Read.All`, then re-authorize the Microsoft 365 connector

### Bridge in "Failed" state

- **Cause**: The sync encountered an error (network issue, Graph rate limit, invalid credentials)
- **Solution**: Check the Event Log for error details. The Bridge will automatically retry with exponential backoff. If the issue persists after 10 consecutive failures, the Bridge will be disabled — fix the underlying issue and re-enable it manually.

### Users not appearing

- **Cause**: Users are B2B guests, lack a mail/UPN, or Graph permissions are incomplete
- **Solution**: The Bridge only syncs home-tenant members (`userType eq 'Member'`). Confirm the user has a `mail` or `userPrincipalName`, and that admin consent was granted

### Stale users not deactivated

- **Cause**: Users may be in the exclusion list, or the sync has not completed a full cycle yet
- **Solution**: Check the exclusion list and wait for the next sync cycle

### OAuth token expired

- **Cause**: The refresh token has been revoked or expired
- **Solution**: Re-authorize the connector. The Bridge automatically refreshes OAuth tokens, but if the refresh token itself is revoked (for example the secret was rotated or consent was withdrawn), you’ll need to re-authorize

:::caution[Prefer Bridge when you can]
Native push from Entra ID works, but Entra’s outbound SCIM behavior is limited in practice. Use **SCIM Bridge** unless you specifically need Native push provisioning.
:::

This guide walks you through setting up Native SCIM provisioning from Microsoft Entra ID so assigned users are pushed into Probo.

## Prerequisites

- Microsoft Entra ID administrator access (Global Administrator or Application Administrator)
- Probo organization administrator access
- A Microsoft 365 subscription with Entra ID P1 or higher (required for automatic provisioning)

## How it works

In Native mode, Microsoft Entra ID pushes user changes to Probo’s SCIM 2.0 endpoint. When you assign users or groups to the Probo enterprise application in Entra ID, it automatically:

- **Creates** Probo accounts for newly assigned users
- **Updates** user attributes when they change in Entra ID
- **Deactivates** Probo accounts when users are unassigned or disabled
- **Deletes** Probo accounts when users are permanently removed (if configured)

### Mapped attributes

**Core User attributes:**

| Entra ID Field | SCIM Attribute | Notes |
| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| userPrincipalName | `userName` | Required, unique |
| displayName | `displayName` | |
| givenName | `name.givenName` | |
| surname | `name.familyName` | |
| ImmutableId | `name.formatted` | |
| honorificPrefix | `name.honorificPrefix` | |
| honorificSuffix | `name.honorificSuffix` | |
| mailNickname | `nickName` | |
| accountEnabled | `active` | |
| mail | `emails[type eq "work"].value` | Multi-valued |
| telephoneNumber | `phoneNumbers[type eq "work"].value` | Multi-valued |
| streetAddress, city, state, postalCode, country | `addresses` | Multi-valued, with `streetAddress`, `locality`, `region`, `postalCode`, `country` sub-attributes |
| jobTitle | `title` | |
| userType | `userType` | |
| preferredLanguage | `preferredLanguage` | |
| usageLocation | `locale` | |
| preferredDataLocation | `timezone` | |
| mysiteUrl | `profileUrl` | |

**Enterprise User Extension attributes:**

| Entra ID Field | SCIM Attribute |
| -------------- | --------------------------- |
| employeeId | `enterprise:employeeNumber` |
| companyName | `enterprise:organization` |
| department | `enterprise:department` |
| division | `enterprise:division` |
| costCenter | `enterprise:costCenter` |
| manager | `enterprise:manager.value` |

## Step 1: Generate SCIM credentials in Probo

1. Log in to Probo as an organization administrator
2. Go to **Organization Settings** → **Authentication** → **Auto-Provisioning**
3. Click **Add Connector** and select **SCIM**
4. Copy the **SCIM Endpoint URL** and **Bearer Token**

   :::caution
   The bearer token is shown only once. Store it securely — you will need it in the next step.
   :::

## Step 2: Create an enterprise application in Entra ID

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com)
2. Go to **Identity** → **Applications** → **Enterprise applications**
3. Click **+ New application** → **Create your own application**
4. Enter the following:

   | Field | Value |
   | ------------------------------- | ----------------------------------------------------------------------------- |
   | **Name** | `Probo` |
   | **What are you looking to do?** | `Integrate any other application you don't find in the gallery (Non-gallery)` |

5. Click **Create**

## Step 3: Configure provisioning

1. In the Probo enterprise application, go to **Provisioning** in the left sidebar
2. Click **Get started**
3. Set **Provisioning Mode** to **Automatic**
4. Under **Admin Credentials**, enter:

   | Field | Value |
   | ---------------- | ------------------------------------------------------------------------------------------- |
   | **Tenant URL** | Your Probo SCIM endpoint URL (e.g. `https://your-probo-domain.com/api/connect/v1/scim/2.0`) |
   | **Secret Token** | The bearer token from Step 1 |

5. Click **Test Connection** to verify Entra ID can reach the Probo SCIM endpoint
6. Click **Save**

## Step 4: Configure attribute mappings

The default attribute mappings work for most setups. To review or customize them:

1. In the **Provisioning** page, expand **Mappings**
2. Click **Provision Microsoft Entra ID Users**
3. Review the attribute mappings — the defaults map to Probo’s supported SCIM attributes
4. Adjust mappings if needed (e.g. map `employeeId` to `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber`)
5. Click **Save**

:::tip
You can remove mappings for attributes you don’t use. Only `userName`, `displayName`, and `active` are required by Probo.
:::

## Step 5: Assign users and groups

1. In the Probo enterprise application, go to **Users and groups**
2. Click **+ Add user/group**
3. Select the users or groups you want to provision into Probo
4. Click **Assign**

Only assigned users (or members of assigned groups) will be provisioned. This gives you fine-grained control over who gets a Probo account.

## Step 6: Start provisioning

1. Go back to **Provisioning**
2. Set **Provisioning Status** to **On**
3. Click **Save**
4. Entra ID will start an initial provisioning cycle — this may take a few minutes depending on the number of users

After the initial cycle, Entra ID runs incremental sync approximately every 40 minutes to push any changes.

## Step 7: Verify provisioning

1. In Entra ID, go to **Provisioning** → **Provisioning logs** to see the sync activity
2. In Probo, go to **People** to verify users have been provisioned
3. Check **Organization Settings** → **Authentication** → **Auto-Provisioning** → **Event Log** for detailed SCIM events

## Setting a user's role

Probo membership roles (**Owner**, **Admin**, and so on) are assigned in [People](/docs/product/roles-and-permissions) or mapped with the SAML [Role Attribute](/docs/product/sso/overview#membership-roles-from-saml). SCIM creates people as **Employee** by default.

Separately, syncing job title and employee type helps Probo attribute policies and run meaningful access reviews:

- **Job title** → profile title (for example, Software Engineer)
- **Employee type** → employment type context (for example, Full-time, Contractor)

1. In the Microsoft Entra admin center, go to **Identity** → **Users** → **All users**
2. Select the user you want to update
3. Click **Edit properties**, then open the **Job information** tab
4. Set the **Job title** field
5. Set the **Employee type** field if you use it
6. Click **Save**
7. Wait for the next Entra provisioning cycle (or restart provisioning) for the values to appear in Probo

:::tip
Keep job titles and employment types consistent across your team (avoid free-form variations like Eng, SWE, Engineer for the same role) so access reviews group people cleanly.
:::

## Troubleshooting

### Test Connection fails

- **Cause**: The SCIM endpoint URL or bearer token is incorrect, or a firewall is blocking the connection
- **Solution**: Verify the endpoint URL includes the full path (ending in `/scim/2.0`). Re-generate the bearer token in Probo if needed. Ensure your network allows outbound HTTPS from Entra ID to your Probo instance.

### Users not being provisioned

- **Cause**: Users or groups are not assigned to the enterprise application, or provisioning is not turned on
- **Solution**: Check that the users are assigned under **Users and groups** and that **Provisioning Status** is set to **On**

### Provisioning errors in logs

- **Cause**: Attribute mapping conflicts or missing required attributes
- **Solution**: Check the **Provisioning logs** in Entra ID for specific error messages. Ensure `userName` is mapped to a unique, non-empty value (typically `userPrincipalName` or `mail`)

### Users not deactivated after removal

- **Cause**: Entra ID may still be processing the change, or the user was soft-deleted
- **Solution**: Check the provisioning logs for the deprovisioning event. Entra ID processes changes during the next sync cycle (approximately every 40 minutes). For immediate effect, trigger a manual sync by clicking **Restart provisioning** in the Provisioning page.

### Duplicate users

- **Cause**: The `userName` in Entra ID doesn’t match an existing Probo user’s email
- **Solution**: Ensure the attribute mapped to `userName` matches the email format used in Probo. You may need to adjust the mapping to use `mail` instead of `userPrincipalName`.

## Combining with SSO

For the best experience, combine SCIM provisioning with SAML SSO:

1. **SCIM** handles user lifecycle — creating and deactivating accounts automatically
2. **SAML SSO** handles authentication — users sign in with their Microsoft credentials

This means users get automatic Probo accounts when they join your organization and lose access when they leave, with no manual account management needed.

- [Microsoft Entra ID SSO](/docs/product/sso/microsoft-entra-id) — Set up SAML SSO alongside SCIM provisioning
- [SCIM Overview](/docs/product/scim/overview) — Compare Native and Bridge synchronization modes