| D. McAdams | |
| Amazon | |
| March 9, 2020 |
FastFed Basic SAML Profile 1.0 - draft 02
fastfed-saml-1_0
This specification defines the requirements to implement the FastFed Basic SAML Profile.
This specification defines the functionality which a provider must implement to satisfy the Basic SAMLProfile for FastFed.
It consists of the following extensions to the FastFed Core specification:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
In the .txt version of this specification, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. In the HTML version of this specification, values to be taken literally are indicated by the use of this fixed-width font.
This FastFed Profile uses the terminology defined in Section 1.2 of the FastFed Core specification.
When using the SAML protocol, the FastFed Identity Provider and Application Provider have various responsibilities to comply with the protocol.
The Identity Provider fulfills the role of a SAML Identity Provider. It has a responsibility to host a SAML Metadata file as described in Section 5.1.
The Application Provider fulfills the role of a SAML Application Provider. It has a responsibility to host a SAML Metadata file as described in Section 5.2
This specification extends the FastFed Core handshake messages with the additional attributes necessary for each party to fulfill their respective obligations under SAML.
This specification extends the FastFed Core Provider Metadata (Section 3.3.1) with the following value for authentication_profiles:
The following is a non-normative example of Provider Metadata showing the usage of the value:
{
"application_provider": {
"capabilities": {
"authentication_profiles": ["urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic"],
...
}
This specification extends the Application Provider Metadata defined in Section 3.3.8 of FastFed Core with an additional member having the name:
"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic".
The value of the element is a structure containing the following members:
The following is a non-normative example of Application Provider Metadata with the profile extensions:
{
"application_provider": {
"entity_id": "https://tenant-67890.app.example.com/"
"provider_domain": "example.com",
"provider_contact_information": {
"organization": "Example Inc.",
"phone": "+1-800-555-5555",
"email": "support@example.com"
},
"display_settings": {
"display_name": "Example Application Provider",
"logo_uri": "https://app.example.com/images/logo.png",
"icon_uri": "https://app.example.com/images/icon.png",
"license": "https://openid.net/intellectual-property/licenses/fastfed/1.0/"
}
"capabilities": {
"provisioning_profiles": [
"urn:ietf:params:fastfed:1.0:provisioning:saml:2.0:basic"
],
"schema_grammars": [
"urn:ietf:params:fastfed:1:0:schemas:scim:2.0"
],
"signing_alg_values_supported": [
"ES512",
"RS256"
]
},
"fastfed_handshake_register_uri": "https://tenant-67890.app.example.com/fastfed/register",
"urn:ietf:params:fastfed:1.0:provisioning:saml:2.0:basic": {
"desired_attributes": {
"urn:ietf:params:fastfed:1:0:schemas:scim:2.0": {
"required_user_attributes": [
"username",
"emails[primary eq true].value"
],
"optional_user_attributes": [
"displayName",
"phoneNumbers[primary eq true].value"
]
}
}
}
}
This specification extends the JWT contents of the FastFed Registration Request (Section 7.2.3.1 of FastFed Core) with an additional member sharing the same name as the profile:
"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic".
The value of the element is a structure with the following members:
The following is a non-normative example of the contents of a registration request message prior to serialization:
{
"iss": "https://tenant-12345.idp.example.com",
"aud": "https://tenant-67890.app.example.com",
"exp": 1234567890,
"schema_grammar": "urn:ietf:params:fastfed:1:0:schemas:scim:2.0",
"authentication_profiles": [
"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic"
],
"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic": {
"saml_metatadata_uri": "https://tenant-12345.idp.example.com/saml-metadata.xml",
}
}
This specification extends the contents of the FastFed Registration Response (Section 7.2.3.3 of FastFed Core) with an additional member sharing the same name as the profile:
"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic".
The value of the element is a structure with the following members:
The following is a non-normative example of the contents of a registration response message:
{
"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:basic": {
"saml_metatadata_uri": "https://tenant-56789.app.example.com/saml-metadata.xml"
"saml_response_attributes": [
"displayName",
"emails[primary eq true].value"
]
}
}
FastFed recommmends SCIM for user schemas. However, neither SAML nor SCIM specify how to represent SCIM attributes in the context of SAML assertions.
This specification fills the gap and defines how FastFed compatible Providers can use the SCIM 2.0 Schema Grammar (Section 3.3.4.1 of FastFed Core) with the SAML 2.0 protocol.
A SAML document contains a Subject element which identifies the authenticated user.
The Subject element MUST contain a NameID with the following properties:
The following is a non-normative example of a SAML Subject:
<saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">babs@example.com</saml:NameID> </saml:Subject>
If users have been pre-provisioned into the Application through mechanisms such as SCIM, the SAML Subject alone can be sufficient to correlate the incoming SAML message with the appropriate pre-existing user. However, there can be circumstances when additional user attributes are necessary.
One such situation occurs when an application is using Just-In-Time provisioning instead of pre-provisioning. In this mode of behavior, the incoming user attributes are used to auto-instantiate a user in the Application.
To support these scenarios, FastFed allows a subset of user attributes to be included in SAML response messages according to the mapping rules below. Any attributes not in the mapping table are only accessible via SCIM provisioning and cannot be included in SAML response messages.
Attributes are requested by populating the member "desired_attributes" in the Application Provider Metadata (Section 3.1.2).
If attributes are requested, and values exist for the user, then the Identity Provider MUST include SAML Attribute elements in the response message with the following properties:
Note: In the table below, SCIM attributes refer to the "User" Resource Schema defined in Section 4.1 of the SCIM Core Specification. Individual members of a JSON structure are referenced in the table using the JSON path syntax defined in Section 3.5.2 of the SCIM Protocol.
| SAML Attribute Name | SCIM Attribute |
|---|---|
| externalId | externalId |
| displayName | displayName |
| givenName | name.givenName |
| familyName | name.familyName |
| middleName | name.middleName |
| emails[primary eq true].value | |
| phoneNumber | phoneNumbers[primary eq true].value |
The following is a non-normative example demonstrating a transformation from a SCIM User to SAML Attributes:
<saml:AttributeStatement>
<saml:Attribute Name="externalId" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">1fc58220-7213-47bb-9161-bbd39ad75937</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="displayName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">Babs Jensen</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="givenName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">Barbara</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="familyName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">Jensen</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="middleName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">Jane</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">bjensen@example.com</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="phoneNumber" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">1-555-555-5555</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
When exposing user information through SAML Attributes, FastFed Identity Providers MUST NOT expose any attributes which were not in the desired_attributes element of the Application Provider Metadata (Section 3.1.2).
Each identity standard defines a set of optional features to enable usage in a wide variety of circumstances.
However, a consequence of the flexibility is that two Providers may find themselves incompabitible despite sharing the same protocols.
To deliver the simplified experience that is the goal of FastFed, it is important that two FastFed-enabled Providers have confidence that they can interoperate when sharing the same protocols.
The following sections describe the subset of the SAML specifications that Providers MUST implement to be compatible with this profile. Providers MAY support additional functionality, but MUST NOT require the additional functionality when configuring federation with another Provider using FastFed specifications.
SAML Requirements for Application Providers:
The Application Provider MAY include the URL-encoded query parameter LoginHint={hint} when initiating an authentication request via the SAML HTTP Redirect binding.
The value is a hint to the Identity Provider about the login identifier the end-user might use to log in. This hint can be known to the Application Provider, for example, if it first asks the end-user for their e-mail address (or other identifier) in order to discover the authentication provider to be used for sign-in. It is RECOMMENDED that the hint value match the value used for discovery.
The use of this parameter is left to the Identity Provider's discretion.
The LoginHint MUST NOT be included in request signature for the HTTP Redirect Binding.
The Identity Provider MUST ignore the LoginHint parameter if the SAML Authentication Request message contains a Subject with an identifier.
The following is a non-normative example of a SAML HTTP Redirect request with a LoginHint:
HTTP/1.1 302 Found Location http://idp.example.com/SAML?LoginHint=bjensen%40example.org&SAMLRequest=[...omitted for brevity...]
While the full SAML specification supports a variety of key types, the FastFed Profile defined herein restricts Providers to only X509 Keys for signing SAML Assertions in Web Browser SSO response messages from the Identity Provider.
FastFed Providers MUST implement automatic rotation of the X509 Certificates. This section describes the interoperability requirements for certificate rotation.
To rotate and publish new SAML signing certificates, the following requirements apply to the Identity Provider:
To consume rotated SAML signing certificates, the following options are available to the Application Provider:
When preemptively querying for updates on a recurring basis, the following requirements apply to the Application Provider:
In all cases of certificate refresh, both on-demand and preemptive, the following requirements apply to the Application Provider:
For SAML security considerations, see SAML Security and Privacy Considerations.
For FastFed security considerations, see Section 8 of FastFed Core.
Pending
The OpenID Community would like to thank the following people for their contributions to this specification:
Copyright (c) 2020 The OpenID Foundation.
The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.
The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.