Appendix D - Encapsulation of Application Layer Attributes in SAML SSO Exchange
Motivation
SAML v2.0 single sign on transactions are able to pass attributes as
an <AttributeStatement> contained in the assertion.
However, the vendor implementations pass these attributes to the
application layer in proprietary ways. Considering the range of flaws
in the proprietary mechanisms, the common denominator that will always
work appears to be string valued attributes that do not contain any
special characters. As of late 2007, both multi-valued and structured
attributes (attributes whose values are XML documents or fragments)
trigger bugs and limitations in various vendor implementations.
Goal
An IdP wants to pass attributes A, B, and C to a custom developed service application (SA) that is behind a service provider (SP) implementation using a vendor product.
Method
When the IdP prepares a SAML assertion, it includes an
<AttributeStatement> with an
<Attribute> (or
<EncryptedAttribute>) element whose Name is:
urn:nzl:govt:ssc:sams:safeb64:NNNN
where NNNN is an attribute name assigned by SSC for use in association with this attribute passing method, and NameFormat is:
urn:oasis:name:tc:SAML:2.0:attrname-format:uri
The content of the attribute MUST be a safebase64 encoding (RFC3548) of a well formed XML document specified by the schema registered for the attribute name (see next section).
Any leading or trailing whitespace is ignored. The safebase64 encoding of the data MUST NOT contain whitespace (such as line breaks).
The SP (which is assumed to be implemented with an immutable vendor product) will consume the SSO assertion, extract the attribute as a single valued string attribute, and pass the string to the Service Application (assumed to be custom developed) in a deployment dependent way.
Registry and extensibility
The following outlines an approach to attribute registration which is expected to be implemented by SSC.
SSC is expected to maintain a registry of assigned attribute names (NNNNs), their intended use, entities who are supposed to use the attribute, and the type of the attribute value. If the type is an XML document, then the root element and XML schema with version should be specified.
The registry will ensure uniqueness of attribute names.
If the schema for the attribute changes, a new attribute name MUST
be issued. Alternately, SSC MAY issue an attribute name of form
"urn:nzl:govt:ssc:sams:safeb64:NNNN:VVV" and delegate
administration of VVV to a delegate (presumably the VVV would be the
version number of the data schema).
To enquire about registration of new attributes, please contact authentication@ssc.govt.nz.
If two parties mutually agree to use this attribute encapsulation
method but do not wish to coordinate the attribute name with SSC, then
the attribute name they choose MUST NOT start by
"urn:nzl:govt:ssc:". However, they are otherwise
encouraged to follow the format and practices defined in this
document.
Example
Assume SSC has assigned attribute
"urn:nzl:govt:ssc:sams:safeb64:example" and designated
that it contain an XML document whose root element is
<e1:Set> and which is further defined by the
following schema:
<schema targetNamespace="urn:egns1">
<element name="Set">
<sequence>
<element name="A" type="xs:string" minOccurs="0"
maxOccurs="unbounded"/>
<element name="B" type="xs:string" minOccurs="0"
maxOccurs="unbounded"/>
<element name="C" type="xs:string" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
</element>
</schema>
The IdP wishes to pass the following attributes
- A: 1
- B: 2
- B: 22
Note that the attribute C is omitted and B is multi-valued. This would be rendered to an XML document according to the schema as follows:
<e1:Set xmlns:e1="urn:egns1">
<e1:A>1</e1:A>
<e1:B>2</e1:B>
<e1:B>22</e1:B>
</e1:Set>
This is safebase64 encoded into following:
PGUxOlNldCB4bWxuczpl-(snip)-vZTE6Qj48L2UxOlNldD4=
Now, the IdP could prepare an assertion with
<AttributeStatement> containing the following
attribute:
<sa:AttributeName="urn:nzl:govt:ssc:sams:safeb64:example1"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<sa:AttributeValue>
PGUxOlNldCB4bWxuczpl-(snip)-vZTE6Qj48L2UxOlNldD4=
</sa:AttributeValue>
</sa:Attribute>
When the SP decodes the SSO assertion, it will extract the attribute and pass to SA the following attribute-value pair:
urn:nzl:govt:ssc:sams:safeb64:example1:PGUxOlNldCB4bWxuczpl-(snip)-
vZTE6Qj48L2UxOlNldD4=
Now the SA application can recover the attributes A, B, (and C if present) using code similar to:
val_b64
=getattr("urn:nzl:govt:ssc:sams:safeb64:example1");
xml = unbase64(val_b64);
//This API also handles safebase64
encoded data
dom = xml_parse(xml);
print "Value A is " $ dom.Set.A;
which will result output 'Value A is 1'. Exactly how the SA extracts the attributes depends on the SA programming environment and the method SP uses to pass the attributes to the SA.
Implementation notes
Implementing the present encapsulation scheme may require adaptation of some existing software. Given that the scheme is relatively simple, this should be straightforward.
On IdP side, attributes that have static values can be stored in the IdP's attribute database in an already encoded form. In this case the IdP software does not require any adaptation. All the work is done when the attribute is provisioned. Given that IdPs tend to be COTS, whereas provisioning systems are usually customised to customer requirements, the adaptation conveniently happens exactly in the component that needs to be customised anyway.
If IdP needs to generate an attribute dynamically, then the IdP software needs to be adapted to this scheme. Assuming the split between COTS SP and custom developed SA, this scheme really only needs to be understood by the SA.
The present system supports both passing single XML structured attribute (in which case NNNN is directly the desired attribute) or a collection, bundled under the NNNN label, of related attributes, which can be simple or structured. This gives a lot of flexibility and scope for agreement at different levels. It would seem advisable to use the bundled method as much as possible as it keeps the top level registrations to minimum. One bundle for each application area to be integrated sounds about right. As system is deployed and we gain further experience, we expect to give better guidance about which attributes should be bundled together.
Identity-related data elements are defined as part of the New Zealand government's e-GIF authentication standards (refer to Data Formats for Identity Records Standard [DFIRS]). The identity-related data elements support the collection, recording and establishing of an individual's identity. The Data Formats for Identity Records Standard is a profiled subset of the OASIS Customer Information Quality v3.0 (CIQ) Specifications under revision at the time of the NZ SAMS publication. CIQ v3.0 includes customer data such as names. These can be used to support data exchange within SAML attributes.
