Handling SAML Attributes and Mapping
SAML can carry user attributes along with authentication results. Knowing the naming differences and mapping tips makes operations smoother.
📄 Attribute Basics
Attributes normally occur in Assertion/AttributeStatement. Validate signature, issuer and recipient before mapping accounts or permissions. Names such as email below are examples, not mandatory names shared by every IdP.
Common attributes
- ✅ email: Used as login ID or notification address.
- ✅ givenName / surname: Used for display name.
- ✅ groups / roles: Used for access control.
🧩 Attribute Mapping
Map IdP-provided attribute names to your internal user fields.
Mapping tips
- 🔍 Attribute names and namespaces differ by IdP (Microsoft Entra ID (formerly Azure AD), Okta, Google Workspace).
- 🔍 Agree on required attributes up front; missing values can break login.
- 🔍 Verify values in test/staging; they may differ from production tenants.
⚙️ IdP Differences and Setup Tips
Attribute names/namespaces differ by IdP, so align expectations and document them up front.
Attribute Profile
SAML defines Attribute Profiles (e.g., X.500/LDAP) to standardize attribute names/namespaces. Using a standard profile improves interoperability.
- Refer to standard profiles (e.g., X.500/LDAP Attribute Profile) and align names/namespaces.
- If using IdP-specific custom attributes, document the SP mapping explicitly.
- Agree whether the integration follows a standard profile.
IdP specifics
- 🔧 Check the configured Name and NameFormat. The issuer entityID is separate from attribute naming.
- 🔧 Use the agreed Name rather than relying only on FriendlyName.
- 🔧 AttributeValue can be multi-valued. Test missing, empty and multiple values, especially for groups.
SP-side tips
- 🛠️ Document accepted attribute names and share with the IdP team.
- 🛠️ Define AttributeConsumingService in metadata when possible.
- 🛠️ Track tenant/env differences and share them with support teams.