Profile Attributes

WorkOS automatically normalizes a standard set of attributes from identity providers (IdPs) into the Single Sign-On (SSO) Profile object. More unique cases can be mapped by your customer admins. In this guide, we’ll explain how to map data from identity providers to the SSO Profiles.

Standard attributes

The most common user information, normalized across providers.

Predefined attributes

Detailed user attributes for specific use cases, normalized across providers. You can opt-in to each attribute you’d like organization admins to map during SSO connection configuration.

Custom attributes

For unique cases, you can create custom attributes your customers can map when setting up an SSO connection.

Every SSO Profile comes with the following standard attributes. These are the core set of attributes that are common across all identity providers. These are structured fields with a guaranteed schema in the top-level SSO Profile payload.

For more detailed user information, you can opt-in to additional predefined attributes and define your own custom attributes. These attributes will appear in the custom_attributes field on SSO Profile objects and can be configured in the WorkOS Dashboard.

When enabled, organization admins will we asked to map these attributes during SSO configuration in Admin Portal. These fields are always optional if enabled. These fields are named and schematized by WorkOS – they cannot be renamed.

Enable or disable a predefined attribute

Predefined attributes can be enabled or disabled in the WorkOS Dashboard on the Identity Provider Attributes page.

Custom attributes can be utilized to enrich SSO Profiles with additional data from the identity provider. You can create attributes that appear as fields in the Admin Portal. Your customers can map these fields to the correct values in their system when setting up SSO with their identity provider.

Create a custom attribute

Custom attributes can be created in the WorkOS Dashboard on the Identity Provider Attributes page.

Delete a custom attribute

When a custom attribute is deleted, SSO Profiles will retain these existing attribute values until the next sign-in.

Editing attribute mappings

If attribute data for a particular SSO connection has changed and is no longer mapped properly, you or the organization admin can edit the attribute mappings via the WorkOS Dashboard connection page or Admin Portal, respectively.

You can control the visibility of custom attribute mapping for Directory Sync and Single Sign-On flows in the Admin Portal at the environment and organization level.

The environment-level setting is controlled on the Identity Provider Attributes page in the WorkOS Dashboard.

Organization-level settings are controlled on an individual organization’s Attributes tab in the WorkOS Dashboard. Organizations mirror the environment-level settings by default.

Which identity providers support mapping additional predefined and custom attributes?

Additional predefined and custom attributes are supported for all SAML SSO connections.

Can our customers add their own custom attributes outside of what is defined in the WorkOS Dashboard?

We do not currently support this functionality. Custom attributes must be defined in the WorkOS Dashboard first. Please reach out to support if you have a specific use case that you would like to discuss.

What happens if an attribute cannot be mapped from the IdP?

Attributes that cannot be mapped for a particular SSO Profile will result in a null value for the attribute.