SCIM provisioning

Provision a Nametag directory from your identity provider over SCIM 2.0

Beta: SCIM provisioning is in beta and is enabled per organization. While we do not expect these steps to change, they might. Report any issues to help@nametag.co.

Nametag can populate a directory in one of two ways:

Pull provisioning (the default): Nametag periodically reads accounts from your provider.
SCIM provisioning: your identity provider pushes users and groups to Nametag as they change.

The Nametag-side setup is the same for every provider: enable SCIM on your directory, get your connection details, and understand the attributes Nametag consumes. After that, follow the guide for your identity provider to finish the configuration.

Before you begin

SCIM provisioning must be enabled for your Nametag organization. If you don’t see the SCIM option described in Step 1, contact your Nametag representative to have it turned on.
You need administrator access to the Nametag console.
You’ll also need administrator access to your identity provider to complete its provider guide.

Step 1 — enable SCIM on your Nametag directory

You can choose SCIM either while creating a new directory integration or on an existing one. Follow whichever path applies to you.

Create a directory integration with SCIM

In the Nametag console, go to Integrations and select New integration.
Choose your identity provider (for example, Okta) from the list of integration types.
Under Provisioning method, select SCIM provisioning.
Enter your provider’s connection details and finish creating the directory.

Enable SCIM on an existing directory

In the Nametag console, go to Integrations and open your directory.
Turn on the SCIM toggle.

If a pull sync is running, wait for it to finish before enabling SCIM.

Step 2 — Gather your Nametag connection details

You’ll need three values from Nametag to configure your identity provider:

SCIM endpoint URL:
```
https://nametag.co/scim/v2
```
Username — your Directory ID. On the directory’s page, find the Directory Information section and copy the Directory ID.
Password — a Nametag API key. Go to the API Keys page, create a key with the Admin role, and copy it. The key is shown only once, so copy it before leaving the page.

Keep these three values available — your provider guide uses them to authenticate to Nametag.

Supported authentication formats

Nametag accepts the Directory ID and Admin API key in either of these Authorization header formats:

HTTP Basic authentication — use the Directory ID as the username and the Admin API key as the password. Most identity providers generate the header after you enter those values:
```
Authorization: Basic <base64-encoded-directory-id-and-api-key>
```
Bearer authentication — if your identity provider requires a bearer token, combine the Directory ID and Admin API key with a colon:
```
Authorization: Bearer <directory-id>:<admin-api-key>
```
The Directory ID is required. A bearer header containing only the API key is not accepted.

Attributes Nametag consumes

User attributes

Regardless of provider, Nametag reads the following SCIM user attributes. A standard setup requires no custom mapping.

Exact SCIM attribute	Used by Nametag for
`userName`	The account’s sign-in name and a matching identifier
`externalId`	Stable provider identifier used to reconcile users and avoid duplicates. Providers send the `GUID` of the object by default; deviating from this behavior will cause issues with Nametag functionality.
`emails[*].value`	Additional identifiers used to match the account
`displayName`	Account display name
`name.givenName`	First name used with `name.familyName` when `displayName` is not sent
`name.familyName`	Last name used with `name.givenName` when `displayName` is not sent
`active`	Whether the account is active; defaults to `true` when omitted

Map an optional birthdate

If you want Nametag to match a user’s birthdate during identity verification, send it in the Nametag custom SCIM extension attribute at this path:

urn:ietf:params:scim:schemas:extension:nametag:2.0:User:birthDate

The value can be a plain date in YYYY-MM-DD format, or one of the hashed formats supported by Nametag. See Birth date hashes for the accepted formats. Your provider guide explains how to map one of your provider’s user attributes to this path.

Group attributes

Nametag reads the following SCIM group attributes:

Exact SCIM attribute	Used by Nametag for
`displayName`	Group name
`externalId`	Stable provider identifier used to reconcile groups and avoid duplicates
`members[*].value`	Nametag SCIM user resource IDs belonging to the group

Provider guides

Configure your identity provider using one of the guides below. Each one picks up where this page leaves off.

Okta — provision a Nametag directory from Okta.

More providers are coming. If you need a provider that isn’t listed yet, contact help@nametag.co.