D. McAdams
Amazon
October 7, 2020

FastFed Enterprise SAML Profile 1.0 - draft 03
fastfed-saml-1_0

Abstract

This specification defines the requirements to implement the FastFed Enterprise SAML Profile.


Table of Contents

1. Introduction

This specification defines the functionality which a provider must implement to satisfy the Enterprise SAMLProfile for FastFed.

It consists of the following extensions to the FastFed Core specification:

1.1. Requirements Notation and Conventions

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.

1.2. Terminology

This FastFed Profile uses the terminology defined in Section 1.2 of the FastFed Core specification.

2. Overview

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.

3. Protocol Extensions

3.1. FastFed Metadata

3.1.1. Authentication Profile URN

This specification extends the FastFed Core Provider Metadata (Section 3.3.1) with the following value for authentication_profiles:

urn:ietf:params:fastfed:1.0:authentication:saml:2.0:enterprise
A Provider who includes this URN in their list of capabilities MUST comply with the requirements described in this specification.

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:enterprise"],
   ...
 }

3.1.2. Application Metadata

This specification extends the Application Provider Metadata defined in Section 3.3.9 of FastFed Core with an additional member having the name:

"urn:ietf:params:fastfed:1.0:authentication:saml:2.0:enterprise".

The value of the element is a structure containing the following members:

saml_subject
REQUIRED. A structure describing the attribute to use as the SAML Subject. The format of the structure is a "User Attribute" as defined in Section 3.3.6 of FastFed Core. The usage of the structure in this profile, including contraints upon the contents, is described in Section 4.1.1.
desired_attributes
OPTIONAL. A structure specifying the values to be included in the SAML Attributes. The format of the structure is described in Section 3.3.5 of FastFed Core. The usage of the structure in this profile, including constraints upon the contents, is described in Section 4.1.2.

Groups are not supported by this SAML profile. Therefore, the following MUST be omitted from the desired attributes:

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:enterprise"
       ],
       "schema_grammars": [
         "urn:ietf:params:fastfed:1.0:schemas:scim:2.0"
       ],
       "signing_algorithms": [
         "ES512",
         "RS256"
       ]
     },
     "fastfed_handshake_register_uri": "https://tenant-67890.app.example.com/fastfed/register",

     "urn:ietf:params:fastfed:1.0:provisioning:saml:2.0:enterprise": {
       "saml_subject": {
         "urn:ietf:params:fastfed:1.0:schemas:scim:2.0": 
           "userName"
       },
       "desired_attributes": {
         "urn:ietf:params:fastfed:1.0:schemas:scim:2.0": {
           "required_user_attributes": [
             "displayName"
           ],
           "optional_user_attributes": [
             "phoneNumbers[primary eq true].value"
           ]
         }
      }
   }
 }

3.2. FastFed Handshake

3.2.1. FastFed Registration Request

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:enterprise".

The value of the element is a structure with the following members:

saml_metadata_uri
REQUIRED. Contains the URL of the Identity Provider's SAML Metadata document.

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,
   "authentication_profiles": [
     "urn:ietf:params:fastfed:1.0:authentication:saml:2.0:enterprise"
   ],
   "urn:ietf:params:fastfed:1.0:authentication:saml:2.0:enterprise": {
     "saml_metadata_uri": "https://tenant-12345.idp.example.com/saml-metadata.xml"
   }
 }

3.2.2. FastFed Registration Response

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:enterprise".

The value of the element is a structure with the following members:

saml_metadata_uri
REQUIRED. Contains the URL of the Application Provider's SAML Metadata document.

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:enterprise": {
     "saml_metadata_uri": "https://tenant-56789.app.example.com/saml-metadata.xml"
   }
 }

4. Schema Binding

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.

4.1. SCIM-to-SAML Attribute Mapping

4.1.1. SAML Subject

A SAML Response document contains a Subject element which identifies the authenticated user.

The Application Provider declares the attribute to populate in the SAML Subject via the saml_subject element in Section 3.1.2

The value of the saml_subject MUST be one of the SCIM Attributes in the table below.

Note: In the table, 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.

SCIM Attribute SAML NameID Format
externalId urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
userName urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
emails[primary eq true].value urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

As a reference to implementors, the following considerations can be taken into account when choosing a SAML subject:

When generating a SAML Response, the Identity Provider MUST populate the SAML Subject with a NameID containing the attribute requested by the Application Provider, and the associated NameID Format from the table above.

The Identity Provider MUST be able to provide a value of externalId and userName for all end-users. Email address is optional.

If a value for an optional attribute is not defined for an end-user, the Identity Provider MUST NOT perform any authentication activity into the Application Provider for the affected end-user. To assist with diagnostics, the Identity Provider SHOULD signal to the end-user that the attribute is missing and is required by the Application. The means of doing so are outside the scope of the specification, but could include displaying an informative error message when the end-user attempts to authenticate into the application, or making error logs available to the administrators of the Identity Provider.

The following is a non-normative example of the use of "externalId" as the SAML Subject:

 <saml:Subject>
   <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">1fc58220-7213-47bb-9161-bbd39ad75937</saml:NameID>
 </saml:Subject>

The following is a non-normative example of the use of "userName" as the SAML Subject:

  <saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified">bjensen</saml:NameID>
  </saml:Subject>

The following is a non-normative example of the use of "email[primary eq true].value" as the SAML Subject:

                                                                                          
 <saml:Subject>
   <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress">babs@example.com</saml:NameID>               
 </saml:Subject>

4.1.2. SAML Attributes

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.

SCIM Attribute SAML Attribute Name
externalId externalId
userName userName
displayName displayName
name.givenName givenName
name.familyName familyName
name.middleName middleName
emails[primary eq true].value email
phoneNumbers[primary eq true].value phoneNumber

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="userName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml:AttributeValue xsi:type="xs:string">bjensen</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>

4.2. Privacy Considerations

When exposing user information through SAML Attributes, FastFed Identity Providers MUST NOT expose any attributes which were not in the desired_attributes or saml_subject elements of the Application Provider Metadata (Section 3.1.2).

5. Interoperability Requirements

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.

5.1. Identity Provider Requirements

5.2. Application Provider Requirements

SAML Requirements for Application Providers:

5.3. Login Hint

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...]

5.4. Certificate Rotation

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.

5.4.1. Certificate Rotation Requirements for an Identity Provider

To rotate and publish new SAML signing certificates, the following requirements apply to the Identity Provider:

5.4.2. Certificate Rotation Requirements for an Application 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:

6. Security Considerations

For SAML security considerations, see SAML Security and Privacy Considerations.

For FastFed security considerations, see Section 8 of FastFed Core.

7. IANA Considerations

Pending

8. Normative References

[FastFed.Core] McAdams, K., "FastFed Core 1.0", October 2020.
[FastFedProfile.EnterpriseSCIM] McAdams, K., "FastFed Enterprise SCIM Profile 1.0", October 2020.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, June 1999.
[RFC7643] Hunt, P., Grizzle, K., Wahlstroem, E. and C. Mortimore, "System for Cross-domain Identity Management: Core Schema", RFC 7643, DOI 10.17487/RFC7643, September 2015.
[RFC7644] Hunt, P., Grizzle, K., Ansari, M., Wahlstroem, E. and C. Mortimore, "System for Cross-domain Identity Management: Protocol", RFC 7644, DOI 10.17487/RFC7644, September 2015.
[SAML.Interoperability] Cantor, S., Kemp, J., Philpott, R. and E. Maler, "SAML V2.0 Metadata Interoperability Profile Version 1.0", August 2009.
[SAML.Metadata] Cantor, S., Moreh, J., Philpott, R. and E. Maler, "Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005.
[SAML.Profiles] Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R. and E. Maler, "Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0"", March 2005.
[SAML.SecurityConsiderations] Hirsch, F., Philpott, R. and E. Maler, "Security and Privacy Considerations for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005.

Appendix A. Acknowledgements

The OpenID Community would like to thank the following people for their contributions to this specification:

Appendix B. Notices

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.

Author's Address

Darin K. McAdams Amazon EMail: darinm@amazon.com