3.1.1.3 Federation Partner

  • Article

A federation partner is a generic term used to refer to a security realm that operates either a requestor IP/STS or a relying party service (or both), capable of performing the mandatory operations defined in this specification.

A requestor IP/STS and a relying party MUST exchange configuration metadata before they begin exchanging protocol messages. How this metadata is exchanged is implementation-specific and not addressed in this protocol. Administrators MAY<34> exchange files by an out-of-band process (such as email attachments) and enter the partner's metadata into a local configuration file or database.

A requestor IP/STS and a relying party MUST exchange at least the following metadata before they begin exchanging protocol messages:

  • Unique identifiers that indicate the security realms that they represent, and distinguish them from other possible federation partners.

  • URLs that indicate where protocol messages are to be sent.

Also, the relying party MUST obtain the certificate specified in [X509] that contains the public key that corresponds to the private key that the requestor IP/STS uses for signing security tokens.

The following is a potential representation for organizing this data. The data is organized as a series of records, each representing a federation partner. The fields of this record are as follows:

  • Identifier: A string field that uniquely identifies the security realm of the partner. It must be the value that is used for the wtrealm parameter for wsignin1.0 request messages. For details, see section 2.2.3.

  • Role: A string field that identifies the role (or roles) played by the partner, and thus the types of protocol messages that it can send or receive. There are two possible values for this field, requestor IP/STS and relying party. This field must contain at least one value. If a federation partner is capable of playing both roles, this can be represented by a single record with both requestor IP/STS and relying party values present, or it MAY be represented by two separate records with different values for the Role field.<35>

  • URL: A field indicating the URL to which all protocol messages that are intended for the federation partner identified by this record must be sent.

  • Certificate (optional): A field indicating an X.509 certificate that holds the public key that corresponds to the private key used by the partner for signing security tokens. If the Role field contains requestor IP/STS, a certificate must be present. Otherwise this field does not apply. Note that the field can contain multiple certificates. If the requestor IP/STS is a farm of servers, all of the servers can use the same private key, or each server can use a different private key.<36>

A security token, as described in section 2.2.4.2, MUST contain an AuthenticationStatement that specifies the identity of the user in the Subject element. The wsignin1.0 request message does not contain a provision to specify additional claims that the relying party requires to determine if a user is authorized to access a particular WS resource. If specific claims are to be included in a security token, federation partners MUST agree on them before protocol messages are exchanged. Specific claims can be requested as part of the metadata exchange and included in the federation partner record.

The following is a potential representation for organizing this data. Two fields are added to the abstract data model of a federation partner record. For further specifications on the AttributeStatement element of a security token mentioned in the following data definitions, see section 2.2.4.2:

  • ClaimsOut (optional): A list of claims, as defined in section 3.1.1.4, that SHOULD be included in an AttributeStatement of a security token sent in a wsignin1.0 response message to the federation partner. This SHOULD match the corresponding ClaimsIn record at the federation partner.<37>

  • ClaimsIn (optional): A list of claims, as specified in section 3.1.1.4, that MAY be included in the AttributeStatement of a security token received in a wsignin1.0 response message from the federation partner. This SHOULD match the corresponding ClaimsOut record at the federation partner.<38>

This protocol does not address whether these additional claims are treated as optional or mandatory by the requestor IP/STS. There is no guarantee that a particular user will have the attribute data necessary to satisfy every claim on the ClaimsOut list for every relying party that requests a security token for that user. Whether a requestor IP/STS fails a wsignin1.0 request message if it cannot set every claim is an implementation-specific detail that is not addressed in this protocol. It is recommended that a security token be issued and the relying party be allowed to decide if it has sufficient information about the user to grant access to the protected resource in question.<39>