AdobeCloudIntegrationGuide

This is a template for an integration guide for a SAML-supporting application. Typically these are mostly made up of corrections and gap-filling to the usually inaccurate or incomplete SAML technical documentation provided by applications or vendors, along with examples of how to configure the IdP to support whatever special requirements may exist.

The following sections may not always apply to a given application, but many usually will. Most of these topics are not specific to Shibboleth, and some won't even be about SAML, but there are often "wider" considerations such as provisioning that have to be considered when planning the rest.

Place any links to "real" documentation in the appropriate places if worthwhile.

If there are "unknowns" or open questions to highlight, use a blockquote, like this.

Most of the actual text and examples in this template should not appear in the final documents, but please keep the headings and the tip/warning boxes.

Identity Provider Metadata

Use this section to describe how/whether the service handles provisioning of IdP technical details and trust to the service/application.

Include any unusual requirements that would cause integration problems, such as an inability to support a URN-style entityID, any unusual certificate requirements such as algorithms, lifetimes, or commercial certification, etc.

Recommend that this be divided into these broad categories:

• Third-Party Metadata (i.e. InCommon)
• Self-Service (you enter your IdP information into the SP system)
• Manual ("just send us a link or an email" or "we don't do metadata, send us your certificate and SSO URL")

Include any caveats to the categorization, such as "they can load InCommon's metadata or load from a link, but won't update it".

If they use made-up terminology for referring to things that would be in metadata, define that terminology.

Service Provider Metadata

Use this section to describe how/whether the service handles provisioning of SP technical details and trust to the IdP.

Include details such as the "style" of service definition (i.e., a single SP for all customers, an SP-per customer, customer-specific endpoints, etc.) and any details such as use of commercial/short-lived certificates for signing or encryption.

Recommend that this be divided into these broad categories:

• Third-Party Metadata (i.e. InCommon)
• First-Party Metadata (a signed or at least hosted document maintained by the vendor)
• Manual ("here's our metadata" or "we don't do metadata, here's our SAML URL")

Include any caveats to the categorization, such as "they register via InCommon but forget to maintain it" or "they regularly roll certificates in a haphhazard way".

If they use made-up terminology for referring to things that would be in metadata, define that terminology.

Profile Requirements

Use this section to describe any specific requirements known about the service's basic interoperation of SAML SSO, including but not limited to:

• Requiring signed responses (Shibboleth's default)  vs. signed assertions.
• Requiring assertion encryption, supporting encryption, not supporting encryption, and/or whether encryption can be turned on or off without manual intervention.
• Any failure to support common signing/encryption algorithms.
• Anything else general to watch for (e.g., bugs in how messages are transmitted or received, or requirements for special Audience conditions)

In general, anything (excepting perhaps NameID Format(s)) that you have to configure in relying-party.xml should get a mention here unless it's a local-only need.

Example Shibboleth Configuration

Describe ways to account for any special requirements noted above. Could include examples of relying-party.xml changes or additions, or other suggestions in rare situations.

	<!-- Container for any overrides you want to add. -->

	<util:list id="shibboleth.RelyingPartyOverrides">

		<!-- other overrides... -->

		<!-- SPs that required signed assertions but don't indicate that in their metadata. -->
		<bean p:id="example.SignAssertionsOnly" parent="RelyingPartyByName">
			<constructor-arg name="relyingPartyIds">
				<list>
					<value>https://sp.example.org/shibboleth</value>
				</list>
			</constructor-arg>
			<property name="profileConfigurations">
				<list>
					<bean parent="SAML2.SSO" p:signAssertions="true" p:signResponses="false" />
					<bean parent="SAML2.Logout" />
				</list>
			</property>
		</bean>

	</util:list>

Account Provisioning

Use this section to outline in general terms (or link to specific documentation) on account provisioning. Details optional, but a general description of assumptions: batch? just-in-time? kind of data generally supplied? limitations on account identifiers?

This is usually needed to motivate/guide the decisions around the data required to pass in SAML.

NameID Requirements

Most commercial applications are oblivious or at least very limited in the use of SAML Attributes, and will expect to receive the "key" to lookup a user account in the NameID element. Describe any known requirements or limitations:

• Required?
• Used if present?
• Ignored?

If required or supported, what exactly does the NameID need to contain and what Format constant must be used? Don't guess. Don't assume. If you don't know for sure, then document working approaches as examples, but be clear that it may not be the only working solution.

Highlight any errors by the vendor (e.g., requiring a particular Format but misusing it such that the data required can't comply with the Format's requirements, causing problems for other integrations).

Example Shibboleth Configuration

To limit variance, please limit examples to the V3-supplied mechanism for generating NameID values, rather than the legacy approach of encoding attributes inside the Attribute Resolver, so typically will involve examples from saml-nameid.xml and often from attribute-filter.xml.

There are only three ways of triggering the selection of the right Format at runtime:

• The SP requests it (very rare)
• The SP's metadata contains a <NameIDFormat> element
• Use of nameIDFormatPrecedence in relying-party.xml

If the SP's metadata is manually supplied to the IdP, you should indicate that the metadata should be modified to carry the required <NameIDFormat>. If not, an example from relying-party.xml should be shown.

You are encouraged to avoid documenting the use of the Attribute Resolver itself to produce the data to be sent, as this will of necessity vary significantly by site, and gets in the way of the point: how to generate the NameID. Just document any assumptions (e.g., an attribute is produced called mail that contains the user's email address).

	<!-- SAML 2 NameID Generation -->
	<util:list id="shibboleth.SAML2NameIDGenerators">

		<ref bean="shibboleth.SAML2TransientGenerator" />

		<!--
		<ref bean="shibboleth.SAML2PersistentGenerator" />
		-->

		<!--
		Add custom support for email-based NameID, assumes you've released
		the source attribute (mail) to any SPs expecting to get it.
		-->
		<bean parent="shibboleth.SAML2AttributeSourcedGenerator"
			p:format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
			p:attributeSourceIds="#{ {'mail'} }" />

	</util:list>

    <!-- mail only -->
    <AttributeFilterPolicy id="mailOnly">
        <PolicyRequirementRule xsi:type="Requester" value="https://sp.example.org/shibboleth" />

        <AttributeRule attributeID="mail" permitAny="true" />
    </AttributeFilterPolicy>

Attribute Requirements

In cases where SAML Attributes are required or supported, document those requirements here. Important details per-attribute include:

• Name and NameFormat
• Single- vs. Multi-valued
• Value syntax/limitations
• Required vs optional

Another detail to capture, if known, is whether the SP supports (or not) the use of xsi:type within the <AttributeValue> element. V3 defaults to omitting it through an explicit setting, but most legacy resolver configurations omit the setting and will emit the declaration. Testing by an IdP would reveal whether an SP supports omitting this, and most will.

Example Shibboleth Configuration

Most resolver examples are superfluous, as they illustrate local attribute requirements more than anything to do with SPs, but in cases where an SP requires non-standard attributes, it's acceptable to include examples that might demonstrate how to attach conditions to <AttributeEncoder> plugins to limit their use to an SP.