Attribute Mapping when using Keycloak as a SAML SP

Introduction

Earlier, in this article, we discussed how to configure Keycloak as a SAML Service Provider (SP) and Okta as a SAML Identity Provider (IDP). This article extends that configuration and demonstrates how to map user attributes sent from Okta into Keycloak.

Attribute mapping ensures Keycloak correctly identifies and provisions authenticated users by capturing key fields such as email, first name, and last name

Configuration Steps

To map attributes, you must configure:

1. Attribute settings in the Okta SAML application
2. Attribute mapping in Keycloak

For more details on Keycloak as an Identity Broker, you may refer Keycloak server admin guide.

Step 1: Configure Attributes for Keycloak in Okta

1. Navigate to Okta Developer Console.
2. Go to Applications -> Your Keycloak SAML App (created in the previous article, named kc-client).
3. Open the General tab and click Edit under SAML Setting
4. Proceed to the Configure SAML Settings page.
5. Add the attribute statements for:
   • email
   • firstName
   • lastName

Note on Email Attribute

Here, we map the Okta username as the email value. By default, Okta usernames are email-formatted and unique, while Okta’s primary email field may not always be unique across all user records. Since Keycloak requires emails to be unique across users, mapping the username is safer and consistent.

Step 2: Add Attribute Mappings in Keycloak

Now configure Keycloak:

1. Open Keycloak Admin Console Identity Providers -> Okta
2. Locate the SAML dialog
3. Open Mappers → Add Mapper
4. Create individual mappers for:
   • email
   • firstName
   • lastName

You may refer to the screenshot provided below showing sample configuration for firstName.

Testing the Integration

1. Access your Keycloak Account Console: https://skycloak_hostname>/realms/<your_realm_name>/account or launch a protected application.
2. Click Sign in with Okta
3. Authenticate in Okta
4. Keycloak will automatically create (or update) a local user record with mapped attributes

Validating Using SAML Debugger

Using Firefox with the SAML Tracer extension:

• Inspect the SAML Response
• You will see attribute statements matching:
  • email
  • firstName
  • LastName
• The SAML NameID field will also be visible for reference

Screenshots referenced earlier will illustrate these payloads.

Summary

In this article, we covered:

• How to configure attribute statements for Keycloak within Okta
• How to map those attributes inside Keycloak

We used Skycloak, a fully managed Keycloak hosting solution, for demonstration.

Skycloak provides production-ready managed Keycloak hosting, helping teams avoid the complexity of maintaining and scaling Keycloak themselves.

If you’re new to Skycloak, visit the Skycloak Getting Started Guide to learn more.