User Attribute Profile
The User Attribute Profile (UAP) provides a consistent way to define, manage, and map user attributes across protocols such as SCIM, SAML, and OIDC. UAP with Self-Service SSO gives administrators greater control over user identity data by defining user attributes and applying the profile across authentication protocols.
How it works
Profile Definition
An administrator creates a User Attribute Profile to define attributes, including:
How to display attributes
How to make attributes required
How attributes map to Auth0 and external identity systems
Flexible Scope
Profiles are linked to Self-Service SSO flows but are designed for provisioning, onboarding, and entitlement management.
Unified Mapping Layer
Each attribute supports mappings across authentication protocols with the option to override values for specific providers or connection strategies, such as Okta and Entra ID.
Attribute mapping and override
UAP supports multi-protocol attribute definitions and strategy overrides for provider-specific needs.
Attribute mapping
Protocol | Description |
---|---|
Auth0 Mapping | Canonical attribute stored in Auth0 (email , name , app_metadata.department ). |
OIDC Mapping | Standard OIDC claims (sub , preferred_username , zoneinfo ). To learn more about OIDC standard claims, read Standard Claims. |
SAML Mapping | Supports one or more assertion URIs (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress). |
SCIM Mapping | Provisioning attributes (name.familyName , addresses[type eq "work"].country ). |
Strategy overrides
Protocol | Description |
---|---|
SAML | Map userName instead of externalId . |
WAAD (Entra ID) | Use oid as the OIDC identifier. |
Okta | Map attributes such as middleName or federated_groups using Okta-specific claims. |
User ID
The user_id
property defines how to map OIDC claims, SAML attributes, or SCIM attributes to the Auth0 user ID. Every Auth0 user must have an ID, so this mapping is required.
For OIDC, the choices are rigid (typically
sub
, oroid
for Azure AD, oremail
for Google).For SAML and SCIM, the mapping is more flexible and can point to multiple possible attributes.
User attributes
The user_attributes
property contains mapping information allows the system to interpret incoming claims from the IdP and store them as Auth0 user profile attributes.
Each attribute must be provided as a key/value pair:
The key corresponds to the attribute name.
The value is an object with:
label
description
profile_required
auth0_mapping
saml_mapping
scim_mapping
oidc_mapping
an object with propertiesmapping
represents the incoming claim from the IdP (literal value, dynamic context object, or both using${variable}
syntax supporting the context object).display_name
the label shown to end users in self-service flows.
Strategy Overrides
The strategy_overrides
property allows you to specify exceptions for individual identity providers (IdPs), since not all IdPs expose the same identifiers or claims.
Each override defines protocol-specific mappings that replace the defaults defined in user_id
or user_attributes
.
Examples
User identifier
"user_id": {
"oidc_mapping": "sub",
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"scim_mapping": "externalId",
"strategy_overrides": {
"waad": {
"oidc_mapping": "oid"
},
"samlp": {
"scim_mapping": "userName"
},
"google-apps": {
"oidc_mapping": "email"
}
}
},
Was this helpful?
Default identifier:
externalId
via SCIM.SAML: Multiple identifier URIs supported.
OIDC: Uses
sub
.Overrides: SAML and WAAD customize mappings.
Email attribute
"email": {
"description": "Email",
"label": "Email",
"profile_required": true,
"auth0_mapping": "email",
"scim_mapping": "emails[primary eq true].value",
"oidc_mapping": {
"mapping": "${context.tokenset.email}",
"display_name": "email"
},
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
],
"strategy_overrides": {
"waad": {
"scim_mapping": "emails[type eq \"work\"].value"
}
}
}
Was this helpful?
Suggested for most profiles.
Unified across Auth0, OIDC, SAML and SCIM.
WAAD override ensures correct mapping to work emails.
Create a User Attribute Profile
Navigate to Authentication > Enterprise > Self-Service SSO.
Select Create Profile.
Provide a Name and optional Description for the new profile.
Add a User Attribute Profile entry by either selecting an existing profile or choosing +Create New.
For a new profile, provide a User Profile Attribute Name.
Review mappings to ensure the profile attribute are mapping to your preferred Auth0 attributes.
Choose Create.
Your new UAP is available to configure for SSO.
To call the Management API, you must have an access token. To learn how to obtain one, read Management API Access Token.
Make a
POST
call to the UAP/api/v2/user-attribute-profiles
endpoint:
curl --location 'https: //auth0.com/api/v2/user-attribute-profiles' \
--header 'Authorization: Bearer ...' \
--data '{
"name": "My User Attribute Profile",
"user_id": {
"scim_mapping": "externalId",
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"oidc_mapping": "sub",
"strategy_overrides": {
"samlp": {
"scim_mapping": "userName"
},
"waad": {
"oidc_mapping": "oid"
},
"google-apps": {
"oidc_mapping": "email"
}
}
},
"user_attributes": {
"preferred_username": {
"description": "Preferred username",
"label": "Preferred username",
"profile_required": false,
"auth0_mapping": "preferred_username",
"oidc_mapping": {
"mapping": "${context.tokenset.preferred_username}",
"display_name": "preferred_username"
},
"strategy_overrides": {
"oidc": {
"scim_mapping": "userName"
},
"okta": {
"scim_mapping": "userName"
}
}
},
"username": {
"description": "Username",
"label": "Username",
"profile_required": false,
"auth0_mapping": "username",
"oidc_mapping": {
"mapping": "${context.tokenset.preferred_username}",
"display_name": "preferred_username"
},
"strategy_overrides": {
"samlp": {
"scim_mapping": "userName"
}
}
},
"upn": {
"description": "User Principal Name",
"label": "UPN",
"profile_required": false,
"auth0_mapping": "upn",
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
],
"strategy_overrides": {
"waad": {
"scim_mapping": "userName"
}
}
},
"email": {
"description": "Email",
"label": "Email",
"profile_required": true,
"auth0_mapping": "email",
"scim_mapping": "emails[primary eq true].value",
"oidc_mapping": {
"mapping": "${context.tokenset.email}",
"display_name": "email"
},
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
],
"strategy_overrides": {
"waad": {
"scim_mapping": "emails[type eq \"work\"].value"
}
}
},
"email_verified": {
"description": "Is Email verified?",
"label": "Email verified?",
"profile_required": false,
"auth0_mapping": "email_verified",
"oidc_mapping": {
"mapping": "${context.tokenset.email_verified}",
"display_name": "email_verified"
}
},
"external_id": {
"description": "External identifier",
"label": "External ID",
"profile_required": false,
"auth0_mapping": "app_metadata.external_id",
"scim_mapping": "externalId"
},
"blocked": {
"description": "User blocked status",
"label": "Blocked",
"profile_required": false,
"auth0_mapping": "blocked",
"scim_mapping": "active"
},
"name": {
"description": "Full name",
"label": "Name",
"profile_required": false,
"auth0_mapping": "name",
"scim_mapping": "displayName",
"oidc_mapping": {
"mapping": "${context.tokenset.name}",
"display_name": "name"
},
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
]
},
"given_name": {
"description": "First name",
"label": "Given Name",
"profile_required": false,
"auth0_mapping": "given_name",
"scim_mapping": "name.givenName",
"oidc_mapping": {
"mapping": "${context.tokenset.given_name}",
"display_name": "given_name"
},
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
]
},
"family_name": {
"description": "Last name",
"label": "Family Name",
"profile_required": false,
"auth0_mapping": "family_name",
"scim_mapping": "name.familyName",
"oidc_mapping": {
"mapping": "${context.tokenset.family_name}",
"display_name": "family_name"
},
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
]
},
"middle_name_oidc": {
"description": "Middle name",
"label": "Middle Name",
"profile_required": false,
"auth0_mapping": "middle_name",
"oidc_mapping": {
"mapping": "${context.tokenset.middle_name}",
"display_name": "middle_name"
}
},
"middle_name_scim": {
"description": "Middle name",
"label": "Middle Name",
"profile_required": false,
"auth0_mapping": "app_metadata.middle_name",
"strategy_overrides": {
"okta": {
"scim_mapping": "name.middleName"
}
}
},
"honorific_prefix": {
"description": "Honorific prefix",
"label": "Honorific Prefix",
"profile_required": false,
"auth0_mapping": "app_metadata.honorific_prefix",
"strategy_overrides": {
"okta": {
"scim_mapping": "name.honorificPrefix"
}
}
},
"honorific_suffix": {
"description": "Honorific suffix",
"label": "Honorific Suffix",
"profile_required": false,
"auth0_mapping": "app_metadata.honorific_suffix",
"strategy_overrides": {
"okta": {
"scim_mapping": "name.honorificSuffix"
}
}
},
"nickname": {
"description": "User nickname",
"label": "Nickname",
"profile_required": false,
"auth0_mapping": "nickname",
"scim_mapping": "nickName",
"oidc_mapping": {
"mapping": "${context.tokenset.nickname}",
"display_name": "nickname"
}
},
"picture": {
"description": "Profile picture URL",
"label": "Picture",
"profile_required": false,
"auth0_mapping": "picture",
"scim_mapping": "photos[type eq \"photo\"].value",
"oidc_mapping": {
"mapping": "${context.tokenset.picture}",
"display_name": "picture"
}
},
"primary_phone_number": {
"description": "Primary phone number",
"label": "Primary Phone Number",
"profile_required": false,
"auth0_mapping": "app_metadata.primary_phone_number",
"strategy_overrides": {
"okta": {
"scim_mapping": "phoneNumbers[primary eq true].value"
}
}
},
"work_phone_number": {
"description": "Work phone number",
"label": "Work Phone Number",
"profile_required": false,
"auth0_mapping": "app_metadata.work_phone_number",
"strategy_overrides": {
"oidc": {
"scim_mapping": "phoneNumbers[type eq \"work\"].value"
},
"samlp": {
"scim_mapping": "phoneNumbers[type eq \"work\"].value"
},
"waad": {
"scim_mapping": "phoneNumbers[type eq \"work\"].value"
}
}
},
"home_phone_number": {
"description": "Home phone number",
"label": "Home Phone Number",
"profile_required": false,
"auth0_mapping": "app_metadata.home_phone_number",
"strategy_overrides": {
"oidc": {
"scim_mapping": "phoneNumbers[type eq \"home\"].value"
},
"samlp": {
"scim_mapping": "phoneNumbers[type eq \"home\"].value"
}
}
},
"phone_number": {
"description": "Mobile phone number",
"label": "Mobile Phone Number",
"profile_required": false,
"auth0_mapping": "phone_number",
"oidc_mapping": {
"mapping": "${context.tokenset.phone_number}",
"display_name": "phone_number"
},
"saml_mapping": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/homephone",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/otherphone"
]
},
"mobile_phone_number_scim": {
"description": "Mobile phone number",
"label": "Mobile Phone Number",
"profile_required": false,
"auth0_mapping": "app_metadata.mobile_phone_number",
"scim_mapping": "phoneNumbers[type eq \"mobile\"].value"
},
"fax_number": {
"description": "Fax number",
"label": "Fax Number",
"profile_required": false,
"auth0_mapping": "app_metadata.fax_number",
"strategy_overrides": {
"waad": {
"scim_mapping": "phoneNumbers[type eq \"fax\"].value"
}
}
},
"street_address": {
"description": "Street address",
"label": "Street Address",
"profile_required": false,
"auth0_mapping": "app_metadata.street_address",
"scim_mapping": "addresses[type eq \"work\"].streetAddress"
},
"city": {
"description": "City",
"label": "City",
"profile_required": false,
"auth0_mapping": "app_metadata.city",
"scim_mapping": "addresses[type eq \"work\"].locality"
},
"state": {
"description": "State or province",
"label": "State",
"profile_required": false,
"auth0_mapping": "app_metadata.state",
"scim_mapping": "addresses[type eq \"work\"].region"
},
"postal_code": {
"description": "Postal code",
"label": "Postal Code",
"profile_required": false,
"auth0_mapping": "app_metadata.postal_code",
"scim_mapping": "addresses[type eq \"work\"].postalCode"
},
"postal_address": {
"description": "Postal address",
"label": "Postal Address",
"profile_required": false,
"auth0_mapping": "app_metadata.postal_address",
"scim_mapping": "addresses[type eq \"work\"].formatted"
},
"country": {
"description": "Country",
"label": "Country",
"profile_required": false,
"auth0_mapping": "app_metadata.country",
"scim_mapping": "addresses[type eq \"work\"].country"
},
"profile_url": {
"description": "Profile URL",
"label": "Profile URL",
"profile_required": false,
"auth0_mapping": "app_metadata.profile_url",
"scim_mapping": "profileUrl"
},
"user_type": {
"description": "User type",
"label": "User Type",
"profile_required": false,
"auth0_mapping": "app_metadata.user_type",
"scim_mapping": "userType"
},
"title": {
"description": "Title",
"label": "Title",
"profile_required": false,
"auth0_mapping": "app_metadata.title",
"scim_mapping": "title"
},
"language": {
"description": "Preferred language",
"label": "Language",
"profile_required": false,
"auth0_mapping": "app_metadata.language",
"scim_mapping": "preferredLanguage"
},
"locale": {
"description": "User locale",
"label": "Locale",
"profile_required": false,
"auth0_mapping": "app_metadata.locale",
"scim_mapping": "locale"
},
"timezone_oidc": {
"description": "User timezone",
"label": "Timezone",
"profile_required": false,
"auth0_mapping": "timezone",
"oidc_mapping": {
"mapping": "${context.tokenset.zoneinfo}",
"display_name": "zoneinfo"
}
},
"timezone_scim": {
"description": "User timezone",
"label": "Timezone",
"profile_required": false,
"auth0_mapping": "app_metadata.timezone",
"scim_mapping": "timezone"
},
"entitlements": {
"description": "User entitlements",
"label": "Entitlements",
"profile_required": false,
"auth0_mapping": "app_metadata.entitlements",
"strategy_overrides": {
"oidc": {
"scim_mapping": "entitlements"
},
"samlp": {
"scim_mapping": "entitlements"
}
}
},
"role_saml": {
"description": "User role",
"label": "Role",
"profile_required": false,
"auth0_mapping": "role",
"saml_mapping": [
"http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
]
},
"roles_scim": {
"description": "User roles",
"label": "Roles",
"profile_required": false,
"auth0_mapping": "app_metadata.roles",
"strategy_overrides": {
"oidc": {
"scim_mapping": "roles"
},
"samlp": {
"scim_mapping": "roles"
}
}
},
"employee_id": {
"description": "Employee identifier",
"label": "Employee ID",
"profile_required": false,
"auth0_mapping": "app_metadata.employee_id",
"scim_mapping": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.employeeNumber"
},
"cost_center": {
"description": "Cost center",
"label": "Cost Center",
"profile_required": false,
"auth0_mapping": "app_metadata.cost_center",
"scim_mapping": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.costCenter"
},
"organization": {
"description": "Organization",
"label": "Organization",
"profile_required": false,
"auth0_mapping": "app_metadata.organization",
"scim_mapping": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.organization"
},
"division": {
"description": "Division",
"label": "Division",
"profile_required": false,
"auth0_mapping": "app_metadata.division",
"scim_mapping": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.division"
},
"department": {
"description": "Department",
"label": "Department",
"profile_required": false,
"auth0_mapping": "app_metadata.department",
"scim_mapping": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department"
},
"manager": {
"description": "Manager",
"label": "Manager",
"profile_required": false,
"auth0_mapping": "app_metadata.manager",
"scim_mapping": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.manager"
},
"groups_saml": {
"description": "User'\''s groups",
"label": "User'\''s groups",
"profile_required": false,
"auth0_mapping": "groups_saml",
"saml_mapping": [
"http://schemas.xmlsoap.org/claims/Group"
]
},
"federated_groups": {
"description": "Federated groups",
"label": "Federated groups",
"profile_required": false,
"auth0_mapping": "federated_groups",
"strategy_overrides": {
"okta": {
"oidc_mapping": {
"mapping": "${context.userinfo.groups}",
"display_name": "groups"
}
}
}
},
"federated_locale": {
"description": "Federated locale",
"label": "Federated locale",
"profile_required": false,
"auth0_mapping": "federated_locale",
"strategy_overrides": {
"okta": {
"oidc_mapping": {
"mapping": "${context.userinfo.locale}",
"display_name": "locale"
}
}
}
},
"federated_zoneinfo": {
"description": "Federated zone info",
"label": "Federated zone info",
"profile_required": false,
"auth0_mapping": "federated_zoneinfo",
"strategy_overrides": {
"okta": {
"oidc_mapping": {
"mapping": "${context.userinfo.zoneinfo}"
}
}
}
}
}
}'
Was this helpful?
Sample response
{
"name": "myprofile",
"description": "A self-service profile with user_attribute_profile_id",
"allowed_strategies": ['oidc', 'saml'],
"user_attribute_profile_id": "uap_72jbvv7LfRKYp59gtRLtkn",
}
Was this helpful?
References
APIs
To manage User Attribute Profiles, the following Management API endpoints are available:
POST
/api/v2/user-attribute-profiles
GET
/api/v2/user-attribute-profiles
PATCH
/api/v2/user-attribute-profiles/{id}
GET
/api/v2/user-attribute-profiles/{id}
GET
/api/v2/user-attribute-profiles/templates
GET
/api/v2/user-attribute-profiles/templates/{id}