> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agent-auth`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Map user attributes to IdP

Scalekit simplifies Single Sign-On (SSO) by managing user information between Identity Providers (IdPs) and B2B applications. The IdPs provide standard user properties, such as `email` and `firstname`, to your application, thus helping recognize the user.

Consider a scenario where you want to get the employee number of the user logging into the application. This guide demonstrates how to add your own custom attribute (such as `employee_number`) and map its value from the Identity Provider.

Broadly, we'll go through two steps:

1. Create a new attribute in Scalekit
2. Set up the value that the Identity Provider should relay to this attribute

## Create a new attribute

Let's begin by signing into the Scalekit dashboard:

1. Navigate to **Dashboard > SSO > User Attributes**
2. Click **Add Attribute**
3. Add "Employee Number" as Display name

<figure>
  ![add attribute](@/assets/docs/guides/product/setup-sso/customize-user-attributes/1-add-attribute-scalekit.png)
</figure>

You'll now notice "Employee Number" in the list of user attributes. Scalekit is now ready to receive this attribute from your customers' Identity Providers (IdPs).

<figure>
  ![see attribute](@/assets/docs/guides/product/setup-sso/customize-user-attributes/2.png)
</figure>

## Set up IdP attributes Okta example

Now, we'll set up an Identity Provider to send these details. For the purposes of this guide, we'll use Okta as IdP to send the `employee_number` to Scalekit. However, similar functionality can be achieved using any other IdP.

Note that in this specific Okta instance, the "Employee Number" is a default attribute that hasn't been utilized yet. Before you proceed forward, it's important to modify the profile's `employee_number` attribute with any desired number for this example (for example, `1729`). For a detailed guide on how to achieve this, consult <a href="https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-edit-user-attributes.htm#:~:text=Click%20the%20Profile%20tab" target="_blank" rel="noopener noreferrer">Okta's dedicated help article on updating profile attributes</a>.

Alternatively, you can <a href="https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-custom-user-attributes.htm#:~:text=In%20the%20Admin%20Console%20%2C%20go%20to%20Directory%20Profile%20Editor" target="_blank" rel="noopener noreferrer">add a new custom attribute in the Okta Profile Editor</a>.

<figure>
  ![map attribute](@/assets/docs/guides/product/setup-sso/customize-user-attributes/3-map-attribute-okta.png)
</figure>

## Test SSO for new attributes

In the Scalekit dashboard, navigate to **Dashboard > Organizations**.

1. Select the organization that you'd like to add custom attribute to
2. Navigate to the SSO Connection
3. Click **Test Connection** - you'll find this if the IdP has already been established
<figure>
  ![map attr scalekit](@/assets/docs/guides/product/setup-sso/customize-user-attributes/4-map-attribute-scalekit.png)
</figure>

Upon testing the connection, if you notice the updated user profile (`employee_number` as `1729` in this example), this signifies a successful test.

Subsequently, these details will be integrated into your B2B application through Scalekit. This ensures seamless recognition and handling of customer user attributes during the SSO authentication process.

## Reserved attribute names

Some attribute names are **reserved by Scalekit** and must not be used for custom attributes. Using a reserved name causes silent failures — the custom attribute value is silently dropped or overwritten during SSO.

| Name | Purpose |
|------|---------|
| `roles` | Used by Scalekit for FSA role-based access control (RBAC) |
| `permissions` | Used by Scalekit for FSA permissions |
| `email` | Standard claim — always populated from IdP |
| `email_verified` | Standard claim |
| `name`, `given_name`, `family_name` | Standard profile claims |
| `sub`, `oid`, `sid` | Internal Scalekit identifiers |

If your IdP sends an attribute named `roles`, it **will not** appear as a custom attribute in the JWT. Instead, rename it to something unique (e.g., `user_role` or `idp_roles`) in both Scalekit and your IdP attribute mapping.

## Access custom attributes from the ID token

After configuring a custom attribute in Scalekit, its value appears in the ID token as a JWT claim. Use the Scalekit SDK to validate the token and read the claim:

```typescript title="Read custom attributes from ID token"
import type { IdTokenClaim } from '@scalekit-sdk/node';

// Validate the ID token and cast to include your custom attributes
const claims = await scalekit.validateToken<IdTokenClaim & Record<string, unknown>>(idToken);
const employeeNumber = claims['employee_number'];
const userRole = claims['user_role']; // use 'user_role', not 'roles'
```
```python title="Read custom attributes from ID token"
# Validate the ID token — returns a dict of all claims
claims = scalekit_client.validate_token(id_token)
employee_number = claims.get('employee_number')
user_role = claims.get('user_role')  # use 'user_role', not 'roles'
```
```go title="Read custom attributes from ID token"
// Validate the ID token — returns a map of all claims
claims, err := scalekitClient.ValidateToken(ctx, idToken)
if err != nil {
    log.Fatal(err)
}
employeeNumber := claims["employee_number"]
userRole := claims["user_role"] // use "user_role", not "roles"
```
```java title="Read custom attributes from ID token"
import java.util.Map;

// Validate the ID token — returns a map of all claims
Map<String, Object> claims = scalekitClient.authentication().validateToken(idToken);
Object employeeNumber = claims.get("employee_number");
Object userRole = claims.get("user_role"); // use "user_role", not "roles"
```

---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |