Package org.opensaml.saml.security.impl

# Class MetadataCredentialResolver

java.lang.Object
org.opensaml.security.credential.impl.AbstractCredentialResolver
org.opensaml.security.credential.impl.AbstractCriteriaFilteringCredentialResolver
org.opensaml.saml.security.impl.MetadataCredentialResolver

All Implemented Interfaces:
  `Component`, `InitializableComponent`, `Resolver<Credential,CriteriaSet>`, `CredentialResolver`

public class MetadataCredentialResolver extends AbstractCriteriaFilteringCredentialResolver implements InitializableComponent
A credential resolver capable of resolving credentials from SAML 2 metadata.

Credentials may be resolved either by directly supplying an instance of `RoleDescriptor` in the input `CriteriaSet`, or by looking up the role descriptor via a supplied `RoleDescriptorResolver`.

The following resolution modes and associated `Criterion` inputs are supported:

Direct resolution from a supplied `RoleDescriptor`:

- `RoleDescriptorCriterion` - required
- `UsageCriterion` - optional; if absent, the effective value `UsageType.UNSPECIFIED` will be used for credential resolution.

Resolution from a metadata source using a `RoleDescriptorResolver`:

- `EntityIdCriterion` - required
- `EntityRoleCriterion` - required
- `ProtocolCriterion` - optional; if absent, credentials will be resolved from all matching roles, regardless of protocol support.
- `UsageCriterion` - optional; if absent, the effective value `UsageType.UNSPECIFIED` will be used for credential resolution.

In order to support resolution from a metadata source using `EntityIdCriterion` + `EntityRoleCriterion`, an instance of `RoleDescriptorResolver` must be supplied. Otherwise it is optional.

An instance of `KeyInfoCredentialResolver` must always be supplied.

## Field Summary

Fields
Modifier and Type
Field
Description
`private boolean`
`isInitialized`
Initialization flag.
`private KeyInfoCredentialResolver`
`keyInfoCredentialResolver`
Credential resolver used to resolve credentials from role descriptor KeyInfo elements.
`private final org.slf4j.Logger`
`log`
Class logger.
`private RoleDescriptorResolver`
`roleDescriptorResolver`
Metadata RoleDescriptor resolver which is the source of credentials.

## Constructor Summary

Constructors
Constructor
Description
`MetadataCredentialResolver()`

## Method Summary

Modifier and Type
Method
Description
`protected void`
`extractCredentials(Collection<Credential> accumulator, KeyDescriptor keyDescriptor, String entityID, UsageType mdUsage)`
Extract the credentials from the specified KeyDescriptor.
`protected UsageType`
`getEffectiveUsageInput(CriteriaSet criteriaSet)`
Get the effective `UsageType` input to use.
`KeyInfoCredentialResolver`
`getKeyInfoCredentialResolver()`
Get the KeyInfo credential resolver used by this entityDescriptorResolver resolver to handle KeyInfo elements.
`RoleDescriptorResolver`
`getRoleDescriptorResolver()`
Get the metadata RoleDescriptor resolver instance used by this resolver.
`protected Iterable<RoleDescriptor>`
`getRoleDescriptors(CriteriaSet criteriaSet, String entityID, QName role, String protocol)`
Get the list of role descriptors which match the given entityID, role and protocol.
`protected void`
`ifInitializedThrowUnmodifiabledComponentException()`
Checks if a component has been initialized and, if so, throws a `UnmodifiableComponentException`.
`protected void`
`ifNotInitializedThrowUninitializedComponentException()`
Checks if a component has not been initialized and, if so, throws a `UninitializedComponentException`.
`void`
`initialize()`
`boolean`
`isInitialized()`
`protected boolean`
`matchUsage(UsageType metadataUsage, UsageType criteriaUsage)`
Match usage enum type values from entityDescriptorResolver KeyDescriptor and from credential criteria.
`protected void`
`processRoleDescriptor(Collection<Credential> accumulator, RoleDescriptor roleDescriptor, String entityID, UsageType usage)`
Process a RoleDescriptor by examing each of its KeyDescriptors.
`protected Collection<Credential>`
`resolveFromMetadata(CriteriaSet criteriaSet, String entityID, QName role, String protocol, UsageType usage)`
Resolves credentials using this resolver's configured instance of `RoleDescriptorResolver`.
`protected Collection<Credential>`
`resolveFromRoleDescriptor(CriteriaSet criteriaSet, RoleDescriptor roleDescriptor, UsageType usage)`
Resolves credentials using a supplied instance of `RoleDescriptor`.
`protected Iterable<Credential>`
`resolveFromSource(CriteriaSet criteriaSet)`
Subclasses are required to implement this method to resolve credentials from the implementation-specific type of underlying credential source.
`void`
`setKeyInfoCredentialResolver(KeyInfoCredentialResolver resolver)`
Set the KeyInfo credential resolver used by this entityDescriptorResolver resolver to handle KeyInfo elements.
`void`
`setRoleDescriptorResolver(RoleDescriptorResolver resolver)`
Set the metadata RoleDescriptor resolver instance used by this resolver.

### Methods inherited from class org.opensaml.security.credential.impl.AbstractCriteriaFilteringCredentialResolver

`isSatisfyAllPredicates, resolve, setSatisfyAllPredicates`

### Methods inherited from class org.opensaml.security.credential.impl.AbstractCredentialResolver

`resolveSingle`

### Methods inherited from class java.lang.Object

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

## Field Details

### log

@Nonnull private final org.slf4j.Logger log
Class logger.

### roleDescriptorResolver

@Nullable private RoleDescriptorResolver roleDescriptorResolver
Metadata RoleDescriptor resolver which is the source of credentials.

### keyInfoCredentialResolver

@NonnullAfterInit private KeyInfoCredentialResolver keyInfoCredentialResolver
Credential resolver used to resolve credentials from role descriptor KeyInfo elements.

### isInitialized

private boolean isInitialized
Initialization flag.

## Constructor Details

### MetadataCredentialResolver

public MetadataCredentialResolver()

## Method Details

### isInitialized

public boolean isInitialized()

Specified by:
  `isInitialized` in interface `InitializableComponent`

### ifNotInitializedThrowUninitializedComponentException

protected void ifNotInitializedThrowUninitializedComponentException()
Checks if a component has not been initialized and, if so, throws a `UninitializedComponentException`.

### ifInitializedThrowUnmodifiabledComponentException

protected void ifInitializedThrowUnmodifiabledComponentException()
Checks if a component has been initialized and, if so, throws a `UnmodifiableComponentException`.

### initialize

public void initialize() throws ComponentInitializationException

Specified by:
  `initialize` in interface `InitializableComponent`
Throws:
  `ComponentInitializationException`

### getRoleDescriptorResolver

@Nullable public RoleDescriptorResolver getRoleDescriptorResolver()
Get the metadata RoleDescriptor resolver instance used by this resolver.

This is optional. If not supplied, credentials may only be resolved via input of a `RoleDescriptorCriterion`.

Returns:
  the resolver's RoleDescriptor metadata resolver instance

### setRoleDescriptorResolver

public void setRoleDescriptorResolver(@Nullable RoleDescriptorResolver resolver)
Set the metadata RoleDescriptor resolver instance used by this resolver.

This is optional. If not supplied, credentials may only be resolved via input of a `RoleDescriptorCriterion`.

Parameters:
  `resolver` - the new RoleDescriptorResolver to use

### getKeyInfoCredentialResolver

@NonnullAfterInit public KeyInfoCredentialResolver getKeyInfoCredentialResolver()
Get the KeyInfo credential resolver used by this entityDescriptorResolver resolver to handle KeyInfo elements.

Returns:
  KeyInfo credential resolver

### setKeyInfoCredentialResolver

public void setKeyInfoCredentialResolver(@Nonnull KeyInfoCredentialResolver resolver)
Set the KeyInfo credential resolver used by this entityDescriptorResolver resolver to handle KeyInfo elements.

Parameters:
  `resolver` - the new KeyInfoCredentialResolver to use

### resolveFromSource

@Nonnull protected Iterable<Credential> resolveFromSource(@Nullable CriteriaSet criteriaSet) throws ResolverException
Subclasses are required to implement this method to resolve credentials from the implementation-specific type of underlying credential source.

Specified by:
  `resolveFromSource` in class `AbstractCriteriaFilteringCredentialResolver`
Parameters:
  `criteriaSet` - the set of criteria used to resolve credentials from the credential source
Returns:
  an Iterable for the resolved set of credentials
Throws:
  `ResolverException` - thrown if there is an error resolving credentials from the credential source

### getEffectiveUsageInput

@Nonnull protected UsageType getEffectiveUsageInput(@Nullable CriteriaSet criteriaSet)
Get the effective `UsageType` input to use.

Parameters:
  `criteriaSet` - the criteria set being processed
Returns:
  the effective usage value

### resolveFromRoleDescriptor

@Nonnull @Unmodifiable @NotLive protected Collection<Credential> resolveFromRoleDescriptor(@Nullable CriteriaSet criteriaSet, @Nonnull RoleDescriptor roleDescriptor, @Nonnull UsageType usage) throws ResolverException
Resolves credentials using a supplied instance of `RoleDescriptor`.

Parameters:
  `criteriaSet` - the criteria set being processed
  `roleDescriptor` - the role descriptor being processed
  `usage` - intended usage of resolved credentials
Returns:
  the resolved credentials or null
Throws:
  `ResolverException` - thrown if the key, certificate, or CRL information is represented in an unsupported format

### resolveFromMetadata

@Nonnull @Unmodifiable @NotLive protected Collection<Credential> resolveFromMetadata(@Nullable CriteriaSet criteriaSet, @Nonnull @NotEmpty String entityID, @Nonnull QName role, @Nullable String protocol, @Nonnull UsageType usage) throws ResolverException
Resolves credentials using this resolver's configured instance of `RoleDescriptorResolver`.

Parameters:
  `criteriaSet` - the criteria set being processed
  `entityID` - entityID of the credential owner
  `role` - role in which the entity is operating
  `protocol` - protocol over which the entity is operating (may be null)
  `usage` - intended usage of resolved credentials
Returns:
  the resolved credentials or null
Throws:
  `ResolverException` - thrown if the key, certificate, or CRL information is represented in an unsupported format

### processRoleDescriptor

protected void processRoleDescriptor(@Nonnull Collection<Credential> accumulator, @Nonnull RoleDescriptor roleDescriptor, @Nullable String entityID, @Nonnull UsageType usage) throws ResolverException
Process a RoleDescriptor by examing each of its KeyDescriptors.

Parameters:
  `accumulator` - the collection of credentials being accumulated for return to the caller
  `roleDescriptor` - the KeyDescriptor being processed
  `entityID` - the entity ID of the KeyDescriptor being processed
  `usage` - the credential usage type specified as resolve input
Throws:
  `ResolverException` - if there is a problem resolving credentials from the KeyDescriptor's KeyInfo element

### extractCredentials

protected void extractCredentials(@Nonnull Collection<Credential> accumulator, @Nonnull KeyDescriptor keyDescriptor, @Nullable String entityID, @Nonnull UsageType mdUsage) throws ResolverException
Extract the credentials from the specified KeyDescriptor. First the credentials are looking up in object metadata cache. If they are not found there, then they will be resolved from the KeyDescriptor's KeyInfo and then cached in the KeyDescriptor's object metadata before returning.

Parameters:
  `accumulator` - the collection of credentials being accumulated for return to the caller
  `keyDescriptor` - the KeyDescriptor being processed
  `entityID` - the entity ID of the KeyDescriptor being processed
  `mdUsage` - the effective credential usage type in effect for the resolved credentials
Throws:
  `ResolverException` - if there is a problem resolving credentials from the KeyDescriptor's KeyInfo element

### matchUsage

protected boolean matchUsage(@Nonnull UsageType metadataUsage, @Nonnull UsageType criteriaUsage)
Match usage enum type values from entityDescriptorResolver KeyDescriptor and from credential criteria.

Parameters:
  `metadataUsage` - the value from the 'use' attribute of a entityDescriptorResolver KeyDescriptor element
  `criteriaUsage` - the value from credential criteria
Returns:
  true if the two usage specifiers match for purposes of resolving credentials, false otherwise

### getRoleDescriptors

@Nonnull protected Iterable<RoleDescriptor> getRoleDescriptors(@Nullable CriteriaSet criteriaSet, @Nonnull String entityID, @Nonnull QName role, @Nullable String protocol) throws ResolverException
Get the list of role descriptors which match the given entityID, role and protocol.

Parameters:
  `criteriaSet` - criteria set being processed
  `entityID` - entity ID of the credential owner
  `role` - role in which the entity is operating
  `protocol` - protocol over which the entity is operating (may be null)
Returns:
  a list of role descriptors matching the given parameters, or null
Throws:
  `ResolverException` - thrown if there is an error retrieving role descriptors from the entityDescriptorResolver provider