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

# Microsoft

> Set up SCIM provisioning from Microsoft Entra ID.

Set up SCIM 2.0 provisioning from Microsoft Entra ID, formerly Azure Active Directory, so it
pushes users to OutKept as they change.

<Info>
  You need **Global Administrator** or **Application Administrator** rights in your Azure
  tenant.
</Info>

## Generate a SCIM token

This bearer token authenticates every provisioning request from Entra ID to our platform.

<Steps>
  <Step title="Open the import wizard">
    Log into the OutKept platform as an administrator. Go to **Manage your data** and click
    **Import data**, or click **Start onboarding**.
  </Step>

  <Step title="Choose SCIM">
    Select **SCIM** as your sync type.
  </Step>

  <Step title="Generate">
    Click **Generate SCIM Token**.
  </Step>

  <Step title="Copy it">
    The token starts with `outkept_scim_`. Copy it now.
  </Step>
</Steps>

<Warning>
  Store this token securely. It is only shown once. To regenerate, return to the same screen.
  The old token is invalidated immediately and stops working.
</Warning>

## Create the enterprise application

<Steps>
  <Step title="Open Entra ID">
    Go to [portal.azure.com](https://portal.azure.com) and sign in with your admin account.
    Navigate to **Azure Active Directory** then **Enterprise applications**.
  </Step>

  <Step title="Create your own application">
    Click **New application**, then **Create your own application**.
  </Step>

  <Step title="Name it and set the type">
    Enter a name, for example `OutKept SCIM`. Select **Integrate any other application you don't
    find in the gallery (Non-gallery)**. Click **Create**.
  </Step>
</Steps>

## Configure provisioning credentials

<Steps>
  <Step title="Open provisioning">
    Inside the new application, click **Provisioning** in the left sidebar, then **New
    Configuration** at the top or **Connect your application** from the list.
  </Step>

  <Step title="Set the authentication method">
    Choose **Bearer authentication**, then fill in:

    | Field | Value |
    | - | - |
    | Tenant URL | `https://api.outkept.com/scim/v2` |
    | Secret Token | Your `outkept_scim_…` token |
  </Step>

  <Step title="Test the connection">
    Click **Test connection**. Entra ID calls `GET /scim/v2/Users` with your token. On success,
    a connected status appears both in the Azure admin center and on the OutKept platform.
  </Step>

  <Step title="Save">
    Click **Save** to confirm.
  </Step>
</Steps>

<Note>
  If the test fails, confirm there is no trailing slash on the Tenant URL and that the full
  token was pasted without extra spaces.
</Note>

## Configure attribute mappings

Attribute mappings define which fields from Entra ID are sent to OutKept and how they map to
OutKept user fields. Correct mapping is what makes targeting and personalisation work.

### Select users to sync

By default Entra ID can sync your entire tenant. For most campaigns you want to limit it to a
specific group.

Create a security group in Entra ID containing only the employees in scope, for example
`OutKept Campaign Users`, then assign that group to the application.

<Steps>
  <Step title="Set the scope">
    Under **Settings**, set **Scope** to **Sync only assigned users and groups**.
  </Step>

  <Step title="Assign the group">
    Go to **Users and groups** then **Add user/group**, and assign your security group.
  </Step>
</Steps>

<Tip>
  Only members of the assigned security group are synced. To add or remove someone from the
  sync, add or remove them from that group in Entra ID. Nothing in the SCIM configuration needs
  to change.
</Tip>

### Map the attributes

On the Provisioning page, click **Manage** to expand the section, then **Attribute mapping**.

Only email, country and language are mandatory. Everything else improves targeting quality and
is strongly recommended.

| Entra ID attribute | SCIM attribute | Required |
| - | - | - |
| `userPrincipalName` | `userName` (email) | Mandatory |
| `mail` | `emails[type eq "work"].value` | Mandatory |
| `country` | `addresses[type eq "work"].country` | Mandatory |
| `preferredLanguage` | `preferredLanguage` | Mandatory |
| `givenName` | `name.givenName` | Recommended |
| `surname` | `name.familyName` | Recommended |
| `department` | `urn:…:enterprise:2.0:User:department` | Recommended |
| `jobTitle` | `title` | Recommended |
| `companyName` | `urn:…:enterprise:2.0:User:organization` | Optional |

<Tip>
  Mapping `department` and `jobTitle` significantly improves phishing targeting. The more
  context available, the more realistic the simulations.
</Tip>

## Start provisioning

### Enable provisioning

<Steps>
  <Step title="Turn it on">
    Go back to the **Provisioning** page of the application, set **Provisioning Status** to
    **On**, and click **Save**.
  </Step>

  <Step title="Start it">
    Go to **Overview** and click **Start provisioning**.
  </Step>
</Steps>

### Monitor the initial cycle

Entra ID runs an initial full sync. This can take 20 minutes to several hours depending on user
count.

On the Provisioning page, click **Provisioning logs** and look for Action = **Create** and
Status = **Success** for each user.

### Verify in OutKept

Log into the platform as an administrator, go to **Manage your data**, and confirm synced users
appear with correct tags for country and language.

<Tip>
  After the initial sync, Entra ID runs incremental cycles roughly every 40 minutes. New members
  of the security group are provisioned automatically.
</Tip>

## How the sync works

Once provisioning is active, Entra ID is the source of truth for user data. Our SCIM endpoint
receives and processes all provisioning requests automatically.

| Cycle | When |
| - | - |
| Initial | Once, when provisioning is first enabled. Syncs all in-scope users in full |
| Incremental | Roughly every 40 minutes. Processes only changes since the last cycle |

### User lifecycle

| Event in Entra ID | Action in OutKept |
| - | - |
| User added to the security group | New person created and added to the campaign |
| User attributes updated | Person record updated, tags re-mapped |
| User removed from the security group | Person deactivated, excluded from future sends |
| User account disabled in Entra ID | Person deactivated |

<Tip>
  Deactivated users are not deleted, and their interaction history is preserved. Use **Include
  deleted persons** in the [dashboard](/campaign-dashboard) to keep them in your
  statistics.
</Tip>

### Tag mapping after sync

When a user arrives via SCIM, their attributes go through our tag mapping system. Values we
have seen before, such as a known department, are applied automatically. New values must be
mapped once by hand under **Manage your data** then **Map data**. See
[Mapping column values](/mapping-column-values).

## Supported SCIM operations

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/scim/v2/Users` | List users, used by Entra ID to detect changes |
| `GET` | `/scim/v2/Users/{id}` | Retrieve a single user by SCIM ID |
| `POST` | `/scim/v2/Users` | Create a new user |
| `PUT` | `/scim/v2/Users/{id}` | Replace all attributes of a user |
| `PATCH` | `/scim/v2/Users/{id}` | Update specific attributes of a user |
| `PATCH` with `active=false` | `/scim/v2/Users/{id}` | Deactivate a user |

Base URL:

```
https://api.outkept.com/scim/v2
```

Every request from Entra ID includes the SCIM token in the `Authorization: Bearer` header.
Invalid or missing tokens are rejected with `HTTP 401`.

## Attribute reference

Email, country and language are mandatory. A user missing any of these cannot receive
simulations.

| SCIM attribute | OutKept field | Mandatory |
| - | - | - |
| `userName` | Email address | Yes |
| `emails[work].value` | Email (fallback) | No |
| `name.givenName` | First name | No |
| `name.familyName` | Last name | No |
| `addresses[work].country` | Country tag | Yes |
| `preferredLanguage` | Language tag | Yes |
| `title` | Function title, becomes a business function tag | No |
| `department` | Department, becomes a business function tag | No |
| `urn:…:organization` | Organisation name | No |
| `active` | Active or inactive status | No |

<Warning>
  The country tag determines the cultural context of simulations. Make sure it reflects where
  the employee works, not necessarily their nationality.
</Warning>

## Troubleshooting

| Issue | Solution |
| - | - |
| Test connection fails in Azure | Confirm the Tenant URL is exactly `https://api.outkept.com/scim/v2` with no trailing slash, check the full token was pasted starting with `outkept_scim_`, and confirm you clicked **Save** after testing |
| Users show Success in Azure logs but are missing in OutKept | Check the user has a valid work email as `userPrincipalName`, confirm `country` and `preferredLanguage` are mapped and have values, and look for a red exclamation mark under **Manage your data** |
| Provisioning cycles are not running | Confirm **Provisioning Status** is **On**, check the Provisioning logs for errors, and click **Restart provisioning** on the Overview page if it is stuck |
| Token expired or invalidated | Update the **Secret Token** field in Azure with the new token and re-test the connection. The old token is invalidated immediately |

For anything not listed here, contact [support@outkept.com](mailto:support@outkept.com) with
your organisation name and a screenshot of the Azure provisioning logs.

## Next

Once users are in, continue to [Email delivery](/email-delivery).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.