Normalizing Claims Across Customer Identity Providers

Federation solves the login problem, but it does not automatically solve the application contract problem.

Two enterprise customers can both use OpenID Connect and still send different claim names, different identifiers, different group representations, and different assumptions about which attributes are present. One customer may federate through Azure AD. Another may use ADFS. A third may bring a custom OpenID Connect provider. If every application service learns those differences directly, federation has only moved the complexity from the login screen into the product.

For a SaaS application, the better boundary is clear: applications trust ProAuth, and ProAuth absorbs the differences between customer identity providers. The application should receive predictable tokens from one issuer, with claims that match the product’s identity model.

Start with the application identity contract

Before discussing claim rules, define what the application actually needs.

For most SaaS products, the contract is smaller than the upstream directory model. It may include:

• a stable user identifier for authorization decisions and audit trails
• a display name and email address for UI and notifications
• tenant and customer context
• application roles or group-derived permissions
• a small set of profile values the product genuinely uses

OpenID Connect already gives useful language for this discussion. It defines standard claims such as sub, name, given_name, family_name, email, and email_verified. It also warns that the only globally reliable end-user identifier is the combination of issuer and subject; claims such as email, preferred_username, and name are not guaranteed to be stable or unique across issuers (OpenID Connect Core, claim stability and uniqueness).

That is the important architectural point. The application should not quietly turn a convenient upstream claim into a permanent identity key unless the identity platform has made that mapping explicit.

Where normalization belongs

ProAuth is designed to sit between the SaaS application and the customer’s identity provider. The application has a single trust relation to ProAuth, while ProAuth federates with customer-specific providers and issues the tokens used by the application. The earlier article on tenant identification shows this pattern in a multi-tenant login flow: the tenant is resolved, the user is routed to the tenant’s configured IdP instance, ProAuth validates the upstream token, aligns claims, and issues the application-facing token.

The ProAuth documentation describes the same separation in the product overview: applications should rely on a trusted identity provider, and new federated identity providers or customer-specific configurations should not force application changes. In the “Different Identity Providers” section, ProAuth documents that security tokens are normalized for applications by the claim rule engine, including rules to convert claims, add claims, and remove claims.

flowchart LR
    subgraph "Customer Identity Providers"
        AAD["Azure AD<br/>tenant-specific OIDC claims"]
        ADFS["ADFS<br/>customer directory claims"]
        Custom["Custom OIDC IdP<br/>provider-specific claims"]
    end

    subgraph "ProAuth tenant context"
        Federation["Federated IdP instance"]
        Rules["Claim rule engine<br/>filter, transform, create"]
        Token["Normalized ProAuth token<br/>stable application contract"]
    end

    subgraph "SaaS application"
        Portal["Portal"]
        APIs["Backend APIs"]
    end

    AAD --> Federation
    ADFS --> Federation
    Custom --> Federation
    Federation --> Rules
    Rules --> Token
    Token --> Portal
    Token --> APIs

This keeps provider variance on the identity side of the boundary. The application can still make fine-grained authorization decisions, but it makes them from a token contract it owns deliberately instead of from whatever a customer’s directory happens to emit.

What claim rules should do

The ProAuth claim rule documentation describes the claim rule engine as the step that runs before tokens are issued. It processes ProAuth claims together with claims from federated identity providers, and only the resulting claims are added to the issued tokens. Mandatory or sensitive claims, for example sub, cannot be modified by the claim rule engine.

That gives teams a practical toolbox:

• Filter claims that should not leave the identity boundary.
• Transform claim types or values when an upstream provider uses a different shape than the application contract.
• Create additional claims from fixed values or template variables when the application needs context that is not sent directly by the upstream provider.
• Choose whether the resulting claim belongs in the ID token, the access token, or both.

ProAuth claim rules can be associated at different levels: subscription, tenant, client application, or a combination of client application and IdP instance. That matters in multi-tenant SaaS. A mapping that is correct for one customer’s ADFS instance should not become a global assumption for every other tenant. Tenant-specific federation and scoped claim rules keep each customer’s directory model contained.

Normalize less than you collect

A common mistake is to forward every upstream claim “just in case.” It feels convenient during onboarding, but it turns every application and API into a long-term consumer of customer directory details.

ProAuth’s rule behavior pushes teams toward a cleaner model. The usage documentation notes that if no claim rules exist in a subscription, only mandatory claims are present in issued tokens and all other claims are dropped. In other words, claim release is an explicit decision. That is a good default for SaaS products: start with the claims the application contract requires, then add more only when a product feature has a clear need.

This is also where group claims need care. If a lower-level rule drops group information, later client-specific rules cannot recover it. If a customer sends very broad group data, forwarding all of it may expose directory structure that the application does not need. The claim contract should decide whether the application receives raw group identifiers, mapped application roles, or no group information at all.

A practical onboarding checklist

When adding a customer IdP, test the contract rather than only testing that login succeeds.

1. Capture the upstream claims from the provider in the customer’s tenant context.
2. Identify which upstream values map to the application contract.
3. Decide which claims are identifiers, which are display attributes, and which are authorization inputs.
4. Configure claim rules at the narrowest useful level: tenant, client application, or client application plus IdP instance.
5. Verify the resulting ID token and access token separately, because not every claim belongs in both.
6. Test missing and changed optional claims, especially email, display name, and groups.
7. Keep a small regression sample for the tenant so future rule changes do not silently alter the application contract.

The result should be boring in the best possible way. A user signs in through Azure AD, ADFS, or another OpenID Connect provider; ProAuth handles the provider-specific federation; and the SaaS application receives the same claim contract it already understands.

Keep the boundary honest

Claim normalization is not only a convenience feature. It is part of the trust boundary between customer identity systems and application code.

Applications should not need to know how every customer names a department, where a directory stores group membership, or which optional profile claims a provider chooses to send. They should know the contract they receive from ProAuth. That gives developers a stable model to build against, gives onboarding teams a concrete checklist, and gives each tenant room to bring its own identity provider without leaking that provider’s assumptions into every service.

For configuration details, see the ProAuth documentation for federated identity providers and claim rules.