Custom Attribute Mapping

Custom attribute mapping lets you sync additional user data from your Identity Provider (IdP) (such as department, employee ID, or cost center) into Clerk's publicMetadata. Attribute definitions are configured at the enterprise connection level and are shared between your SSO connection (SAML) and your Directory Sync (SCIM) connection, so the same attributes are available regardless of how a user authenticates or is provisioned.

How it works

Attribute configuration happens in two layers:

1. Shared attribute pool — You define the attributes you care about once, at the enterprise connection level. Each attribute maps to a key in the user's publicMetadata. These definitions are shared across SSO and SCIM for that connection.
2. Connection-specific mappings — For each connection type (SAML or SCIM), you map the shared attribute to the IdP's specific field name or schema attribute.

This keeps your schema consistent while allowing for the different naming conventions each IdP uses.

Common attributes

Standard attributes (for example, username, first name, last name, and email addresses) are pre-configured for every enterprise connection. Clerk controls the mapping logic for these, but you don't need to define them manually.

Custom attributes

Custom attributes let you sync any additional user data from your IdP into publicMetadata. When your IdP sends a value for a custom attribute, Clerk stores it at publicMetadata.<key> on the user object.

For example, if you define a custom attribute with the key department, it will be stored as publicMetadata.department when synced.

Define custom attributes

1. In the Clerk Dashboard, navigate to the SSO connections⁠ page.
2. Select the enterprise connection you want to configure.
3. In the Overview tab, go to the Identity provider attributes section.
4. Under Custom attributes, select Create custom attribute.
5. Enter a Display name for the attribute (e.g., Department).
6. Enter the publicMetadata Key where this value will be stored (e.g., department).
7. Select Create attribute.

Once defined, this attribute will appear in the mapping configuration for both your SSO connection and your SCIM connection (if Directory Sync is enabled).

Map attributes for SSO connections

For SSO connections, you map each shared attribute to the claim name your IdP returns during authentication.

SAML

In SAML, attributes are passed as assertions. For each custom attribute:

1. In the Clerk Dashboard, select the Attribute mapping tab on your SAML connection.
2. For each custom attribute, enter the SAML claim name your IdP sends (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department).
3. In your IdP, ensure the corresponding attribute is included in the SAML assertion and mapped to the same claim name.

For a full walkthrough of setting up a SAML connection, see the custom SAML provider guide.

Map attributes for SCIM (Directory Sync)

When Directory Sync is enabled, SCIM is the exclusive source of truth for attribute values. SCIM-managed attributes are read-only in Clerk and cannot be edited from the Dashboard or by the user in <UserProfile />. When SCIM is disabled, attributes become editable again.

Clerk's SCIM implementation exposes a /Schemas endpoint that advertises a custom schema extension (urn:clerk:scim:schemas:extension:custom:2.0:User). This tells your IdP that Clerk accepts arbitrary custom attributes, which are mapped directly to publicMetadata.

For each custom attribute, you map the shared attribute to the SCIM schema attribute name your IdP sends:

1. In the Clerk Dashboard, navigate to the Directory Sync tab on your enterprise connection.
2. Under Attribute mapping, use the dropdown (populated from the SCIM /Schemas endpoint) to select the SCIM attribute for each custom attribute.
3. Select Save.

For example, the shared department attribute might map to urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department in Okta.

For a full walkthrough of setting up Directory Sync, see the Directory Sync guide.

Accessing custom attributes

Custom attribute values are stored in publicMetadata and are accessible from the Backend API⁠ on the user object, the useUser() hook (via user.publicMetadata), and Clerk's server-side helpers.