Attribute Mapping — SSO Providers

How Attribute Mapping Works

When Passport builds a SAML assertion or OIDC token for a consumer, it runs the user's profile through an attribute mapping pipeline. The pipeline reads Passport user fields and writes them into the assertion using the names and formats that the SP expects.

Mapping configuration lives in the consumer registration and is evaluated at runtime for each SSO event. There is no caching of individual attribute values — the latest user profile is always used.

Default SAML Attribute Mapping

When no custom mapping is configured, Passport uses the following defaults:

Passport Field	SAML Attribute Name	Format
`user.email`	`email`	String
`user.firstName`	`firstName`	String
`user.lastName`	`lastName`	String
`user.displayName`	`displayName`	String
`user.roles[]`	`roles`	Multi-value
`user.tenantId`	`tenantId`	String
`user.userId`	NameID (subject)	email or persistent format

Default OIDC Claim Mapping

Passport Field	OIDC Claim	Scope Required
`user.userId`	`sub`	`openid` (always)
`user.email`	`email`	`email`
`user.emailVerified`	`email_verified`	`email`
`user.displayName`	`name`	`profile`
`user.firstName`	`given_name`	`profile`
`user.lastName`	`family_name`	`profile`
`user.roles[]`	`roles`	`roles`
`user.tenantId`	`tenant_id`	`tenant`
`user.tenantName`	`tenant_name`	`tenant`

Custom Attribute Mapping Configuration

Override the defaults by specifying an attributeMapping section in the consumer registration. Each entry maps a Passport source field to an assertion attribute name, with an optional transform.

// Consumer registration with custom attribute mapping
{
  "consumerKey": "workday-hr",
  "protocol": "SAML2",
  "attributeMapping": {
    "email": {
      "source": "user.email",
      "samlName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    },
    "firstName": {
      "source": "user.firstName",
      "samlName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
    },
    "lastName": {
      "source": "user.lastName",
      "samlName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
    },
    "employeeId": {
      "source": "user.customAttributes.employeeId",
      "samlName": "urn:oid:2.16.840.1.113730.3.1.3"
    },
    "department": {
      "source": "user.customAttributes.department",
      "samlName": "urn:oid:2.16.840.1.113730.3.1.2"
    },
    "roles": {
      "source": "user.roles",
      "samlName": "groups",
      "transform": "groupMapping"
    }
  }
}

Available Source Fields

Source Path	Type	Description
`user.userId`	string	Passport user GUID — stable identifier
`user.email`	string	Primary email address
`user.firstName`	string	Given name
`user.lastName`	string	Family name
`user.displayName`	string	Full display name (may be composite)
`user.phone`	string	Primary phone number
`user.roles`	string[]	Role names assigned in current tenant
`user.tenantId`	string	Tenant identifier
`user.tenantName`	string	Tenant display name
`user.customAttributes.*`	any	Custom user profile attributes (configurable per installation)

Value Transforms

Apply a transform to modify the value before it is written to the assertion:

Transform	Description	Example
`groupMapping`	Applies the consumer's `groupMappings` table to role values	`manager` → `Salesforce_Manager`
`lowercase`	Converts string to lowercase	`Jane` → `jane`
`uppercase`	Converts string to uppercase	`Jane` → `JANE`
`emailDomain`	Extracts domain portion of email	`jane@acme.com` → `acme.com`
`join(separator)`	Joins array values with separator	`["a","b"]` → `"a,b"`

Custom Attributes Must Be Pre-Provisioned

Custom user attributes (user.customAttributes.*) must be defined in the Passport schema configuration before they can be used in attribute mappings. Referencing an undefined attribute produces an empty value in the assertion — not an error. Use the Admin API to inspect available custom attributes for your tenant.

Attribute Mapping for Common SaaS Platforms

Salesforce

"attributeMapping": {
  "email":      { "source": "user.email",       "samlName": "email" },
  "firstName":  { "source": "user.firstName",   "samlName": "firstName" },
  "lastName":   { "source": "user.lastName",    "samlName": "lastName" },
  "federationId":{ "source": "user.userId",     "samlName": "federationId" }
}

Microsoft 365 / Azure AD

"attributeMapping": {
  "upn": {
    "source": "user.email",
    "samlName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
  },
  "immutableId": {
    "source": "user.userId",
    "samlName": "http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID"
  }
}

← Application Trust Next: SSO Session Management →