Add Attributes to IdP Tokens and Profiles

What This Is For

Skillhabit Attribute mappings only work when your identity provider actually sends the value. This page shows how common IdPs put directory fields into:

After the IdP releases the field, map it in Skillhabit under Configure → Connections → Attribute mappings. Full Skillhabit-side steps: User Provisioning → Map Directory Attributes.

Who This Is For

Workspace administrators working with your identity / Entra / Okta / Auth0 admin. You need permission to change app claim configuration in the IdP—not only Skillhabit Configure.

Before You Start

1. Create the Skillhabit Attributes you want to fill (Custom Attribute Fields).
2. Decide the source type for each mapping (OIDC claim vs Entra Graph property vs SCIM path)—they are not interchangeable.
3. Prefer short, stable claim or property names (for example department, officeLocation). Avoid renaming claims later; remapping in Skillhabit is easier than breaking every token consumer.
4. After IdP changes, sign out and sign in again (OIDC) or run a sync / SCIM update so Skillhabit receives a fresh payload.

Microsoft Entra ID (Azure AD)

Entra is used in two different Skillhabit paths. Configure the path you actually use.

A) OpenID Connect / Microsoft login — optional claims on the token

Use this when Skillhabit maps an OpenID Connect claim at sign-in.

1. In the Azure portal, open Microsoft Entra ID → App registrations → the app Skillhabit (or your broker) uses for OpenID Connect / Microsoft sign-in.
2. Open Token configuration.
3. Choose Add optional claim.
4. Select token type ID (Skillhabit reads identity claims from the ID token / login profile path).
5. Add the directory claims you need—for example department, officeLocation, job title, or other optional claims Entra lists for your account type.
6. Save. If Entra prompts for Microsoft Graph permissions for that claim, grant admin consent.
7. In Skillhabit, create a mapping with Source = OpenID Connect claim and External IdP Property Name = the claim name Entra emits (often the same short name, for example department).

Custom / extension attributes in the ID token

1. Prefer Enterprise applications → your app → Single sign-on → Attributes & Claims (SAML-style UI is also used for OIDC apps in many tenants) or a claims mapping policy on the service principal—follow your tenant’s standard for “emit extension attribute X as claim Y”.
2. Emit a simple claim name Skillhabit can type into External IdP Property Name (for example costCenter). Nested JSON paths are harder to support—prefer a flat string or string array.
3. Test with a fresh login. Confirm the claim appears in the ID token (Azure Token configuration, or a JWT decode of a test login) before debugging Skillhabit mappings.

B) Microsoft Entra directory sync — Graph properties (not token claims)

Use this when Skillhabit maps a Microsoft Entra property during Configure → Connections → Microsoft Entra ID sync.

Graph already exposes many profile fields without optional-claim setup—for example:

In Skillhabit, set Source = Microsoft Entra property and External IdP Property Name to that Graph property path (exactly as above for extension attributes).

You do not need to put these on an ID token for Entra sync—sync reads Graph. You do still need optional claims (section A) if the same field must arrive on OIDC login for users who are not updated by sync.

Okta

Use this for OpenID Connect claim mappings when people sign in through Okta OIDC.

1. In Okta Admin, open Security → API → Authorization Servers (or your custom authorization server used by the Skillhabit OIDC app).
2. Open the authorization server → Claims.
3. Add Claim:
   • Name — the claim Skillhabit will map (for example department). Use this exact string in Skillhabit External IdP Property Name.
   • Include in token type — ID Token (always / or matching your scopes).
   • Value type — Expression or identity attribute (for example user.department, user.costCenter, or a custom profile attribute).
4. Save and assign the claim so it is included for the Skillhabit client / scopes you use.
5. Confirm the Okta OIDC app requests any scopes your claim requires.
6. In Skillhabit: Source = OpenID Connect claim, External IdP Property Name = the claim Name from step 3.

App-level ID token claims (org authorization server)

Some orgs configure claims under the OIDC application → Sign On → OpenID Connect ID Token section instead of a custom authorization server. Same idea: define a claim name and map it from an Okta user profile attribute, then use that name in Skillhabit.

Multi-value attributes

If the Okta attribute is multi-valued, emit a JSON array of strings in the ID token when Skillhabit should fill a Multi Select attribute (Skillhabit replaces the whole set on each apply).

Auth0

Auth0 does not put arbitrary profile root fields on third-party ID tokens by default. Add custom claims with a namespaced identifier, then map that full claim name in Skillhabit.

1. Create (or reuse) an Auth0 Action on the Login / Post Login flow.
2. In the action, set claims on the ID token, for example:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://skillhabit.com';
  if (event.user.department) {
    api.idToken.setCustomClaim(`${namespace}/department`, event.user.department);
  }
  if (Array.isArray(event.user.groups)) {
    api.idToken.setCustomClaim(`${namespace}/costCenters`, event.user.groups);
  }
};

3. Deploy the Action and add it to the Login flow.
4. Ensure the user profile (or an enrichment Action) actually populates department / custom metadata before the claim is set.
5. In Skillhabit: Source = OpenID Connect claim, External IdP Property Name = the full claim name, including namespace (for example https://skillhabit.com/department).

Auth0 rejects non-namespaced custom claims on OIDC ID tokens—do not omit the namespace.

Generic OpenID Connect IdPs

For Ping, OneLogin, Keycloak, FusionAuth, AWS Cognito, and similar:

1. Find the IdP setting that adds ID token claims or attribute statements for your Skillhabit OIDC client (names vary: Claims, Mappers, Attribute mapping, Token customization).
2. Map a directory attribute → claim name.
3. Include the claim in the ID token (not only the access token). Skillhabit attribute mapping for OIDC is driven by login identity claims.
4. Prefer string or string-array values.
5. In Skillhabit, type the claim name exactly as it appears in the ID token.

Minimum identity claims Skillhabit still needs for login itself (email, or preferred_username, or upn) are separate from attribute mappings—see SSO and Email Addresses.

SCIM Attribute Paths

When Skillhabit maps a SCIM attribute, the IdP must send that attribute on SCIM User create/update—not on an OIDC token.

Common patterns:

Steps (IdP side):

1. Enable the Skillhabit SCIM connector and confirm core User provisioning works (User Provisioning → SCIM).
2. In the IdP SCIM app, open attribute mappings / provisioning attributes.
3. Map the directory field onto the SCIM attribute path Skillhabit expects.
4. Push or reprovision a test user; confirm the attribute appears on the SCIM payload.
5. In Skillhabit: Source = SCIM attribute, External IdP Property Name = that path (exact string your tenant uses).

Exact SCIM base URLs and which extension schemas Skillhabit accepts are workspace-specific—your Skillhabit contact confirms them when SCIM is enabled.

Verify End-to-End

1. IdP — Decode a fresh ID token (OIDC) or inspect a SCIM/Graph payload and confirm the claim / property is present with the expected value.
2. Skillhabit mapping — Configure → Connections → Attribute mappings points at that exact name/path and the right Source type.
3. Apply — Sign in again (OIDC) or wait for / force Entra sync / trigger SCIM update.
4. Profile — Open the user in Users & Groups; the Skillhabit attribute should update and stay locked when sourced from the IdP.

If the IdP never sends the field, Skillhabit cannot invent it—fix the IdP emission step first.

Related

• User Provisioning — Attribute mappings in Skillhabit
• SSO and Authentication
• SSO and Email Addresses
• Custom Attribute Fields
• Sync Users With SCIM