Page Comparison

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 boxesAdobe Creative Cloud service (helpfully called "Adobe SSO" in their documentation and also referred to as "Adobe Experience" and "Adobe Target"), is used to offer access to the Adobe suite of software products.   Many organisations are now being encouraged to use their SAML integration.

Their documentation for Shibboleth IdP can be found at https://helpx.adobe.com/enterprise/kb/configure-shibboleth-with-adobe-sso.html.  However, it  recommends changing much of the default NameID configuration, which would be unacceptable to an already operational IdP, and also configuring and releasing additional attributes using non-standard names which isn't required.

The Adobe service is provided via a SAML IdP/SP Proxy (Okta), it is the Okta SP that you are integrating with.

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.The Service Provider does not consume an Identity Provider Metadata file and it must be configured using the Adobe Admin Console - https://adminconsole.adobe.com/enterprise. 

• IdP Certificate - It does not support SAML encryption, but it does support SAML signature validation, therefore you must provide your SAML signing certificate (you may only have one if you use it for both purposes)
• IdP Binding - set to Redirect
• User Login Setting - This will come down to your individual deployment.   Many may choose to use Email address or another attribute.
• IdP Issuer - is the entityID of your IdP
• IdP Login URL - this is your HTTP-Redirect binding (the Location shown in your IdP metadata under  SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect")

Service Provider Metadata

The Service Provider provides metadata to be consumed by your Identity Provider is not semantically correct.   This is evident in the Adobe documentation where it suggests a number of modifications.  Issues with the SP metadata are as follows;

• It suggests you change AuthnRequestsSigned and WantAsssertionsSigned from true to false
• It suggests you remove the NameIDFormats that it doesn't support, and add the one that it does.
• It provides a signing key which only has 1024-bits, but never signs an AuthnRequest so a KeyDescriptor element is not required.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor entityID="https://www.okta.com/saml2/service-provider/xxxxxxxxxxxxxxxxxxxx" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://adbe-yyyyyyyyyyyyyyyyyyyyyyyy-yyyy-prd.okta.com/auth/saml20/accauthlinktest" index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Profile Requirements

• Supports signed responses, which is the Shibboleth default.
• Encryption is not supported and thus has to be disabled.

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 requireddont signedsupport assertionsencryption butof don'tdata indicate that in their metadatato them. -->
		<bean p:id="example.SignAssertionsOnly"
      <bean parent="RelyingPartyByName">
			<constructor-arg name="relyingPartyIds">
				<list>
					<value>https c:relyingPartyIds="https://spwww.exampleokta.org/shibboleth</value>
				</list>
			</constructor-arg>
			com/saml2/service-provider/xxxxxxxxxxxxxxxxxxxx">
          <property name="profileConfigurations">
				<list>
					
              <list>
                  <bean parent="SAML2.SSO" p:signAssertionsencryptAssertions="true" p:signResponses="false" />
					<bean parent="SAML2.Logout" />
				</list>
			</property>
		</bean>
              </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)Account provisioning is via the Adobe Admin Console - https://adminconsole.adobe.com/enterprise.  Other methods exist such as via an API - https://adobe-apiplatform.github.io/umapi-documentation/en/UM_Authentication.html

NameID Requirements

The SP requires a NameID either in the format of urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress  or in another format, cf. "User Login Setting" when configuring the SP in the admin console mentioned above.

Other more stable identifiers and attributes could be used over and above email address, such as pairwise-id / subject-id attribute, eduPersonPrincipalName, uid or sAMAccountName, that would require a different configuration to that listed in the examples here.  This will link into what can be configured in the Account Provisioning above and the User Login Setting in the Adobe Admin Console.

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>

Attribute Requirements

In addition to the mail attribute and NameID the Adobe documentation suggests that attributes with the name FirstName, LastName and Email are required.   However, the SP does support the follow standard attributes with NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" out of the box:

• givenName (urn:oid:2.5.4.42)
• sn (urn:oid:2.5.4.4)
• mail (urn:oid:0.9.2342.19200300.100.1.3)

Example Shibboleth Configuration

The following is an example attribute-filter configuration

    <!-- mailAdobe Cloud onlySP -->
    <AttributeFilterPolicy id="mailOnlyAdobeCloudSP">
        <PolicyRequirementRule xsi:type="Requester" value="https://spwww.example.org/shibbolethokta.com/saml2/service-provider/xxxxxxxxxxxxxxxxxxxx" />
        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="givenName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="mail" permitAny="truesn">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
     </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

...

Note an example attribute-resolver configuration is not provided here, but configuration might be required.   This should be a fairly simple attribute to configure given it will in most cases map to the equivalent LDAP attribute.