Home

Dynamic SAML

Submitted by Andreas Åkre Solberg [1] on 18 February, 2010 - 13:07

Dynamic SAML is an approach to completely distributed metadata management.

This draft is far from being completed. Consider it as a presentation of an idea. Feedback is welcome!

1 Requirements notation

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

2 Self-provisioning of SAML Metadata

A dynamic SAML enabled entity MUST have an EntityID equals to an URL where metadata for that entity can be obtained. Access to the URL should be unprotected and metadata should available for retrieval on the URL using a HTTP GET request, and without any query parameters.

The endpoint returning metadata, SHOULD return a content type of application/xml+metadata. The responder may use any common HTTP response code like not found, redirection and internal error, if appropriate.

The root element of the returned metadata MUST be an <md:EntityDescriptor>, and the EntityID attribute of the metadata MUST match the URL.

3 Signing self-provisioned SAML Metadata

The entity that provides metadata MUST embed a X.509 certificate, and it MUST sign the metadata with the same certificate.

Here is an example of such a metadata document.

<EntityDescriptor 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:mdattr="urn:oasis:names:tc:SAML:metadata:attribute"
    entityID="https://idp.example.org">

    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>[snipp]</ds:SignedInfo>
        <ds:SignatureValue>vDoZqiWbgr6Ri....</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>[snipp]</ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>

    <IDPSSODescriptor 
        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">

        <KeyDescriptor>
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:X509Data>
                    <ds:X509Certificate>[snipp]</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </KeyDescriptor>

        <SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
            Location="https://idp.example.org/SSO"/>
    </IDPSSODescriptor>
</EntityDescriptor>

4 Referring to third-party assertions about the entity

Self-asserting metadata would in most use-cases need some extra verification of the entity's federation membership, level of assurance etc. The entity may put in a reference using the <dsaml:ExternalEntityAttributeAuthority> to refer to an authority that may assert additional statements about this entity.

<Extensions>
   <ExternalEntityAttributeAuthority
       xmlns="urn:oasis:names:tc:SAML:metadata:dynamicsaml">
       <AssertingEntity>
           <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
               http://federationX.org
           </NameID>
       </AssertingEntity>
       <RetrievalEndpoint>
           https://federationX.org/?ID=a87s76a5765da76576a57as
       </RetrievalEndpoint>
   </ExternalEntityAttributeAuthority>
</Extensions>

There might be any number of <dsaml:ExternalEntityAttributeAuthority> elements within the <md:Extensions> element within the <md:EntityDescriptor>.

The <dsaml:ExternalEntityAttributeAuthority> MUST include an <dsaml:AssertingEntity> and one or more <dsaml:RetrievalEndpoint>-s. The <dsaml:AssertingEntity> MUST include an <saml:NameID> element where the Format MUST be urn:oasis:names:tc:SAML:2.0:nameid-format:entity. This would be the entityID of the asserting party that would make an assertion targeted on the entity.

The endpoint listed in the <dsaml:RetrievalEndpoint> element MUST be an endpoint that will return an <saml:Assertion> using the SAML URI Binding [SAML2Bind].

The <saml:Assertion> that can be resolved following the ExternalEntityAttributeAuthority reference, MUST have an Issuer matching the <dsaml:AssertingEntity>. The assertion MUST also include a <saml:Subject> referring to the actual entity. The <saml:Subject> MUST also include a <saml:SubjectConfirmation> with a Method of urn:oasis:names:tc:SAML:2.0:cm:holder-of-key and a <saml:SubjectConfirmationData> with an contained <ds:KeyInfo>. The content of the <ds:KeyInfo> MUST contain an X.509 certificate within <ds:X509Data><ds:X509Certificate>. That certificate MUST match the embedded certificate in the processed metadata.

The validity time window of such an assertion SHOULD be limited by using a <saml:Conditions> element with NotBefore and NotOnOrAfter. The time window should be large enough to allow for some caching, but at the same time short enough for some reasonable time out period if the third-party would like to revoke the entity from the federation or similar.

Here is an example of an <saml:Assertion> resolved from an <dsaml:AssertingEntity>:

<saml:Assertion 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    Version="2.0" ID="a87s76a5765da76576a57as"
    IssueInstant="2008-05-27T07:49:23Z">
    <saml:Issuer>http://federationX.org</saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">[snipp]</ds:Signature>

    <saml:Subject>
        <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
            https://idp.example.org
        </NameID>
        <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:holder-of-key">
            <saml:SubjectConfirmationData NotOnOrAfter="2008-05-27T07:54:23Z" >
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate>[snipp]</ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </saml:SubjectConfirmationData>
        </saml:SubjectConfirmation>
    </saml:Subject>

    <saml:Conditions NotBefore="2008-05-27T07:48:53Z" NotOnOrAfter="2008-05-27T07:54:23Z" />

    <saml:AttributeStatement>
        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" 
            Name="urn:mace:feide:attr:federation">
            <saml:AttributeValue xsi:type="xs:string">member</saml:AttributeValue>
        </saml:Attribute>

        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" 
            Name="urn:mace:feide:attr:profiles">
            <saml:AttributeValue xsi:type="xs:string">
                urn:mace:incommon:profiles:saml2:browser-sso:deployment
            </saml:AttributeValue>
            <saml:AttributeValue xsi:type="xs:string">
                urn:oasis:names:tc:SAML:2.0:profiles:metadata-iop
            </saml:AttributeValue>
        </saml:Attribute>

        <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" 
            Name="urn:oasis:names:tc:SAML:attribute:assurance-certification">
            <saml:AttributeValue xsi:type="xs:string">http://federationX.org/assurance/loa2</saml:AttributeValue>
        </saml:Attribute>
    </saml:AttributeStatement>

</saml:Assertion>

5 Processing rules for consuming self-provisioned metadata

The entity that tries to resolve a dynamic SAML entityID (metadata consumer) MUST verify that the EntityID matches the URL where metadata was retrieved from. It also MUST verify the signature, and compare the signing certificate with the embedded certificate in the <md:KeyDescriptor>.

The metadata consumer MAY choose whether or not to resolve the <dsaml:ExternalEntityAttributeAuthority>-s. The consumer will usually only resolve <dsaml:AssertingEntity> that it recognises and trust.

When resolving a <dsaml:ExternalEntityAttributeAuthority> the signature on the assertion MUST be verified, and the certificate in the <saml:SubjectConfirmationData> MUST be compared with the embedded certificate in the metadata. If anything fails during resolving an <dsaml:ExternalEntityAttributeAuthority> the consumer MUST proceed processing metadata as if the <dsaml:ExternalEntityAttributeAuthority> was not included in the metadata. That goes for any types of failures, such as invalid signature, wrong signature, invalid assertion, failure establishing HTTP connection with the endpoints, etc.

6 Dynamic SAML for a Service Provider

A dynamic SAML enabled Service Provider software will automatically create a metadata document, sign it and publish it on the correct endpoint.

Then, a Service Provider administrator may register the entity in a federation, or establish some kind of arrangement with a third party asserter. The result of this process would be that the third party will provide the Service Provider administrator with an EntityID and a URL. The Service Provider Administrator then configures this in the configuration of the Service Provider software. The software then will include a corresponding <dsaml:ExternalEntityAttributeAuthority> referring to that third-party.

7 Acknowledgement

This work is based on, and extending, existing work on Dynamic SAML found here:

These individuals have been involved in that work:

  • Leif Johansson
  • Scott Cantor
  • Ian Young
  • Nate Klingenstein
  • RL "Bob" Morgan

8 Normative References

RFC2119
Bradner, S.,
Key words for use in RFCs to Indicate Requirement Levels,
March 1997.
SAML2Core
OASIS Standard,
Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0,
March 2005.
SAML2Bind
OASIS Standard,
Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0,
March 2005.
SAML2Prof
OASIS Standard,
Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0,
March 2005.
SAML2Meta
OASIS Standard,
Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0,
March 2005.
SAML2Err
OASIS Approved Errata,
SAML V2.0 Errata.