D. McAdams | |
Amazon | |
October 15, 2017 |
FastFed 1.0 - draft 00
fastfed-1_0
FastFed simplifies the administrative effort to configure identity federation between an identity provider and a hosted application. The specification defines metadata documents, APIs, and flows to enable an administrator to quickly connect two providers that support common standards such as OpenID Connect, SAML, and SCIM, and allows configuration changes to be communicated directly between the identity provider and hosted application on a recurring basis.
Despite the existence of well-established standards, identity federation remains difficult to configure and maintain.
One source of difficulty arises because the existing identity standards each solve a portion of the federation ecosystem, such as authentication, schema definition, or end-user information exchange; but without a clear recommendation on how to assemble the pieces into a whole. As a result, each hosted application may choose to assemble standards in different ways or even ignore them, such as by declaring their own user attribute schema. The resulting impact is that each hosted application can be an architectural one-off that an administrator must study and understand before beginning to configure a federation relationship.
Another area of difficulty arises because there is no standard mechanism for an identity provider and application provider to directly exchange metadata required by existing standards. Instead, a human administrator must copy-and-paste information between the two providers. This is typically done by opening a web page for each provider and following online instructions to copy information between them. Copy-and-paste errors, overlooked steps, or incomplete documentation can result in non-functional configuration that is difficult to debug.
Finally, a working configuration may cease to function when the configuration becomes stale, such as when certificates expire. The lack of a direct communication channel between the identity provider and application provider requires that human administrators remember to periodically refresh the configuration and rotate certificates. In some implementations, planned refresh activities such as certificate rotation can temporarily break the ability for federated users to sign-in to the hosted application.
As a result of these challenges, administrators find it necessary to acquire domain expertise in the identity standards and spend significant time configuring, debugging, and maintaining the federations.
The goal of FastFed is to simplify the administrator experience. An ecosystem of FastFed-enabled providers will enable administrators to instantiate new federation relationships with a few clicks in a web-based workflow, and without needing to understand the underlying technologies.
To encourage adoption and minimize intrusive changes, FastFed does not alter existing standards nor break existing implementations. Rather, FastFed aims to make existing standards easier to adopt.
To enable this, FastFed defines additional metadata documents, APIs, and flows that allow an administrator to quickly connect two providers that support the common identity standards. In addition, FastFed defines interoperability profiles which describe the subset of existing standards which must be implemented for a Provider to label themselves as FastFed Compatible.
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.
FastFed acts as a high-level metadata description layer which references many different underlying standards. To avoid confusion of terminology, the FastFed specification will explicitly reference the relevent standards inline when using terminology from those standards.
In addition, this specification defines the following terms. When used in this document, the terms refer to the definitions here and not any of terminology from underlying standards:
The following abbreviations are used in this specification:
This section provides an introductory overview of the key concepts in FastFed. The following concepts are explored:
FastFed uses Metadata documents to enable Identity Providers and Application Providers to programmatically discover the capabilities of one other and exchange any configuration necessary to enable federation.
FastFed Metadata is split into two distinct document types:
Provider Metadata describes the capabilities and configurations of the Provider.
The primary purpose of Provider Metadata is to bootstrap the FastFed Handshake (Section 7). To do so, Provider Metadata describes the capabilities of providers so that compatibility can be evaluated when initiating the handshake; e.g. if an Application Provider requires SAML, the Identity Provider must also support SAML.
Provider Metadata also specifies the endpoints for performing the FastFed Handshake, plus optional values such as icon images that can aesthetically improve the handshake flows seen by Administrators.
Provider Metadata is segmented into blocks for identity_provider and application_provider. An entity can define one, or both blocks, depending on the roles they are capable of performing.
The following is a non-normative example of Provider Metadata:
{ "identity_provider": { "provider_uri": "https://idp.example.com", "name": "My Identity Provider", "icons": { "large_icon_uri": "https://idp.example.com/images/tile.png", "small_icon_uri": "https://idp.example.com/images/favicon.png" } capabilities: { "sso_protocols_supported": ["OIDC","SAML"], "user_schemas_supported": ["urn:ietf:params:scim:schemas:core:2.0:User"], "user_provisioning_modes_supported": ["SCIM","JIT","Custom","NoProvisioning"], "provider_authz_schemes_supported": ["OAuth"] } "fastfed_handshake_start_uri": "https://idp.example.com/fastfed/start", "fastfed_handshake_finish_uri": "https://idp.example.com/fastfed/finish" }
Instance Metadata describes the configuration to be used when instantiating a specific instance of a federated relationship between the tenant of an Identity Provider and the tenant of an Application Provider. For example, if SAML is chosen as the SSO protocol, the Instance Metadata document will specify the URL of the SAML Metadata files, which may themselves include tenant-specific customizations such as vanity sign-in URLs.
Instance Metadata documents are exchanged during the Fast Fed Handshake, and are the means by which the Providers are able to programmatically share information without requiring an Administrator to copy-and-paste configuration between the two parties.
The following is a non-normative examples of Instance Metadata for an Identity Provider:
{ "identity_provider_instance": { "tenant_id": "k2lini4cj509ut09cj0jcjwee9gj0jeg", "sso_protocol": "SAML", "saml_metadata_uri": "https://tenant12345.example.com/saml-metadata.xml", "user_schema": "urn:ietf:params:scim:schemas:core:2.0:User", "user_provisioning_mode": "JIT" "provider_authz_scheme": "OAuth", "oauth_token_endpoint": "https://tenant12345.example.com/token", }
Endpoints describe the semantics for exchanging information between the Providers.
FastFed defines two Endpoints for retrieving Metadata documents:
And, three Endpoints for the FastFed Handshake
The Provider Metadata Endpoint, also referred to as the "FastFed URL", vends the Provider Metadata. This URL is the only attribute that Administrators need to copy and paste in order to initiate the FastFed Handshake flows.
Providers typically advertise their FastFed URL in their SSO documentation. In addition, catalogs of pre-configured FastFed URLs may further simplify the Administrator experience. For example, an Identity Provider may offer a catalog of Application Providers in which the FastFed URL for each Application Provider has been pre-configured.
All other FastFed Endpoints are either discoverable from the Provider Metadata document, or exchanged as part of the FastFed Handshake flows. From an Administrator perspective, these other Endpoints may be regarded as an implementation detail and not part of their visible experience.
The FastFed Handshake flow is the means by which Metadata documents are exchanged and a federation relationship becomes established.
The FastFed Handshake is initiated by sending a request to the Identity Provider with a parameter containing the FastFed URL of the Application Provider.
The handshake may be initiated by the Identity Provider or the Application Provider. The flow is the same for each, only varying by whether the Handshake endpoint is invoked by the Identity Provider (by sending a request to itself) or by the Application Provider.
Upon receiving a handshake initiation request, the abstract flow follows these steps:
+----------+ +----------------+ .----. | User |<-----(1)---->| | |.____.| | Agent | | Identity |--(9)-->| Data | | +---|------(3)-----| Provider | | Store| | | +-|------------->| | "----" | | | | +----------------+ | | | | | ^ | | | | | | | | | | | | | | | | | | | (2) (5) (8) | | | | | | | | | | | | | | | | | | V | V | | | | +----------------+ .----. | | +-|------(7)-----| | |.____.| | +---|------------->| Application |--(6)-->| Data | | | | Provider | | Store| | |<-----(4)---->| | "----" +----------+ +----------------+ Figure 1: Abstract Handshake Flow
For privacy reasons, Multi-Tenant Providers may be unwilling or prohibited from exposing tenant data to unauthorized audiences. In some cases, simply acknowledging the existence of a tenant may be prohibited. Such information can only be released with explicit authorization from the tenant.
To enable these privacy controls, FastFed includes the ability to select an authorization scheme for calls between Providers.
One scheme defined in this specificatin uses OAuth [RFC6749]. The OAuth tokens are exchanged between Providers during the FastFed Handshake. The OAuth tokens demonstrate that an authorized Administrator has approved access to the tenant information. The tokens can be used to gate access to any resource that is used when configuring and maintaining a federation relationship. (See Section 8.1)
Federated Identity Management requires a common, agreed upon schema to describe user information, plus a mechanism to transmit user information across organizational boundaries.
While previous standards each define pieces of the solution, they lack guidance on assembling the pieces into an end-to-end flow. For example, the SCIM specification defines a User schema, but does not specify how to bind the schema into SAML or OIDC assertions. Alternatively, OIDC defines a schema for Standard Claims and a User Info Endpoint to retrieve them. However, the claims are weighted toward describing social media users and may lack attributes necessary to describe users from the enterprise sector or educational sector. In addition, the OIDC claims are bound to the OIDC protocol and it is unspecified how the same schema could be reused with an Application Provider that requires SAML instead of OIDC. Finally, it is not uncommon for an Application Provider to completely ignore all preexisting standards and define their own schema which federation partners must adhere to in SAML or OIDC messages.
Administrators bear the burden of this inconsistency. The lack of agreement amongst federation participants requires an Administrator to bridge the divide by defining schema transformation rules that map user attributes from an Identity Provider format into an Application Provider format. This mapping is unique for each Application Provider and must be defined for each federation. Understanding and defining these transformation rules is a major contributor to the friction of adopting federation.
To eliminate the burden from Administrators, Providers must agree upon a shared vocabulary for user attributes. This is accomplished by requiring both parties to share a common schema for use within the FastFed Metadata documents. This schema serves as a common lingua franca for communicating the user attributes to be exchanged.
FastFed also provides an Attribute Mapping capability so that Application Providers may declare how they would like user attributes communicated to them as part of a particular SSO protocol. By using the Attribute Mappings, a Provider can become FastFed-enabled while continuing to operate an existing federation endpoint that relies on non-standard schemas. This shifts the burden for attribute mapping from the Administrator to the Application Provider, and further improves the situation by only asking the Application Provider to define the mapping once, in the Metadata, where it can be reused across all FastFed-enabled relationships.
FastFed Metadata allows Providers to declare the schemas they understand. Providers should choose schemas that are likely to be shared by federation partners. The lack of a common schema between an Identity Provider and Application Provider will be regarded as an incompatibility and the FastFed handshake will be halted before completion.
FastFed recommends the use of the SCIM User Resource Schema and the SCIM Enterprise User Schema Extension. This specification uses SCIM in examples and references. However, other schemas may be used.
The following is a non-normative example showing a snippet from a Provider Metadata with a list of schemas understood by an Identity Provider:
{ "identity_provider": { capabilities: { ... "user_schemas_supported": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:enterprise:2.0:User" ], } ...
User schemas can potentially contain many pieces of information about a user. For example, the SCIM User Resource defines more than 25 different attribute types, some containing sensitive user information. It is typically unnecessary to share all user information with a hosted application. In recognition of this, FastFed provides a mechanism for Application Providers to define the subset of attributes needed to use the application.
Identity Providers display the list of requested attributes during the FastFed Handshake so that Administrators may review and approve the attributes to be released.
The following is a non-normative example showing a snippet of Instance Metadata for an Application Provider who desires 3 attributes from a SCIM User Resource.
{ "application_provider_instance": { ... "user_schema": "urn:ietf:params:scim:schemas:core:2.0:User", "desired_user_attributes": [ {"required": ["username", "emails[primary eq true]"], "optional": ["name.formatted"] } ], ...
Attribute Mapping is the process of copying user attributes from a schema into the specific structure required of an SSO protocol such as SAML or OIDC. This may include relabeling the name of the attribute.
Application Providers declare how they would like schema information transmitted to them for a given SSO protocol. Identity Providers are responsible for applying the mapping to outgoing SSO messages.
FastFed specifies mappings for SCIM-to-SAML and SCIM-to-OIDC. Application Providers may copy the reference examples, or define a custom mapping. Custom mappings allow an Application Provider to become FastFed compliant even if their SSO endpoint uses a non-standard format for user attributes.
The following is a non-normative example showing a snippet of Instance Metadata which contains a SCIM-to-SAML attribute mapping:
{ "application_provider_instance": { ... "sso_protocol": "SAML", "user_schema": "urn:ietf:params:scim:schemas:core:2.0:User", "user_attribute_mapping": { "mapping_syntax": "simple_scim_to_saml", "mapping_rules": { "name_id": { "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", "value": "id", }, "attributes": [ {"name": "name", "value": "displayName" }, {"name": "email", "value": "email[primary eq true].value" }, {"name": "groups", "value": "groups.displayName" } ] }, ...
User Provisioning is the process of creating user accounts in the hosted application. Common patterns include the following:
FastFed Metadata enables Providers to describe their provisioning requirements and capabilities. See Section 4.3.1 and Section 4.4.1.
Some federation information needs to be updated on recurring basis. FastFed specifies the following recurring activities:
See section Section 10 for details.
The following is a non-normative example showing a snippet of Provider Metadata describing the supported recurring activities:
{ "identity_provider": { ... "recurring_activities": { "icon_refresh: ["publish", "consume"], "saml_certificate_rotation": ["publish"] "oidc_key_rotation": ["publish"] }, ...
All FastFed Metadata is represented in JSON format. Property names and string values are represented as JSON strings. Numerical values are represented as JSON numbers. Boolean values are represented as JSON Booleans. Lists are represented as JSON arrays. Complex structures are represented as JSON objects. Omitted properties and properties with no value SHOULD be omitted from the object and not represented by a JSON null value.
Human-readable Metadata values and Metadata values that reference human-readable values MAY be represented in multiple languages and scripts. For example, values such as client_name and large_icon_uri might have multiple locale-specific values for some Providers.
To specify the languages and scripts, BCP47 [RFC5646] language tags are added to Client Metadata member names, delimited by a # character.
If such a human-readable field is sent without a language tag, parties using it MUST NOT make any assumptions about the language, character set, or script of the string value, and the string value MUST be used as-is wherever it is presented in a user interface. To facilitate interoperability, it is RECOMMENDED that any human-readable fields sent without language tags contain values suitable for display on a wide variety of systems.
Provider Metadata enables Providers to advertise their capabilities and evaluate compatibility with other Providers by comparing capabilities. The Provider Metadata also contains the endpoint configuration needed to perform the FastFed Handshake.
Provider Metadata is a structure with the following top-level attributes:
If a single Provider is capable of acting as both an Identity Provider and an Application Provider, the Provider Metadata MAY contain both parts.
If neither part is specified, the FastFed Handshake will halt as per Section 7.1.4.
Capabilities describe the supported behaviors of a Provider. They are included in the Metatdata for both Identity Providers and Application Providers and are the primary tool to evaluate if two Providers are compatible with one another.
Capabilities are represented as a structure with the following attributes:
When one schema extends another schema, Providers MUST list both schemas if they are capable of using either the extended or the base schema when integrating with federation partners. If the extended schema is mandatory, Providers MUST list only the extended schema.
Common Provider Metadata describes properties that are shared by both Identity Providers and Application Providers.
Common Provider Metadata is a structure with the following values:
Identity Provider Metadata is a structure that includes all the elements defined in Common Provider Metadata, plus the following additional elements:
Application Provider Metadata is a structure that includes all the elements defined in Common Provider Metadata, plus the following additional elements:
Instance Metadata represents the specific capabilities chosen by a Provider to use when establishing a federation relationship with another Provider.
Instance Metadata is a structure with the following top-level attributes:
A Provider MUST include one of either the identity_provider or application_provider elements, corresponding to the role it is playing in the federation relationship. A Provider MUST NOT include both elements.
Common Instance Metadata describes properties that are shared by both Identity Providers and Application Providers.
Common Instance Metadata contains the following values:
Identity Provider Instance Metadata is a structure that includes all the elements defined in Common Instance Metadata.
No additional elements are added to the Identity Provider Metadata.
Application Provider Instance Metadata is a structure that includes all the elements defined in Common Instance Metadata, plus the following attributes:
This section describes the additional values to be specified in Metadata documents when using certain protocols.
When using the SAML SSO protocol, the Common Instance Metadata structure is extended with the following attributes:
The following is a non-normative example showing a snippet of Instance Metadata for an Identity Provider using SAML:
"identity_provider_instance": { "tenant_id": "k2lini4cj509ut09cj0jcjwee9gj0jeg", "sso_protocol": "SAML", "saml_metadata_uri": "https://tenant12345.example.com/saml-metadata.xml", ...
The following is a non-normative example showing a snippet of Instance Metadata for an Application Provider using SAML:
"application_provider_instance": { "tenant_id": "3jp2c2JaQ2c52f5hrWC", "sso_protocol": "SAML", "saml_metadata_uri": "https://tenant56789.example.com/saml-metadata.xml", ...
When using the OIDC SSO protocol, the specifications in Section 11.1 require that both parties support OpenID Connect Discovery 1.0 [OpenID.Discovery] and OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]. These specifications require that an Identity Provider share the location of an OpenID Provider Configuration Endpoint.
This is accomplished by extending the Identity Provider Instance Metadata structure with the following attributes:
The following is a non-normative example showing a snippet of Instance Metadata for an Identity Provider using OIDC:
"identity_provider_instance": { "tenant_id": "k2lini4cj509ut09cj0jcjwee9gj0jeg", "sso_protocol": "OIDC", "oidc_configuration_uri": "https://tenant12345.example.com/oidc-configuration", ...
When using the SCIM user provisioning mode, the Application Provider needs to share the location of their SCIM endpoint.
To enable this, the Application Provider Instance Metadata structure is extended with the following attributes:
The following is a non-normative example showing a snippet of Instance Metadata for an Application Provider using SCIM provisioning:
"application_provider_instance": { "tenant_id": "3jp2c2JaQ2c52f5hrWC", "sso_protocol": "SAML", "saml_metadata_uri": "https://tenant56789.example.com/saml-metadata.xml", "user_provisioning_mode": "SCIM", "scim_service_uri": "https://tenant56789.examole.com/scim" ...
Metadata Endpoints describe the semantics for reading the Metadata documents.
A request to this endpoint will return the Provider Metadata document defined in Section 4.3.
The Provider Metadata Endpoint MUST be accessible to other Providers who are permitted to initiate a FastFed Handhake Flow with the entity. Access to the Endpoint SHOULD NOT require Administrators to perform preconfiguration or preregistration of any form between the two Providers, except the necessary act of inputting the URL for the Provider Metadata Endpoint (a.k.a. "FastFed URL") to initiate the FastFed Handshake. Requests to the endpoint may be rate-limited or otherwise limited to prevent a denial-of-service attack.
The means of discovering the location of a Provider Metadata Endpoint for a specific Provider is out of scope of this specification.
As a reference to implementers, Providers typically include their Provider Metadata Endpoint (a.k.a. "FastFed URL") in their SSO documentation materials. Providers may also construct predefined catalogs of common integration partners with whom federations can be instantiated, where the FastFed URLs of the partners are part of the catalog.
Provider Metadata can be read by making an HTTP GET request to the Provider Metadata Endpoint.
The following is a non-normative example read request:
GET /fastfed/provider-metadata HTTP/1.1 Accept: application/json Host: provider.example.com
Upon a successful read operation, the server SHOULD return all available Provider Metadata.
A successful response SHOULD use the HTTP 200 OK status code and return a JSON document [RFC4627] using the application/json_content type with the Provider Metadata values as top-level members of the root JSON object.
The following is a non-normative example read response (with line wraps within values for display purposes only):
HTTP/1.1 200 OK Content-Type: application/json { "identity_provider": { "provider_uri": "https://app.example.com", "name": "My Identity Provider", "icons": { "large_icon_uri": "https://idp.example.com/images/tile.png", "small_icon_uri": "https://idp.example.com/images/favicon.png" } capabilities: { "sso_protocols_supported": ["OIDC","SAML"], "user_schemas_supported": ["urn:ietf:params:scim:schemas:core:2.0:User"], "user_provisioning_modes_supported": ["JIT","Custom","NoProvisioning"], "provider_authz_schemes_supported": ["OAuth"] } "fastfed_handshake_start_uri": "https://idp.example.com/fastfed/start", "fastfed_handshake_finish_uri": "https://idp.example.com/fastfed/finish" }
A request to this endpoint will return the Instance Metadata document defined in Section 4.4:
If client authorization is required as per Section 8, the caller MUST use one of the authorization methods supported by the Provider when requesting Instance Metadata.
The location of the Instance Metadata Endpoint is shared with Providers during the FastFed Handshake, as part of the request parameters. See 7.2.1.7 and 7.2.2.8.
Instance Metadata can be read by making an HTTP GET request to the Instance Metadata Endpoint. The following is a non-normative example read request:
GET /tenant12345/instance-metadata HTTP/1.1 Accept: application/json Host: provider.example.com
Upon a successful read operation, the server SHOULD return all available Instance Metadata.
A successful response SHOULD use the HTTP 200 OK status code and return a JSON document [RFC4627] using the application/json_content type with the Provider Metadata values as top-level members of the root JSON object.
The following is a non-normative example read response (with line wraps within values for display purposes only):
HTTP/1.1 200 OK Content-Type: application/json { "identity_provider_instance": { "tenant_id": "k2lini4cj509ut09cj0jcjwee9gj0jeg", "sso_protocol": "SAML", "saml_metadata_uri": "https://tenant12345.example.com/saml-metadata.xml", "user_schema": "urn:ietf:params:scim:schemas:core:2.0:User", "user_provisioning_mode": "JIT", "provider_authz_scheme": "OAuth", "oauth_token_endpoint": "https://tenant12345.example.com/token", }
If authorization was required by the server and caller authorization was missing or invalid, the server MUST respond with the HTTP 401 Unauthorized status code. If the client does not have permission to read the record, the server MUST return an HTTP 403 Forbidden.
The following is a non-normative example error response:
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired" Cache-Control: no-store Pragma: no-cache
A compatibility evaluation is the act of comparing the abilities of two Providers to determine if they can interoperate. For FastFed, this is accomplished by examining the intersection of Provider Capabilities. The process is specified below.
For reference, all FastFed Capabilities are represented as lists of strings. This includes the following attributes:
Each list is evaluated for compatibility via the following steps:
If the Providers are incompatible for at least one list, then the Providers MUST be treated as incompatible.
The FastFed Handshake can include the exchange of secret materials and private tenant information. All implementations MUST require the use of TLS for all FastFed Endpoints, including the Metadata Endpoints and FastFed Handshake Endpoints. If an underlying protocol also exposes their own endpoints (e.g. SAML Metadata Files), those endpoints SHOULD use TLS, too.
Which TLS version(s) ought to be implemented will vary over time, and depends on the widespread deployment and known security vulnerabilities at the time of implementation. To protect against information disclosure and tampering, confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection.
Whenever TLS is used, a TLS server certificate check MUST be performed, per [RFC6125].
This specification makes use of HTTP redirections, in which a Provider directs the Administrator's user-agent to another destination. While the examples in this specification show the use of the HTTP 302 status code, any other method available via the user-agent to accomplish this redirection is allowed and is considered to be an implementation detail.
The FastFed Handshake uses HTTP GET and POST to transmit requests. Request parameters may be serialized using the following methods:
In order to serialize the parameters using the Query String Serialization, the Client constructs the string by adding the parameters and values to the query component of a URL using the application/x-www-form-urlencoded format as defined by [W3C.REC-html401-19991224]. Query String Serialization is typically used in HTTP GET requests. The same serialization method is also used when adding parameters to the fragment component of a URL.
Parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request using the application/x-www-form-urlencoded format as defined by [W3C.REC-html401-19991224]. Form Serialization is typically used in HTTP POST requests.
In certain circumstances, the FastFed Handshake cannot proceed and must be halted. This may occur, for example, if the Providers do not share common capabilities.
When halting the handshake, the Provider who decides to halt SHOULD display an informative message to the Administrator explaining why the action was halted and any steps that can be taken by the Administrator to correct the situation. The details of this communication to the Administrator are outside the scope of the specification.
The FastFed Handshake begins by sending an HTTP GET or POST to the Identity Provider's fastfed_handshake_start_uri, as defined within the Identity Provider Metadata per Section 4.3.3.
The request contains the following parameters:
Identity Providers MUST support the use of HTTP GET and POST. Clients MAY use the HTTP GET or POST methods.
If using the HTTP GET method, the request parameters are serialized using URI Query String Serialization. If using the HTTP POST method, the request parameters are serialized using Form Serialization.
Any entity may initiate the FastFed Handshake. As a reference to implementers, an Identity Provider can initiate the handshake by sending a message to itself, using the fastfed_handshake_start_uri that is already known to the Identity Provider. Alternatively, an Application Provider can initiate the handshake by asking an Administrator for the FastFed URL of an Identity Provider and then querying the URL to retrieve the Identity Provider Metadata document which contains the fastfed_handshake_start_uri.
The following is a non-normative example of a handshake initiation request using HTTP POST
POST /fastfed/handshake/start Host: idp.example.com Content-Type: application/x-www-form-urlencoded provider_metadata_uri=https%3A%2F%2Fapp.example.com%2Ffastfed%2Fprovider-metadata
The following is a non-normative example of a handshake initiation request using HTTP GET.
GET /fastfed/handshake/start?provider_metadata_uri=https%3A%2F%2Fapp.example.com%2Ffastfed%2Fprovider-metadata HTTP/1.1 Host: idp.example.com
Upon receiving the handshake initiation request, the Identity Provider MUST authenticate the Administrator and verify they are authorized to initiate the FastFed Handshake with the Application. The means of doing so are outside the scope of this specification.
If the Administrator cannot be authenticated, the FastFed Handshake MUST be halted.
Using the provider_metadata_uri sent as a parameter in the handshake request, the Identity Provider queries the Application Provider Metadata Endpoint.
If the Application Provider Metadata cannot be downloaded or is missing required elements, the FastFed Handshake MUST be halted.
The Identity Provider MUST compare its Provider Metadata against the Application Provider Metadata in order to verify compatibility, as described in Section 6.
If the Providers are incompatible, the FastFed Handshake MUST be halted.
The Identity Provider MUST obtain explicit consent from an Administrator to share tenant information with the Application Provider, unless the Administrator has previously consented or the Identity Provider and Application Provider are hosted by the same party.
As a reference to implementers, consent could include displaying a confirmation page. The Identity Provider may also alert the Administrator of any potential risks with the Application Provider, including but not limited to invalid TLS certificates detected when querying Application Provider Endpoints, or matches against suspected phishing sites.
The Identity Provider generates, or makes available, an Instance Metadata Endpoint containing the specific configuration and preferences for establishing a federated relationship with the Application Provider.
The chosen preferences MUST be valid Capabilities for both the Identity Provider and Application Provider; e.g. if both Providers support the SAML SSO protocol, then SAML is a valid choice for SSO protocol. On the other hand, if one or both Providers do not support SAML, it is not a valid choice.
It is possible for Providers to share multiple valid options for a Capability; e.g. both Providers may support SAML and OIDC as SSO protocols. If this occurs, the Identity Provider MUST choose one of the capabilities to use. The manner of determining a choice is considered an implementation detail and is outside the scope of the specification.
One of the preferences that can be chosen by the Identity Provider is the provider_authz_schemes_supported. When the Identity Provider chooses an authorization scheme, it will be used for any interactions between Providers which mandate authorization. The chosen scheme is communicated in two ways: within the Instance Metadata, and also as a parameter in the handshake message to the Application Provider. Both values MUST be the same. The authorization details depend upon the chosen scheme and are described in Section 8
It is possible for an Instance Metadata document to already exist for the given Application Provider, either because this is a duplicate request or a previous handshake was halted or abandoned. If this occurs, the existing Instance Metadata MUST NOT be altered. Doing so could cause inadvertently cause an existing federation relationship to be modified before the Administrator has consented to changes. Instead, a new Instance Metadata Endpoint MUST be instantiated at a new location.
COMMENTS: [CREF1]Darin McAdams: Want to discuss the security model with the group. If we assume any data that traverses through the User Agent is potentially compromised, should the following parameters be encapsualted inside a JWE when transmitting them to the Application Provider? The public keys could be shared as JWK elements in the Provider Metadata files. This question becomes even more important when adding OAuth grants into handshake in Section 7. [CREF2]Darin McAdams: In addition, the names of these attributes should probably be shortened to encourage a compact representation. Leaving as-is for now until the security discussion gives more confidence on the mechanisms for exchanging this data.
If the preceding steps were successful, the Identity Provider responds by issuing a redirect to the Application Provider containing the following parameters:
The following is a non-normative example of a response (with line wraps within values for display purposes only):
HTTP/1.1 302 Found Location: https://app.example.com/fastfed/handshake/receive? provider_metadata_uri=https%3A%2F%2Fidp.example.com%2Ffastfed%2Fprovider-metadata &instance_metadata_uri=https%3A%2F%2Ftenant12345.example.com%2Ffastfed%2Finstance-metadata &state=vk2j35ijlkt2j2oij3ti2jtkltkl2n4kl2n
Upon receiving a handshake message from the Identity Provider as specified in Step 7.2.1.7, the Application Provider MUST authenticate the Administrator and verify they are authorized to setup federation with the Identity Provider.
If the Administrator is a new customer without an existing account with the Application Provider, the Application Provider MAY lead the administrator through a sign-up workflow to subscribe to the Application. The means of doing so are outside the scope of this specification.
If the Administrator cannot be authenticated, the FastFed Handshake MUST be halted.
Using the provider_metadata_uri sent as a parameter in the handshake request, the Application Provider queries the Identity Provider Metadata Endpoint.
If the Identity Provider Metadata cannot be downloaded or is missing required elements, the FastFed Handshake must be halted.
Using the instance_metadata_uri sent as a parameter in the handshake request, the Application Provider queries the Identity Provider's Instance Metadata Endpoint.
If the handshake request contains a parameter for provider_authz_scheme, the Application Provider MUST use the authorization scheme when retrieving the Instance Metadata.
If the Instance Metadata cannot be downloaded or is missing required elements, the FastFed Handshake must be halted.
The Instance Metadata provided by the Identity Provider will contain configuration and preferences for establishing a federated relationship with the Application Provider.
The Application Provider MUST verify that the choices within the Instance Metadata are valid Capabilities for the Application Provider; e.g. if the Application Provider supports SAML as an SSO protocol, then SAML is a valid choice for SSO protocol. On the other hand, if the Application Provider does not support SAML as a Capability, it is not a valid choice.
The FastFed Handshake must be halted if the Instance Metadata contains unsupported Capabilities.
The Application Provider generates, or makes available, an Instance Metadata Endpoint containing the specific configuration and preferences for establishing a federated relationship with the Identity Provider.
The chosen Capabilities MUST match those received from the Identity Provider, plus any additional properties specific to the Application Provider; e.g. if the Identity Provider specified SAML as the SSO protocol in its Instance Metadata, the Application Provider MUST also specify SAML, and will include any SAML-specific configurations that are required of an Application Provider. The details vary by protocol and are described in Section 4.5.
The Application Provider MUST obtain explicit consent from an Administrator to enable federation with the Identity Provider. The Application Provider MUST include CSRF protections when obtaining consent.
If a federation relationship was previously configured between the tenant of the Identity Provider and the txsenant of the Application Provider, the Application Provider MUST alert the Administrator that proceeding will modify an existing federation configuration.
The details of warning the Administrator are out of scope of the specification. Implementers SHOULD consider highlighting any changes that may temporarily break end-users during the FastFed Handshake flow; e.g. if the SSO protocol is being changed from SAML to OIDC, incoming sign-in attempts may fail until the handshake completes and the new configuration has been successfully applied by both Providers
Upon receiving consent from the Administrator, the Application Provider MUST take any actions necessary to enable federation with the Identity Provider. This is an implementation detail. Actions typically include updating internal datastore records to allow SSO from the Identity Provider, performing any additional registration activities required by the SSO protocol, and potentially opening up endpoints for user provisioning.
If an authorization scheme is used, the Identity Provider MUST be granted access to all operations on the Application Provider necessary for the federated relationship to become active.
If the preceding steps were successful, the Application Provider responds by issuing a redirect to the Identity Provider.
The location to send the response is specified by the fastfed_handshake_finish_uri attribute within the Identity Provider Metadata.
The response contains the following parameters:
If an authorization scheme is used, the response may contain additional authorization parameters. The details vary by scheme and are described in Section 8.
The following is a non-normative example of a response:
HTTP/1.1 302 Found Location: https://idp.example.com/fastfed/handshake/finish? instance_metadata_uri=https%3A%2F%2Ftenant67890.example.com%2Ffastfed%2Finstance-metadata &state=vk2j35ijlkt2j2oij3ti2jtkltkl2n4kl2
If the Identity Provider included the state parameter when issuing the handshake request to the Application Provider, the Identity Provider MUST verify that the state parameter received in the response is equal to the value sent in the request.
Using the instance_metadata_uri received as a parameter in handshake response, the Identity Provider queries the Application Provider Metadata Endpoint, as per Section 5.1.
If the Identity Provider included the authz_scheme parameter in the handshake request, the Identity Provider MUST use the authorization scheme when retrieving the Instance Metadata from the Application Provider.
If the Instance Metadata cannot be downloaded or is missing required elements, the FastFed Handshake must be halted.
The Identity Provider MUST verify that the chosen Capabilities in the Instance Metadata vended by the Application Provider match those chosen by the Identity Provider; e.g. if the Identity Provider specified SAML as the SSO protocol in its Instance Metadata, the Application Provider MUST also specify SAML.
The Identity Provider MUST obtain explicit consent from an Administrator to enable federation with the Application Provider.
Obtaining consent MUST include displaying the user attributes that will be released to the Application Provider, as specified in the desired_user_attributes declared by the Application Provider in their Instance Metadata. The user attributes SHOULD be displayed to Administrators in a human-readable format that can be easily understood.
The Identity Provider MUST include CSRF protections when obtaining consent.
If a federation relationship was previously configured between the tenant of the Identity Provider and the tenant of the Application Provider, then completing the handshake SHOULD update the preexisting federation configuration with the newly exchanged values. The Identity Provider SHOULD inform the Administrator of the changes that will be made to the previously defined configuration.
Upon receiving consent from the Administrator, the Identity Provider MUST take any actions necessary to enable federation with the Application Provider. This is an implementation detail. Actions typically include updating internal datastore records to allow SSO to the Application Provider, and potentially initiating user provisioning.
If a provider authorization scheme is used, the Application Provider MUST now be granted access to all operations on the Identity Provider necessary for the federated relationship to become active.
Provider Authorization enables an Identity Provider and Application Provider to agree on an authorization scheme and use that scheme to protect access to any endpoints shared with the other party. Supported schemes are communicated via the provider_authz_schemes_supported property within Provider Metadata.
This specification describes one authorization scheme using OAuth.
FastFed defines an OAuth Extension Grant Type (Section 4.5 of RFC 6749) with URI urn:ietf:params:oauth:grant-type:fastfed.
The FastFed grant type uses access codes exchanged by Providers during the FastFed Handshake. These initial access codes are redeemed for an OAuth access_token and refresh_token using the OAuth Extension Grant Flow (Section 4.5 of RFC 6749). The resulting OAuth tokens are Bearer Tokens [RFC6750] that are subsequently used for accessing any FastFed endpoints which require authorization.
The FastFed initial access codes are redeemed by making a request to the token endpoint of an OAuth authorization server with the following parameters:
The following is a non-normative example of using the OAuth Extension Grant with the FastFed initial_access_code:
POST /token HTTP/1.1 Host: idp.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3fastfed &initial_access_code=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDUk2k2
Support for OAuth is specified in FastFed by including the string OAuth in the provider_authz_schemes_supported property in Provider Metadata.
OAuth is selected as an authorization scheme by using the string OAuth as the value of the provider_authz_schemes_supported in Instance Metadata.
When using OAuth, both Providers need to share the location of the OAuth token endpoint.
To enable this, the Common Instance Metadata structure is extended with the following attributes:
The following is a non-normative snippet of Instance Metadata showing the use of OAuth:
{ "identity_provider_instance": { "tenant_id": "k2lini4cj509ut09cj0jcjwee9gj0jeg", ... "provider_authz_scheme": "OAuth", "oauth_token_endpoint": "https://tenant12345.example.com/token", ...
The use of the OAuth scheme extends the FastFed Handshake flows with additional parameters and requirements. These extensions are described below.
The request from the Identity Provider to the Application Provider is extended with the following parameters:
HTTP/1.1 302 Found Location: https://app.example.com/fastfed/handshake/receive? provider_metadata_uri=https%3A%2F%2Fidp.example.com%2Ffastfed%2Fprovider-metadata &instance_metadata_uri=https%3A%2F%2Ftenant12345.example.com%2Ffastfed%2Finstance-metadata &state=vk2j35ijlkt2j2oij3ti2jtkltkl2n4kl2n &authz_scheme=OAuth &oauth_token_endpoint=https%3A%2F%2Fidp.example.com%2Foauth%2Ftoken &initial_access_code=p3kN2ko1Ho2439cmDs5
The Identity Provider MUST perform the following:
The Application Provider MUST perform the following:
Prior to reading Instance Metadata, the Application Provider MUST exchange the initial_access_code for an OAuth access_token and refresh_token. This is accomplished by using the OAuth Extended Grant flow with the oauth_token_endpoint and initial_access_code supplied by the Identity Provider.
The resulting access_token MUST be presented as a Bearer Token [RFC6750] when calling the Instance Metadata Endpoint on the Identity Provider
The following is a non-normative example of a request and response using the OAuth Extension Grant with FastFed:
POST /token HTTP/1.1 Host: idp.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3fastfed &initial_access_code=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDUk2k2
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token":"Lj2kj3ujwlkdnl2ip42i2o", "token_type":"Bearer", "expires_in":3600, "refresh_token":"ztdyt86vgljyfJRq0vDJ676" }
The following is a non-normative example of using the access_token to query Instance Metadata:
GET /tenant12345/instance-metadata HTTP/1.1 Accept: application/json Host: provider.example.com Authorization: Bearer Lj2kj3ujwlkdnl2ip42i2o
The Identity Provider MUST perform the following for this step:
The Application Provider MUST perform the following:
The response from the Application Provider to the Identity Provider is extended with the following parameters:
The following is a non-normative example showing the usage of OAuth with the additional parameters:
HTTP/1.1 302 Found Location: https://ipd.example.com/fastfed/handshake/finish? instance_metadata_uri=https%3A%2F%2Ftenant67890.example.com%2Ffastfed%2Finstance-metadata &state=vk2j35ijlkt2j2oij3ti2jtkltkl2n4kl2n &authz_scheme=OAuth &oauth_token_endpoint=https%3A%2F%2Fapp.example.com%2Foauth%2Ftoken &initial_access_code=k6i49yjo93jPklqlsj
The Application Provider MUST perform the following:
The Identity Provider MUST perform the following for this step:
This extension is similar to Step 8.1.4.2 with the roles of the Identity Provider and Application Provider swapped.
Prior to querying the Instance Metadata from the Application Provider, the Identity Provider MUST exchange the initial_access_code for an OAuth access_token and refresh_token. This is accomplished by using the OAuth Extended Grant flow with the token endpoint and initial_access_code supplied by the Application Provider, as per Section 8.1
The resulting access_token MUST be presented as a Bearer Token [RFC6750] when calling the Instance Metadata Endpoint on the Application Provider.
When enabling federation and completing the handshake, the Identity Provider MUST grant access to the Application Provider for all operations necessary for the federated relationship to become active. This MAY be accomplished by including the new permissions the next time the Application Provider uses their refresh_token to fetch a new access_token.
If the Identity Provider supports OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration], the FastFed Application Provider MUST present the access_token as the Initial Access Token when calling the Client Registration Endpoint. The Identity Provider SHOULD authorize the caller using the presented token.
In addition, the Application Provider MUST present the access_token as a Bearer Token [RFC6750] when querying any OpenID Connect endpoints hosted by the Identity Provider, including OpenID Provider Configuration Requests as specified in OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration]. The Identity Provider SHOULD authorize the Application Provider using the presented token.
When reading SAML Metadata from an endpoint specified by a Provider, the caller MUST present the access_token as a Bearer Token [RFC6750] when querying the endpoint. The endpoint owner SHOULD authorize the caller using the presented token.
When calling a SCIM endpoint as part of user provisioning activities, the caller MUST present the access_token as a Bearer Token [RFC6750]. The endpoint owner SHOULD authorize the caller using the presented token.
FastFed requires that an Identity Provider and Application Provider share a common user schema. FastFed RECOMMENDS the use of the SCIM specification for defining schemas [RFC7643]. Any schema specified under the path urn:ietf:params:scim:schemas will be presumed to be a SCIM schema definition for the purposes of this specification.
For each schema, the following properties must be specified:
Attribute Path is a string whose contents reference a specific user attribute within the schema.
Attribute Path Syntax describes the format of the string and varies by schema type. Section 9.3.1 describes the Attribute Path Syntax for SCIM.
Attribute Mapping is a structure containing the following elements:
When performing an attribute mapping based upon the mapping_rules, Identity Providers MUST ignore and omit any attributes in the mapping_rules which were not explicitly approved for release by the Administrator in Step 7.2.3.4 of the FastFed Handshake.
FastFed uses the SCIM PATH specification as defined in section Section 3.5.2 of the SCIM Core Specification [RFC7643].
The following are non-normative examples of SCIM PATH definitions:
userName name.familyName addresses[primary eq true].formatted
When used with FastFed, a SCIM PATH expression MUST point to an attribute with one of the following Data Types as defined in Section 3 of the SCIM Core Specification [RFC7643].
The SCIM PATH expression MUST NOT point to an attribute with a Complex Data Type. If information is needed from a Complex attribute, each piece of information should be referenced by explicitly specifying unique paths to the members of a Complex attribute.
The following is a non-normative example of an invalid path which MUST NOT be used because it references a Complex attribute:
addresses[primary eq true] # Invalid. Points to Complex attribute.
The SCIM PATH expression MAY match multiple attributes. Each matching attribute MUST be one of the supported Data Types.
The following are non-normative examples of paths which may match multiple attributes:
groups.displayName # List of group displayNames emails.value # List of email values emails[value co ".com"].value # List of email values containing ".com"
This syntax maps between SCIM 2.0 schemas [RFC7643] and SAML 2.0 assertions [SAML.Assertions].
The syntax is referenced by specifying the string simple_scim_to_saml as the value of the mapping_syntax attribute in the Attribute Mapping structure.
This syntax defines a transformation based on simple string copying. No formatting or alterations of the strings are supported. Instead, values are simply copied from the user schema and inserted into the SSO protocol with the specified labels and properties.
The mapping rules are defined by a structure containing the following attributes:
The following non-normative example shows a SCIM User, a SCIM Attribute Mapping definition, and the resulting SAML assertion.
Example SCIM User:
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "2819c223-7f76-453a-919d-413861904646", "userName": "bjensen", "name": { "formatted": "Ms. Barbara J Jensen, III", }, "displayName": "Babs Jensen", "emails": [ { "value": "bjensen@example.com", "type": "work", "primary": true }, { "value": "babs@jensen.org", "type": "home" } ], "groups": [ { "displayName": "Employees" }, { "displayName": "US Employees" } ] }
Example Attribute Mapping:
"user_attribute_mapping": { "mapping_syntax": "simple_scim_to_saml", "mapping_rules": { "name_id": { "format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", "value": "id", }, "attributes": [ {"name": "name", "value": "displayName" }, {"name": "email", "value": "email[primary eq true].value" }, {"name": "groups", "value": "groups.displayName" } ] } }
Example of Resulting SAML Document:
... <saml:Subject> <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">2819c223-7f76-453a-919d-413861904646</saml:NameID> </saml:Subject> ... <saml:AttributeStatement> <saml:Attribute Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue">Babs Jenson</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue">bjenson@example.com</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue">Employees</saml:AttributeValue> <saml:AttributeValue">US Employees</saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement> ...
This syntax maps between SCIM schemas [RFC7643] and OpenID Connect claims [OpenID.Core].
The syntax is used by specifying the string simple_scim_to_oidc as the value of the mapping_syntax attribute in the Attribute Mapping structure.
This syntax defines a transformation based on simple string copying. No formatting or alterations of the strings are supported. Instead, values are simply copied from the user schema and inserted into the SSO protocol with specified labels.
The mapping rules are defined by a structure containing key-value pairs, where the key is the name of an OpenID Connect claim and the value is a SCIM Attribute Path.
The following is a non-normative example of simple_scim_to_oidc mapping rules:
"mapping_rules": { "sub": "id", "name": "displayName", "email": "email[primary eq true].value", "groups": "groups.displayName" }
If an attribute value is undefined or empty for an end-user, the Identity Provider MUST omit the claim from OIDC responses.
The following non-normative example shows a sample SCIM User, a SCIM Attribute Mapping definition, and the resulting OIDC claims.
Example SCIM User:
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "id": "2819c223-7f76-453a-919d-413861904646", "userName": "bjensen", "name": { "formatted": "Ms. Barbara J Jensen, III", }, "displayName": "Babs Jensen", "emails": [ { "value": "bjensen@example.com", "type": "work", "primary": true }, { "value": "babs@jensen.org", "type": "home" } ], "groups": [ { "displayName": "Employees" }, { "displayName": "US Employees" } ] }
Example Attribute Mapping:
"user_attribute_mapping": { "mapping_syntax": "simple_scim_to_oidc", "mapping_rules": { "sub": "userName", "name": "displayName", "email": "email[primary eq true].value", "groups": "groups.displayName" } }
Example of Resulting OIDC Claims:
"sub": "bjensen", "name": "Babs Jenson" "email": "bjenson@example.com" "groups": ["Employees", "US Employees"]
Recurring Activities are optional capabilities that continue after the initial FastFed Handshake is completed. Typically, they are used to communicate changes in Metadata that are safe to share between Providers automatically, without explicit consent from an Administrator.
This specification defines recurring activities for key rotation and icon image updates.
Recurring Activities Capabilities is a structure containing the following attributes:
The Common Provider Metadata structure defined in Section 4.3.2 is extended with the following attribute:
The following is a non-normative example of Provider Metadata containing recurring activities:
"application_provider": { ... "recurring_activities_supported": { "icon_refresh": ["publish","consume"], "saml_certificate_rotation": ["consume"], "oidc_key_rotation": ["consume"], } ... }
The Common Instance Metadata structure defined in Section 4.4.1 is extended with the following attribute:
"application_provider_instance": { ... "recurring_activities": { "icon_refresh": ["publish"], "saml_certificate_rotation": ["consume"], } ... }
There are no changes to the Provider Compatibility Evaluation defined in Section 6. This is because Recurring Activities are optional. If one Provider supports an activity, but the other doesn't, then the activity will simply not be executed.
When constructing an Instance Metadata document, the following process MUST be used to select the Recurring Activities Capabilities that can be enabled for a specific federation.
In addition, during the FastFed Handshake, each Provider MUST validate that the Instance Metadata vended by the other Provider conforms to this selection process.
The following is a non-normative example showing the Provider Metadata and resulting Instance Metadata for a federation between an Identity Provider and Application Provider:
Example of Provider Metadata:
"identity_provider": { ... "recurring_activities": { "icon_refresh": ["publish", "consume"], "saml_certificate_rotation": ["publish"] "oidc_key_rotation": ["publish"] } ... }
"application_provider": { ... "recurring_activities": { "icon_refresh": ["publish"], "saml_certificate_rotation": ["consume"] } ... }
Example of resulting Instance Metadata:
"identity_provider_instance": { .... "recurring_activities": { "icon_refresh": ["consume"], "saml_certificate_rotation": ["publish"] } ... }
"application_provider_instance": { ... "recurring_activities": { "icon_refresh": ["publish"], "saml_certificate_rotation": ["consume"] } ... }
To publish updated icon images, the following requirements apply to a Provider:
If these requirements are met, the Provider SHOULD specify publish as a value in their list of icon_refresh capabilities.
To consume updated icon images, the following requirements apply to a Provider:
If these requirements are met, the Provider SHOULD specify consume as a value in their list of icon_refresh capabilities.
While the full SAML specification supports a variety of key usages, the FastFed Interoperability Requirements restrict Providers to only X509 Keys for signing SAML Assertions in Web Browser SSO response messages from the Identity Provider.
As such, the following constraints apply to saml_key_rotation specifications:
To rotate and publish new SAML signing certificates, the following requirements apply to the Identity Provider:
If these requirements are met, the Identity Provider MAY specify publish as a value in their list of saml_key_rotation capabilities.
To consume rotated SAML signing keys, the following requirements apply to the Application Provider:
If these requirements are met, the Application Provider MAY specify consume as a value in their list of saml_key_rotation capabilities.
Open ID Connect describes a variety of keys and secrets that are managed by both Identity Providers and Application Providers. The FastFed Interoperability Requirements permit use of the following:
Since all permitted keys are generated and vended by the Identity Provider, the following constraints apply to oidc_key_rotation specifications:
If the Identity Provider meets all the requirements described below in Publication of New Signing Keys and Publication of New Client Secret, the Identity Provider SHOULD specify publish as a value in their list of oidc_key_rotation capabilities.
To publish new signing keys, the following requirements apply to the Identity Provider:
To publish a new client_secret, the following requirements apply to the Identity Provider:
If the Application Provider meets all the requirements described below in Consumption of New Public Signing Keys and Consumption of New Client Secret, the Application Provider SHOULD specify consume as a value in their list of oidc_key_rotation capabilities.
To consume new public signing keys, the following requirements apply to the Application Provider:
At least one of the above methods MUST be used to re-retrieve keys from the jwks_uri. Both methods MAY be used concurrently. In addition, the following requirements apply to the Application Provider:
As background, when an Application Provider initially registers with an Identity Provider using OpenID Connect Dynamic Client Registration [OpenID.Registration], the registration response contains the following attributes:
To rotate the client_secret, the Application Provider will periodically re-query the Client Configuration Endpoint (located at the registration_client_uri) in order to re-read the current configuration. If a new client_secret has been issued, the new client_secret will appear in the response. The specifications for querying the Client Configuration Endpoint are described in Section 4 of OpenID Connect Dynamic Client Registration 1.0 [OpenID.Registration].
To consume new values of client_secret, the following requirements apply to the Application Provider:
Each of the existing identity standards 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. For example, if an Application Provider chooses to require signed SAML Authentication requests, but the Identity Provider doesn't support this feature of SAML, the Providers are incompatible even though both use SAML.
To deliver the simplified Administrator 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. To provide this confidence, this section describes the interoperability requirements for different protocols that a Provider must satisfy to be FastFed Compatible.
A Provider who includes the value OIDC in the sso_protocols_supported within their Metadata will use the OpenID Connect authentication flows as defined in Section 3 of [OpenID.Core].
The following sections describe the subset of the OIDC specifications that Providers MUST implement to be FastFed Combatible for the OIDC SSO protocol. Providers MAY support additional functionality, but MUST NOT require the additional functionality when configuring federation with another Provider using the FastFed specifications.
A Provider who includes the value SAML in the sso_protocols_supported within their Metadata will use the SAML 2.0 Web Browser SSO Profile as defined in Section 4.1 of [SAML.Profiles].
The following sections describe the subset of the SAML specifications that Providers MUST implement to be FastFed Compatible for the SAML SSO protocol. Providers MAY support additional functionality, but MUST NOT require the additional functionality when configuring federation with another Provider using the FastFed specifications.
SAML Requirements for Identity Providers:
SAML Requirements for Application Providers:
A Provider who includes the value SCIM in the user_provisioning_modes_supported within their Provider Metadata will use the SCIM Protocol as defined in [RFC7644].
The following sections describe the subset of the SCIM Protocol specifications that Providers MUST implement to be FastFed Combatible for SCIM provisioning. Providers MAY support additional functionality, but MUST NOT require the additional functionality when configuring federation with another Provider using the FastFed specifications.
SCIM requirements for Identity Providers:
SCIM requirements for Application Providers:
A Provider who meets the requirements defined in this specification MAY describe themselves as "FastFed Compatible".
Since FastFed allows Providers to pick-and-choose from a variety of different protocols, Providers SHOULD include the supported protocols when describing their compatibility.
The following is a non-normative example of a FastFed Compatibility description for an Application Provider:
This application is FastFed Compatible with Identity Providers who support the following: * SSO Protocol: SAML * User Schema: SCIM User * Provisioning Mode: Just In Time (JIT) provisoning In addition, this application supports automatic SAML certificate rotation if enabled by the Identity Provider.
The following is a non-normative example of a FastFed Compatibility description for an Identity Provider:
This Identity Provider is FastFed Compatible with the following: * Any of the following SSO Protocols - SAML - OpenID Connect * Any of the following User Schemas: - SCIM User - SCIM Enterprise User * Any of the following User Provisioning Modes: - SCIM provisioning - Just In Time provisioning - Custom provisioning - No provisioning In addition, if supported by an application, this Identity Provider will automatically perform SAML certificate rotation and OIDC key rotation.
TODO. See comments in 7.2.1.7
TODO
The OpenID Community would like to thank the following people for their contributions to this specification:
Copyright (c) 2017 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.
[[ To be removed from the final specification ]]