Claims Value Providers
Claims value providers gather and supply claims about authenticated users. A claim is an attribute with a name and a value. Each provider returns a map of key-to-value pairs from different sources such as user stores, external services, authentication context, or computed values.
Use Cases#
Claims value providers enable you to include user attributes and contextual information in tokens issued by the Curity Identity Server.
Common use cases include:
- User Profile Data: Include user attributes from account managers or data sources in ID tokens and access tokens
- Authentication Context: Add information about how and when the user authenticated to enable context-aware authorization
- Client Information: Include details about the requesting application to help APIs understand the caller’s identity
- Certificate Attributes: Extract claims from client certificates for certificate-based authentication and authorization
- System Metadata: Add server information like entity IDs or base URLs for service discovery
- Computed Values: Use scripts to transform or calculate claims based on multiple data sources
Getting Started#
To configure claims value providers, sign in to the Admin UI and navigate to Profiles → Token Service → Scopes → Claims Providers.
Select + New Claims Value Provider to create a provider instance.
Variations#
The Curity Identity Server includes ten built-in claims value provider types. Each provider retrieves claims from a different source:
Script
Execute custom JavaScript procedures to compute claims dynamically. Script providers enable transformation logic, data enrichment, and complex claim calculations based on multiple inputs.
Data Source
Retrieve claims from external data sources configured in the system. Connect to databases, REST APIs, or other data repositories to fetch user attributes.
Client Certificate
Extract claims from client certificates presented during authentication. Access certificate attributes like subject DN, organization identifier, PSD2 roles, and subject alternative names.
Authentication Subject
Use attributes from the authenticated user’s subject. Access basic user information like username that authenticators collect during the authentication flow.
Authentication Context
Access contextual information about the authentication session. Retrieve details like authentication method (ACR), client information, and other context-specific attributes.
Account Manager
Fetch user attributes from configured account managers. Connect to user stores to retrieve complete user profiles and custom attributes.
System Information
Include system-level metadata like entity ID, base URL, and zone information. Useful for multi-tenant deployments and service discovery scenarios.
Admin Groups
Include administrative group membership information in tokens. Useful for authorization scenarios where admin UI groups determine access levels and permissions.
Consent
Access consent-related information about which scopes and claims the user has approved. Track user consent decisions for privacy and compliance requirements.
Extensibility Points#
Claims value providers extend the token issuance process through composition. Configure multiple provider instances with different behaviors to gather claims from various sources.
Extension Approaches#
Script-Based Extension: Create custom script claims providers that implement business logic using JavaScript. Scripts can access authentication context, transform data, and compute dynamic claim values. See Scripting Guide for implementation details.
Plugin-Based Extension: Develop custom claims provider plugins using the Java SDK for sophisticated claim gathering logic. Plugins enable integration with proprietary systems or complex data transformation requirements. Learn more in the Plugin Development section.
Data Source Integration: Connect to external systems through Data Sources to fetch user attributes. This composition approach allows centralized management of connections to user stores and APIs.
Multiple Instance Support#
Configure multiple claims provider instances to handle different scenarios:
- Different providers for different scopes or claim types
- Separate providers for different user populations or tenants
- Specialized providers for specific authentication methods
Each provider instance operates independently and can be referenced by claims mappers to control token composition.
Further Details#
Claims Provider Workflow#
Claims value providers execute during token issuance following this workflow:
- Token request arrives at the token service
- Claims mappers determine which providers to invoke based on requested scopes
- Each provider retrieves claims from its configured source
- Claims mappers transform and filter the retrieved values
- Final claims are included in the issued token
Configure claims providers independently from claims mappers to maintain flexibility. This separation enables reuse of the same provider across different scopes and token types.
Learn More#
For comprehensive guidance on implementing claims-based authorization and token design:
- Claims Mapping Configuration — Learn how to map provider output to token claims
- Scopes and Claims — Understand the relationship between scopes, claims providers, and claims mappers
- Scripting Guide — Write custom script-based claims providers
- Token Design Best Practices — Architectural patterns for secure and efficient token structures
- Data Sources — Configure external data sources for claims retrieval
- Account Managers — Integrate with user stores for profile data