What Is Claim Mapping?

Claim mapping is the process of translating and standardizing user attributes from an identity provider (IdP) into a format that a consuming service provider (SP) can understand and utilize.

In a modern, federated identity system, an IdP—such as Microsoft Entra ID or Google Identity—manages user identities and authenticates users. When a user signs into an application (the SP), the IdP issues a security token containing "claims," which are pieces of information about the user, like their name, email, or role.

The core function of claims mapping

The primary purpose of claims mapping is to resolve discrepancies between the claim terminology used by the IdP and the SP. An IdP might refer to a user's email as emailaddress, but an SP might expect it to be labeled user_email. The claims mapping configuration handles this translation, ensuring that the SP receives the correct information in the expected format.

Claims mapping in action: The authentication flow

1. User authentication: A user attempts to sign into a service provider (e.g., a SaaS application) using Single Sign-On (SSO).
2. Redirect to IdP: The service provider redirects the user to the identity provider to authenticate.
3. Authentication and token issuance: The IdP verifies the user's identity and generates a security token (like an ID token or SAML assertion) containing the user's claims.
4. Claim mapping execution: Before sending the token to the SP, the claims mapping rules are applied. The identity system's configuration dictates how the source claims from the IdP (e.g., givenname, groups) are mapped to the target claims expected by the SP (e.g., first_name, user_roles).
5. Token delivery and authorization: The token, now with the correctly mapped claims, is sent to the service provider. The SP reads these claims to grant the user appropriate access and privileges.

Key components of a claims mapping policy

A claims mapping policy defines the transformation rules. It typically includes:

• Source Claims: The claims and their values as they originate from the identity provider. A mapping can be based on the claim's name and a specific value, or it can be configured to match a regular expression.
• Target Claims: The desired claim names and values that the service provider will receive in the token.
• Mapping logic: The rules that dictate the translation.
  • Literal mapping: Maps a source claim directly to a target claim. For example, the IdP's email claim becomes the SP's email_address claim.
  • Conditional mapping: Adds target claims only if certain source claims are present. For example, if a user belongs to the IdP group "engineers," they are assigned the "Contributor" role in the SP.
  • Claim transformations: Creates or modifies claims. A simple transformation might convert a claim value to a different format, while a complex one might merge multiple source claims into a single target claim.

Benefits of claims mapping

Claims mapping provides a flexible and powerful way to manage access control in a federated environment.

• Decoupling IdP and SP: The identity provider and service provider do not need to share the same internal terminology, simplifying integration and reducing dependencies.
• Granular access control: Role-based access control (RBAC) can be managed by mapping claims from the IdP to roles in the SP, ensuring users are assigned the correct permissions.
• Enhanced security: Claims can be customized to send only the essential user information to the SP, following the principle of least privilege.
• Dynamic provisioning: Claims mapping can be used to dynamically provision user accounts and assign roles based on existing identity attributes, automating user management.

Example: Claims mapping for SaaS applications

Imagine a company that uses Microsoft Entra ID as its IdP and an external SaaS application as an SP.

• Source claims (from Entra ID):
  • email: [email protected]
  • groups: ["finance_team", "marketing_team"]
• Target claims (for the SaaS application):
  • user_email: The application needs the user's email to identify them.
  • role: The application assigns roles (e.g., "Editor," "Viewer") based on the user's department.
• Mapping configuration:
  • Map the email claim from Entra ID to the user_email claim for the SaaS application.
  • Create a rule that maps the Entra ID group "finance_team" to the SaaS role "Editor".
• Result: When a user from the finance team logs in, the SaaS application receives a token that correctly identifies their email and assigns them the "Editor" role, streamlining the sign-in and authorization process.