This page documents common usage of subcontexts used in SAML 1 and SAML 2 messaging flows.

Subcontexts Description

General notes about subcontexts relevant to SAML 1 and 2 message flows.

(org.opensaml.messaging.context.BasicMessageMetadataContext)

Noted for historical reasons, plan was to get rid of this eventually, or at least usage of the messageIssuer property, in favor of protocol-specific context, e.g. SAMLPeerEntityContext

org.opensaml.saml.common.messaging.context.SAMLPeerEntityContext

holds entityID and role of SAML peer entity
smart: on inbound can pull data from SAML message (SAMLObject) in MessageContext#getMessage()

org.opensaml.saml.common.messaging.context.SAMLSelfEntityContext

holds entityID and role of SAML "self" entity

org.opensaml.saml.common.messaging.context.SAMLArtifactContext

holds source entityID, artifact type, source ArtifactResolutionService endpoing URL or index

org.opensaml.saml.common.messaging.context.SAMLBindingContext

holds binding URI, RelayState data
for inbound only: holds binding- and message-specific data, to support answering hasBindingSignature() and isIntendedDestinationEndpointRequired(), used by some security-oriented MessageHandlers

org.opensaml.saml.common.messaging.context.SAMLEndpointContext

holds metadata Endpoint for an entity
usually used as direct child of an entity context, interpreted as scoped to that entity and current role

org.opensaml.saml.common.messaging.context.SAMLMessageInfoContext

holds protocol message ID and IssueInstant
smart: on inbound can pull data from SAML message (SAMLObject) in MessageContext#getMessage()

org.opensaml.saml.common.messaging.context.SAMLMetadataContext

holds EntityDescriptor and RoleDescriptor
usually used as direct child of an entity context, interpreted as scoped to that entity and current role

org.opensaml.saml.common.messaging.context.SAMLProtocolContext

holds SAML protocol URI in use for the exchange

org.opensaml.saml.common.messaging.context.SAMLSubjectNameIdentifierContext

holds SAML NameID/NameIdentifier
smart: on inbound can pull data from SAML message (SAMLObject) in MessageContext#getMessage()

org.opensaml.xmlsec.context.SecurityParametersContext

holds 4 security -Parameters instances for the 4 uses cases of: 1) signing 2) signature validation 3) encryption 4) decryption

org.opensaml.soap.messaging.context.SOAP11Context

holds SOAP 1.1 Envelope
used only in SOAP 1.1 cases
inbound: populated by SOAP decoder. Used to provide consistent access to SOAP Envelope to MessageHandlers which do SOAP-specific processing
outbound: used to optionally supply an externally-constructed Envelope (e.g. with headers, etc). If not supplied, added by SOAP MessageEncoder#prepareContext(), used to provide consistent access to Envelope for use by SOAP-specific handling code (e.g. adding headers)

Inbound Flow

org.opensaml.saml.common.messaging.context.SAMLPeerEntityContext

REQUIRED: Used to represent inbound requester's entityID and role to a variety of other code.
SMART: For most SAML 1/2 cases, no need to populate entityID explicitly, context will pull data from decoded SAML message SAMLObject automagically. SAML 1 IdP-initiated decoder also populates from non-SAML Shibboleth protocol message.
Required to populate role from knowledge about the role under which the entity is operating

Children:

org.opensaml.saml.common.messaging.context.SAMLMetadataContext

- REQUIRED: Used to hold Entity- and RoleDescriptor for entity and role identified by immediate parent SAMLPeerEntityContext
- used by a variety of MessageHandlers and other code

org.opensaml.saml.common.messaging.context.SAMLEndpointContext

- NOT REQUIRED: appears not currently used on inbound

org.opensaml.saml.common.messaging.context.SAMLBindingContext

REQUIRED: Automatically created and populated by SAML MessageDecoders, used by a variety of downstream code.

org.opensaml.saml.common.messaging.context.SAMLProtocolContext

REQUIRED: Used by various components to lookup metadata and as metadata-based TrustEngine criteria input
Populated statically via knowledge of the SAML protocol in use

org.opensaml.saml.common.messaging.context.SAMLSelfEntityContext

OPTIONAL (currently): doesn't seem currently used on typical SAML flow.
Might be used in more advanced cases like delegation or ECP. Might be used outside of MessageContext tree within IdP to hold the self-referential entityID.

org.opensaml.saml.common.messaging.context.SAMLArtifactContext

OPTIONAL: Would only be relevant to an inbound message when artifact binding is in use. In that case, might be populated for informational purposes by an artifact MessageDecoder (NOTE: SAML artifact MessageDecoders are not implemented yet).

org.opensaml.saml.common.messaging.context.SAMLMessageInfoContext

REQUIRED: Used to represent message ID and IssueInstant, evaluated by some security-oriented message handlers, for message replay and message lifetime checks.
SMART: For most SAML 1/2 cases, no need to populate data explcitly, context will pull data from decoded SAML message SAMLObject automagically. SAML 1 IdP-initiated decoder also populates from non-SAML Shibboleth protocol message.

org.opensaml.saml.common.messaging.context.SAMLSubjectNameIdentifierContext

OPTIONAL: used to provide access to the request's Subject SAML 1 NameIdentifier or SAML 2 NameID, where relevant. Not currently used directly by any MessageContext-specific code.
SMART: context will pull data from decoded SAML message SAMLObject automagically.

org.opensaml.xmlsec.context.SecurityParametersContext

OPTIONAL (currently)
(TODO: not clear whether required for signature validation. Relationship between MessageHandlers' TrustEngines and this context's SignatureValidationParameters#getSignatureTrustEngine() needs to be worked out and clarified.)
- (QUESTION: do we support dynamic selection of TrustEngine at runtime based on peer entityID, etc? If so, need to use context to hold. Idea: Maybe support both in security message handlers: use context engine if present, otherwise use injected one.)
- (QUESTION: how do whitelist/blacklist algo URI's from context feed into signature eval process? This is an implementation TODO).

org.opensaml.soap.messaging.context.SOAP11Context

OPTIONAL: only used if using a SOAP 1.1 MessageDecoder
automatically populated by MessageDecoder

Outbound Flow

org.opensaml.saml.common.messaging.context.SAMLPeerEntityContext

REQUIRED: Used to represent outbound recipient's entityID and role to a variety of other code.
Required to populate entityID from knowledge about recipient (e.g. from inbound message on a response)
Required to populate role from knowledge about the role under which the entity is operating

Children:

org.opensaml.saml.common.messaging.context.SAMLMetadataContext

- OPTIONAL (currently): might be needed if metadata is used by any outbound MessageHandlers as part of their operation or to produce other data for the context (e.g. the SAML Endpoint). We don't currently have any that do this, but conceptually seems like a possibility.

org.opensaml.saml.common.messaging.context.SAMLEndpointContext

- REQUIRED: required by SAML 1 and 2 MessageEncoders, used as source of endpoint URI to which to deliver message
- populated using knowledge from peer entityID, metadata and role, inbound request, dynamically selected outbound binding URI, etc, e.g. using BasicEndpointSelector or AuthnResponseEndpontSelector

org.opensaml.saml.common.messaging.context.SAMLBindingContext

REQUIRED: RelayState is used by SAML MessageEncoders. For front-channel, binding URI specifies which type of outbound SAML MessageEncoder will be used at runtime.
RelayState should be transferred verbatim from inbound SAMLBindingContext
Binding URI should be selected at runtime based on metadata and inbound message data and populated accordingly.
- (TODO: does this happen in a ProfileAction or a MessageHandler? Perhaps easiest to do in a single ProfileAction that also transfers RelayState from inbound SAMLBindingContext).

org.opensaml.saml.common.messaging.context.SAMLProtocolContext

OPTIONAL (currently): doesn't seem currently used on outbound SAML flow, but conceptually could be (e.g. in conjunction with metadata from SAMLMetadataContext to resolve something)

org.opensaml.saml.common.messaging.context.SAMLSelfEntityContext

OPTIONAL (currently): doesn't seem currently used on typical SAML flow.
Might be used in more advanced cases like delegation or ECP.
Might be used outside of MessageContext tree within IdP to hold the self-referential entityID. (Note: on outbound, the "self" entityID value is populated on SAMLArtifactContext, when artifact binding is used.)

org.opensaml.saml.common.messaging.context.SAMLArtifactContext

OPTIONAL: required when artifact encoder in use, not used otherwise
would likely need to be populated by same component that dynamically selects outbound binding URI, when the latter is artifact.

org.opensaml.saml.common.messaging.context.SAMLMessageInfoContext

OPTIONAL: could be inputs to constructing a SAML Response message. Possibly/likely not used in MessageContext tree directly if the Response skeleton is constructed in ProfileAction(s) directly.

org.opensaml.saml.common.messaging.context.SAMLSubjectNameIdentifierContext

NOT USED: Not relevant to outbound MessageContext code. (Might be used by ProfileAction code outside of MessageContext tree as part of constructing Assertion(s)).

org.opensaml.xmlsec.context.SecurityParametersContext

OPTIONAL: Required (with populated SignatureSigningParameters only) if outbound SAML protocol message is to be signed (either XML signature or simple signature types). Not required otherwise.

org.opensaml.soap.messaging.context.SOAP11Context

OPTIONAL: only used with a SOAP 1.1 MessageEncoder
Can be populated with explicitly-constructed Envelope, e.g. to support header usage. If not populated, empty Envelope automatically populated by SOAP MessageDecoder#prepareContext() for use by SOAP binding-specific MessageHandlers.