MessageContext Subcontext Usage: SAML 1 and SAML 2

Owned by Scott Cantor
Mar 04, 2021
4 min read

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.