> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navigara.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SCIM Provisioning
> Keep your Navigara contributor directory in sync with Okta, Microsoft Entra ID, or any SCIM 2.0 identity provider.
Navigara is a SCIM 2.0 **service provider**: your identity provider (IdP) pushes its user directory to Navigara, and Navigara keeps the contributor directory in sync automatically. When someone joins, changes role, or leaves in your IdP, that change flows into Navigara without manual upkeep.
SCIM provisions the **contributor directory** — names, emails, role, seniority, and manager relationships used for grouping and metrics. It does **not** grant sign-in access. People still log in through your configured SSO (Google, GitHub, GitLab, Microsoft) or an invite. Provisioning a user over SCIM enriches their contributor profile; it does not create a login.
## What you get
* **Automatic directory sync** — users created, updated, and deactivated in your IdP are reflected in Navigara.
* **Attribute mapping** — map any IdP attribute (job title, department, manager, custom claims) onto Navigara contributor fields and tags.
* **Identity stitching** — SCIM users are matched to the `git` contributors discovered from commit history, so directory metadata lands on the right person.
## Identity providers
Navigara implements standard SCIM 2.0, so any compliant identity provider can connect. The steps below cover **Okta** and **Microsoft Entra ID**.
Navigara also normalizes the common deviations between providers — including **Authentik** and **Ping Identity** — so quirks such as Entra sending `active` as a string, Okta's non-standard deactivation, and bare-string `manager` values are handled automatically, with no configuration required.
**Configure user provisioning today.** Navigara does not yet map SCIM Groups onto Navigara teams. Configure **user provisioning** in your IdP; group push can stay off. Team membership is managed inside Navigara.
## Setup
In Navigara, go to **Settings → SCIM** and create a token under the **Tokens** section. Give it a recognizable name (e.g. `okta-production`).
The full token is shown **once**, at creation time — copy it immediately. It is prefixed with `scim_`. You can optionally set an expiry (30 days, 90 days, 1 year, or never).
Treat the token like a password. It is a bearer credential that lets your IdP write to your organization's directory. If it leaks, revoke it from the same screen and mint a new one.
The SCIM base URL is shown on the same screen. It is:
```
https:///api/scim/v2
```
For Navigara Cloud that is `https://app.navigara.com/api/scim/v2`. For on-prem, substitute your own host.
In your IdP, create a SCIM 2.0 provisioning app and point it at the endpoint above, using the token as a **Bearer** credential. Provider-specific steps below.
Out of the box Navigara maps email, name, external ID, and manager. To map job title to a role, or any other attribute to a custom tag, use **Settings → SCIM → Attribute mapping**. See [Attribute mapping](#attribute-mapping).
### Identity provider configuration
1. In the Okta admin console, open **Applications → Create App Integration → SCIM 2.0** (or enable provisioning on an existing app).
2. Under **Provisioning → Integration**:
* **SCIM connector base URL**: `https:///api/scim/v2`
* **Unique identifier field for users**: `userName` (email)
* **Supported provisioning actions**: enable **Push New Users**, **Push Profile Updates**, and **Push User Deactivation**.
* **Authentication Mode**: HTTP Header → `Authorization: Bearer scim_…`
3. Click **Test Connector Configuration**, then save.
4. Under **Provisioning → To App**, enable **Create Users**, **Update User Attributes**, and **Deactivate Users**.
5. Assign the users (or groups of users) you want provisioned to the app.
Okta's "Push Groups" tab is for syncing group membership. Since Navigara does not yet map SCIM groups to teams, you can leave Push Groups off and rely on user provisioning.
1. In the Entra admin center, go to **Enterprise applications → New application → Create your own application**, then open **Provisioning**.
2. Set **Provisioning Mode** to **Automatic**.
3. Under **Admin Credentials**:
* **Tenant URL**: `https:///api/scim/v2`
* **Secret Token**: your `scim_…` token
4. Click **Test Connection**, then save.
5. Under **Mappings**, keep **Provision Microsoft Entra ID Users** enabled. You can disable **Provision Microsoft Entra ID Groups**.
6. Assign users to the application and turn **Provisioning Status** to **On**.
Entra sends some attributes (such as `active`) in non-standard shapes and uses value-path filters when an attribute like a work email changes. Navigara handles both automatically.
## What gets synced
When your IdP pushes a user, Navigara reflects it onto a contributor:
| SCIM resource | Result in Navigara |
| ------------------------------ | --------------------------------------------------------------------------------- |
| User | A contributor profile, matched to the `git` contributor with the same email |
| User attributes | Contributor name, email, and tags (role, seniority, manager, …) per your mappings |
| Deactivation (`active: false`) | The user is marked inactive; their commit history is preserved |
| Group | **Not yet** mapped to Navigara teams |
### Identity stitching
Navigara's metrics are tied to `git` contributors discovered from commit history. A SCIM user is automatically linked to a contributor when their **email** matches. When the IdP email differs from the email used in commits, link them manually:
1. Go to **Settings → SCIM → Attribute mapping** and open the **Linked users** tab.
2. Find the SCIM user and pick the matching contributor.
Each SCIM user links to exactly one contributor and vice versa. The **Unmapped** tab lists SCIM users that have not yet been matched to a contributor.
## Attribute mapping
**Settings → SCIM → Attribute mapping** controls how IdP attributes become contributor fields and tags.
* **Field mapping** — map a source path in the SCIM payload (for example `name.formatted`, or `title` for job title) onto a target: `email`, `name`, `external_id`, or any `tags.`. Each mapping can lowercase the value and remap raw values to canonical ones (for example, fold "SW Eng I", "SW Eng II", and "SW Eng III" into a single `SWE`).
* **Preview** — run the current (even unsaved) mappings against the latest data your IdP sent, to see exactly what each contributor field would become, plus warnings for missing required fields or non-string sources.
If you save no mappings, Navigara applies sensible defaults: `userName` → email (lowercased), `name.formatted` → name, `externalId` → external ID, and the manager reference is recorded for directory relationships.
You can map to any `tags.` you like. Two keys are recognized by Navigara's filters and dashboards today, and the mapping UI suggests their canonical values:
| Tag | Sourced from | Suggested values |
| ---------------------- | ----------------- | ---------------------------------------- |
| `tags.role` | job title | `SWE`, `External SWE`, `Product Manager` |
| `tags.seniority_level` | level / job title | `Junior`, `Medior`, `Senior` |
Saving mappings re-syncs every live SCIM user against the new configuration. Tag keys you remove from the mappings are also removed from contributors on the next sync.
## Token management
SCIM tokens are managed per organization under **Settings → SCIM → Tokens**:
* **Create** — mint a named token, optionally with an expiry. The raw value is shown once.
* **List** — see each token's name, prefix, creation date, last-used time, and expiry. The full secret is never shown again.
* **Revoke** — disable a token immediately. Revocation is instant and irreversible; the IdP will start receiving `401` responses.
An organization can hold up to **25 active tokens** at a time. Use separate tokens per IdP or environment so you can rotate one without disrupting the others.
## Troubleshooting
The token is wrong, disabled, or expired. Confirm the IdP sends `Authorization: Bearer scim_…` (the header value must include the `Bearer ` prefix and the full token), and check the token still appears as enabled under **Settings → SCIM → Tokens**. If in doubt, mint a fresh token and update the IdP.
The SCIM user has not been matched to a `git` contributor. This happens when the IdP email differs from the email used in commits. Open **Settings → SCIM → Attribute mapping → Linked users** and link them manually, or add the commit email as an alias on the contributor. Use the **Preview** tab to confirm the email mapping is producing the value you expect.
The relevant attribute isn't mapped. Open **Attribute mapping → Field mapping** and add a mapping from the IdP source path to the target tag (e.g. `tags.role`). Use **Preview** against the latest payload to verify, then save — saving re-syncs existing users.
Expected. Navigara receives SCIM groups but does not yet project them onto teams — manage team membership inside Navigara. If you rely on a group-derived attribute (e.g. department), make sure your IdP includes it on the **user** payload rather than only on the group.
Navigara normalizes the common provider-specific deviations (Entra's string `active`, value-path PATCH on changed emails; Okta's deactivation via `remove` and bare-string `manager`) automatically. If a specific attribute still isn't landing, check it under **Attribute mapping → Preview** and contact [support@navigara.com](mailto:support@navigara.com).