Package org.keycloak.protocol.oid4vc.issuance.mappers

Class OID4VCMapper

java.lang.Object

org.keycloak.protocol.oid4vc.issuance.mappers.OID4VCMapper

All Implemented Interfaces:

OID4VCEnvironmentProviderFactory, ProtocolMapper, ConfiguredProvider, EnvironmentDependentProviderFactory, Provider, ProviderFactory<ProtocolMapper>

Direct Known Subclasses:

OID4VCContextMapper, OID4VCGeneratedIdMapper, OID4VCIssuedAtTimeClaimMapper, OID4VCStaticClaimMapper, OID4VCSubjectIdMapper, OID4VCTargetRoleMapper, OID4VCTypeMapper, OID4VCUserAttributeMapper

public abstract class OID4VCMapper
extends Object
implements ProtocolMapper, OID4VCEnvironmentProviderFactory

Base class for OID4VC Mappers, to provide common configuration and functionality for all of them

Author:

Stefan Wiedemann

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CLAIM_NAME
protected String	format
static final String	MAPPER_MISSING_MDOC_NAMESPACE_ERROR
static final String	MAPPER_RESERVED_CLAIM_ERROR
protected ProtocolMapperModel	mapperModel
static final String	MDOC_NAMESPACE
static final String	USER_ATTRIBUTE_KEY

Constructor Summary

Constructors

Constructor	Description
OID4VCMapper()

Method Summary

Modifier and Type	Method	Description
void	close()	This is called when the server shuts down.
protected Set<String>	getAllowedReservedClaims()	Returns the reserved, issuer-controlled claims this mapper is allowed to write.
protected List<String>	getAttributePrefix()
protected List<String>	getClaimLookupPath()	Returns the raw claim lookup path in the intermediate map populated by setClaim(Map, UserSessionModel).
protected List<String>	getClaimLookupPath(String claimName)
protected String	getClaimName()
protected String	getClaimName(String defaultClaimName)
List<ProviderConfigProperty>	getConfigProperties()
String	getDisplayCategory()
protected abstract List<ProviderConfigProperty>	getIndividualConfigProperties()
String	getMapperName()
List<String>	getMetadataAttributePath()	Returns the externally visible claim path used in credential metadata and authorization_details validation.
protected List<String>	getMetadataAttributePath(String attributeName)
String	getProtocol()
boolean	includeInMetadata()	some specific claims should not be added into the metadata.
void	init(Config.Scope scope)	Only called once when the factory is first created.
boolean	passesMappingGuards()	Returns true when this mapper passes all issuance-time guards.
void	postInit(KeycloakSessionFactory keycloakSessionFactory)	Called after all provider factories have been initialized
protected List<String>	prefixMetadataAttributePath(List<String> attributePath)
protected String	resolveClaimName(ProtocolMapperModel mapperModel)	Resolves the effective claim name written by this mapper, based on the given configuration.
abstract void	setClaim(Map<String,Object> claims, UserSessionModel userSessionModel)	Set the claims to the credential subject.
abstract void	setClaim(VerifiableCredential verifiableCredential, UserSessionModel userSessionModel)	Set the claims to credential, like f.e. the context
void	setClaimWithMetadataPrefix(Map<String,Object> claimsOrig, Map<String,Object> claimsWithPrefix)	Copies the mapper claim value into claimsWithPrefix using the externally visible credential path.
OID4VCMapper	setMapperModel(ProtocolMapperModel mapperModel, String format)
boolean	supportsCredentialFormat(String credentialFormat)	Some mappers target format-specific container fields instead of subject/data-element claims.
void	validate()	Runs all validations (credential-format and sensitive-mapping checks) for this mapper.
protected void	validateAgainstSensitiveMappings(String credentialFormat, ProtocolMapperModel mapperModel)	Rejects a mapper whose configured claim name targets a reserved, issuer-controlled claim (e.g. exp, iat, sub, jti) unless the mapper is explicitly allowed to write that claim (see getAllowedReservedClaims()).
void	validateConfig(KeycloakSession session, RealmModel realm, ProtocolMapperContainerModel client, ProtocolMapperModel mapperModel)	Called when instance of mapperModel is created/updated for this protocolMapper through admin endpoint
void	validateMdocNamespace(String credentialFormat)	Revalidates this mapper's namespace against the given format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.keycloak.provider.ConfiguredProvider

getConfig, getHelpText

Methods inherited from interface org.keycloak.protocol.oid4vc.OID4VCEnvironmentProviderFactory

isSupported

Methods inherited from interface org.keycloak.protocol.ProtocolMapper

getDisplayType, getEffectiveModel, getPriority

Methods inherited from interface org.keycloak.provider.ProviderFactory

create, dependsOn, getConfigMetadata, getId, order

Field Details

CLAIM_NAME

public static final String CLAIM_NAME

See Also:

• Constant Field Values

MDOC_NAMESPACE

public static final String MDOC_NAMESPACE

See Also:

• Constant Field Values

USER_ATTRIBUTE_KEY

public static final String USER_ATTRIBUTE_KEY

See Also:

• Constant Field Values

MAPPER_RESERVED_CLAIM_ERROR

public static final String MAPPER_RESERVED_CLAIM_ERROR

See Also:

• Constant Field Values

MAPPER_MISSING_MDOC_NAMESPACE_ERROR

public static final String MAPPER_MISSING_MDOC_NAMESPACE_ERROR

See Also:

• Constant Field Values

mapperModel

protected ProtocolMapperModel mapperModel

format

protected String format

Constructor Details

OID4VCMapper

public OID4VCMapper()

Method Details

getIndividualConfigProperties

protected abstract List<ProviderConfigProperty> getIndividualConfigProperties()

getMapperName

public String getMapperName()

getConfigProperties

public List<ProviderConfigProperty> getConfigProperties()

Specified by:

getConfigProperties in interface ConfiguredProvider

setMapperModel

public OID4VCMapper setMapperModel(ProtocolMapperModel mapperModel,
 String format)

validateConfig

public void validateConfig(KeycloakSession session,
 RealmModel realm,
 ProtocolMapperContainerModel client,
 ProtocolMapperModel mapperModel)
                    throws ProtocolMapperConfigException

Description copied from interface: ProtocolMapper

Called when instance of mapperModel is created/updated for this protocolMapper through admin endpoint

Specified by:

validateConfig in interface ProtocolMapper

client - client or clientTemplate

Throws:

ProtocolMapperConfigException - if configuration provided in mapperModel is not valid

validate

public void validate()
              throws ProtocolMapperConfigException

Runs all validations (credential-format and sensitive-mapping checks) for this mapper. Because scope updates/imports can bypass validateConfig(org.keycloak.models.KeycloakSession, org.keycloak.models.RealmModel, org.keycloak.models.ProtocolMapperContainerModel, org.keycloak.models.ProtocolMapperModel), the issuer endpoint invokes this centrally at issuance so a misconfigured mapper fails the request instead of emitting broken or overridden claims.

Throws:

ProtocolMapperConfigException

passesMappingGuards

public boolean passesMappingGuards()

Returns true when this mapper passes all issuance-time guards. Used where a misconfigured mapper is silently omitted (e.g. from issuer metadata) rather than failing the request.

validateAgainstSensitiveMappings

protected void validateAgainstSensitiveMappings(String credentialFormat,
 ProtocolMapperModel mapperModel)
                                         throws ProtocolMapperConfigException

Rejects a mapper whose configured claim name targets a reserved, issuer-controlled claim (e.g. exp, iat, sub, jti) unless the mapper is explicitly allowed to write that claim (see getAllowedReservedClaims()). Such a mapping could let a mapper override issuer-controlled claims (see keycloak/keycloak#52667).

Throws:

ProtocolMapperConfigException

validateMdocNamespace

public void validateMdocNamespace(String credentialFormat)
                           throws ProtocolMapperConfigException

Revalidates this mapper's namespace against the given format. Switching a client scope to mso_mdoc through the format selector does not run validateConfig(org.keycloak.models.KeycloakSession, org.keycloak.models.RealmModel, org.keycloak.models.ProtocolMapperContainerModel, org.keycloak.models.ProtocolMapperModel), so issuance uses this to reject an already stored claim mapper that is missing a namespace before it produces broken claims.

Throws:

ProtocolMapperConfigException

includeInMetadata

public boolean includeInMetadata()

some specific claims should not be added into the metadata. Examples are jti, sub, iss etc. Since we have the possibility to add these credentials with specific claims we should also be able to exclude these specific attributes from the metadata

supportsCredentialFormat

public boolean supportsCredentialFormat(String credentialFormat)

Some mappers target format-specific container fields instead of subject/data-element claims. Callers use this hook for both metadata and issuance so unsupported mappers are not advertised or applied for a credential format.

getMetadataAttributePath

public List<String> getMetadataAttributePath()

Returns the externally visible claim path used in credential metadata and authorization_details validation. JSON credentials use their normal credentialSubject/top-level paths; mDoc prepends the configured namespace because OID4VCI mDoc paths address namespace -> data element -> optional nested value.

getMetadataAttributePath

protected List<String> getMetadataAttributePath(String attributeName)

prefixMetadataAttributePath

protected List<String> prefixMetadataAttributePath(List<String> attributePath)

getClaimLookupPath

protected List<String> getClaimLookupPath()

Returns the raw claim lookup path in the intermediate map populated by setClaim(Map, UserSessionModel). This is intentionally separate from getMetadataAttributePath(): mDoc metadata paths add a namespace that is not present in the raw mapper output, and simple mappers may write a dotted claim name as one literal key.

getClaimLookupPath

protected List<String> getClaimLookupPath(String claimName)

getClaimName

protected String getClaimName()

getClaimName

protected String getClaimName(String defaultClaimName)

getAttributePrefix

protected List<String> getAttributePrefix()

getProtocol

public String getProtocol()

Specified by:

getProtocol in interface ProtocolMapper

getDisplayCategory

public String getDisplayCategory()

Specified by:

getDisplayCategory in interface ProtocolMapper

init

public void init(Config.Scope scope)

Description copied from interface: ProviderFactory

Only called once when the factory is first created.

Specified by:

init in interface ProviderFactory<ProtocolMapper>

postInit

public void postInit(KeycloakSessionFactory keycloakSessionFactory)

Description copied from interface: ProviderFactory

Called after all provider factories have been initialized

Specified by:

postInit in interface ProviderFactory<ProtocolMapper>

close

public void close()

Description copied from interface: ProviderFactory

This is called when the server shuts down.

Specified by:

close in interface Provider

Specified by:

close in interface ProviderFactory<ProtocolMapper>

setClaim

public abstract void setClaim(VerifiableCredential verifiableCredential,
 UserSessionModel userSessionModel)

Set the claims to credential, like f.e. the context

setClaim

public abstract void setClaim(Map<String,Object> claims,
 UserSessionModel userSessionModel)

Set the claims to the credential subject.

setClaimWithMetadataPrefix

public void setClaimWithMetadataPrefix(Map<String,Object> claimsOrig,
 Map<String,Object> claimsWithPrefix)

Copies the mapper claim value into claimsWithPrefix using the externally visible credential path. This is used for authorization_details validation and for mDoc issuance, where the credential subject is namespace-shaped even though individual mappers write un-namespaced raw claims.

Parameters:

claimsOrig - Map with the original claims, which were returned by setClaim(Map, UserSessionModel) . This method usually just reads from this map

claimsWithPrefix - Map with the claims including path prefix. This method might write to this map

getAllowedReservedClaims

protected Set<String> getAllowedReservedClaims()

Returns the reserved, issuer-controlled claims this mapper is allowed to write. A mapper may only target a reserved claim listed here; every other reserved claim is rejected. Mappers are denied all reserved claims by default; subclasses that legitimately write a specific issuer-controlled claim (e.g. the generated-id mapper writing 'jti') override this to allow just that claim.

resolveClaimName

protected String resolveClaimName(ProtocolMapperModel mapperModel)

Resolves the effective claim name written by this mapper, based on the given configuration. Subclasses override this when they derive the claim name with a fallback (e.g. user attribute or a default claim name).