Attribute Mapping

Attribute mapping allows you to transform and map user attributes between different systems and protocols in Keycloak. This guide covers the fundamentals of attribute mapping for OIDC, SAML, and custom applications.

Overview

Attribute mapping is essential for:

• Transforming user data between different formats
• Exposing specific user attributes to applications
• Maintaining data consistency across systems
• Implementing custom business logic for attributes

Types of Attribute Mappers

User Property Mapper

Maps basic user properties like email, username, and first/last name.

User Attribute Mapper

Maps custom user attributes stored in Keycloak to protocol claims.

Hardcoded Attribute Mapper

Adds a fixed value to tokens or assertions.

Group Membership Mapper

Includes user’s group memberships in the authentication response.

Role List Mapper

Maps user roles to claims or assertions.

OIDC Attribute Mapping

For OpenID Connect applications, attributes are mapped to JWT claims.

Common OIDC Mappings

email → email
firstName → given_name
lastName → family_name
username → preferred_username
groups → groups
roles → realm_access.roles

Creating OIDC Mappers

1. Navigate to your OIDC client in Skycloak
2. Go to the Client Scopes tab
3. Select the appropriate scope (usually the client’s dedicated scope)
4. Click Add Mapper → By configuration
5. Choose the mapper type
6. Configure the mapping

SAML Attribute Mapping

For SAML applications, attributes are mapped to SAML assertions.

Common SAML Mappings

email → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
firstName → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
lastName → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
groups → http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Creating SAML Mappers

1. Navigate to your SAML client in Skycloak
2. Go to the Mappers tab
3. Click Create to add a new mapper
4. Configure:
   • Name: Descriptive name for the mapper
   • Mapper Type: Select appropriate type
   • Property: Source attribute
   • SAML Attribute Name: Target attribute name
   • SAML Attribute NameFormat: Format specification

Advanced Mapping Scenarios

Conditional Mapping

Use JavaScript mappers for conditional logic:

// Only include department for internal users
var email = user.getEmail();
if (email && email.endsWith("@company.com")) {
    token.setOtherClaims("department", user.getAttribute("department"));
}

Composite Attributes

Combine multiple attributes into one:

// Create display name from first and last name
var firstName = user.getFirstName() || "";
var lastName = user.getLastName() || "";
token.setOtherClaims("displayName", firstName + " " + lastName);

Dynamic Group Mapping

Map groups with prefix filtering:

// Only include groups starting with "app-"
var groups = user.getGroups();
var appGroups = [];
for (var i = 0; i < groups.size(); i++) {
    var group = groups.get(i);
    if (group.startsWith("/app-")) {
        appGroups.push(group.substring(1)); // Remove leading slash
    }
}
token.setOtherClaims("app_groups", appGroups);

User Attributes Management

Setting User Attributes

User attributes can be set through:

• Admin Console
• Admin REST API
• User registration forms
• Identity provider mappings

Attribute Validation

Implement validation using:

• Regular expressions
• Required field markers
• Custom validators

Protocol-Specific Considerations

OIDC Scopes

Attributes can be grouped into scopes:

• profile: Basic profile information
• email: Email address and verification status
• address: Physical address
• phone: Phone number
• Custom scopes for domain-specific attributes

SAML NameID Formats

Choose appropriate NameID format:

• email: Uses email as identifier
• persistent: Stable pseudonym
• transient: Temporary identifier
• unspecified: No specific format

Best Practices

1. Minimize Exposed Data: Only map necessary attributes
2. Use Standard Claims: Follow OIDC/SAML standards when possible
3. Document Mappings: Maintain documentation of all attribute mappings
4. Test Thoroughly: Verify mappings with actual authentication flows
5. Consider Performance: Complex mappers can impact performance
6. Secure Sensitive Data: Be cautious with PII and sensitive attributes

Troubleshooting

Attributes Not Appearing

1. Check mapper configuration
2. Verify user has the attribute set
3. Confirm client/scope settings
4. Review protocol mapper scope

Wrong Attribute Format

1. Check NameFormat (SAML) or claim type (OIDC)
2. Verify data transformation logic
3. Review application expectations

Performance Issues

1. Simplify complex JavaScript mappers
2. Cache frequently accessed data
3. Reduce number of mapped attributes

Integration Examples

Salesforce SAML

Mapper Type: User Property
Property: email
SAML Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
SAML Attribute NameFormat: URI Reference

AWS Cognito OIDC

Mapper Type: User Attribute
User Attribute: department
Token Claim Name: custom:department
Add to ID Token: Yes
Add to Access Token: Yes

Next Steps

• Set Up Identity Providers
• Implement Multi-Factor Authentication