An attribute contract is the set of user attributes that you and your partner have agreed will be sent in the SSO tokens for this connection (see Attribute contracts). You identify these attributes on the Attribute Contract screen.

Establishing an attribute contract is required for WS-Federation connections. For SAML connections, attribute contracts are optional if you are sending either pseudonym or a transient identifiers to the partners. When establishing an attribute contract, you may change the name format when certain conditions are met. The following table summarizes the conditions and the possible actions that you can perform on the Attribute Contract screen.

Protocol Identity mapping Attribute contract SAML_SUBJECT Additional attributes
SAML 2.0 or SAML 1.1 Standard Required Built-in.

Subject name format can be changed by selecting a value from a list.

Optional.

Attribute name format can be changed by selecting a value from a list.

SAML 2.0 or SAML 1.1 Pseudonym or Transient Required only if the Include attributes ... check box is selected on the Identity Mapping screen; otherwise the Attribute Contract screen is not shown. Assumed and cannot be added as an additional attribute. At least one is required.

Attribute name format can be changed by selecting a value from a list.

SAML 1.0 Standard Required Built-in.

Subject name format can be changed by selecting a value from a list.

Optional.

There is no attribute name format.

SAML 1.0 Pseudonym or Transient Required only if the Include attributes ... check box is selected on the Identity Mapping screen; otherwise the Attribute Contract screen is not shown. Assumed and cannot be added as an additional attribute. At least one is required.

There is no attribute name format.

WS-Federation in conjunction with SAML 1.1 as the token type Email address, user principal name, or common name Required Built-in.

There is no subject name format.

Optional.

Attribute name format can be changed by selecting a value from a list.

WS-Federation in conjunction with SAML 2.0 as the token type Email address, user principal name, or common name Required Built-in.

There is no subject name format.

Optional.

Attribute name format can be changed by selecting a value from the list.

WS-Federation in conjunction with JWT as the token type Not applicable Required Not applicable At least one is required.

There is no attribute name format.

Tip:

If you are creating or updating a SAML SP connection, consider using the partner's metadata to do so. If the metadata contains the required information, PingFederate automatically populates the attribute contract for you.

  1. Optional: Select a different name format for the built-in subject identifier, SAML_SUBJECT.
    Applicable if you and the SP have agreed to a specific format (see Attribute contracts).
    Note:

    As needed, you can customize name-format alternatives in the <pf_install>/pingfederate/server/default/data/config-store/custom-name-formats.xml configuration file. (Restart of PingFederate is required to activate any changes made to this file.)

    (Other conditions described in the table apply.)

  2. Extend the contract with additional attributes.
    (Conditions described in the table apply.)
    1. Enter the name of an additional attribute in the text field under Extend the Contract.
      Attribute names are case-sensitive and must correspond to the attribute names expected by your partner.
      Tip:

      You can add a special attribute, SAML_AUTHN_CTX, to indicate to the SP (if required) the type of credentials used to authenticate to the IdP application.

      The value of this attribute can then be mapped later on the Attribute Contract Fulfillment screen (see Configuring contract fulfillment for IdP Browser SSO). Note that the mapped value overrides the authentication context provided by the IdP adapter instance or the Requested AuthN Context Authentication Selector instance (through an authentication policy). If no authentication context is provided by the SAML_AUTHN_CTX attribute, the IdP adapter instance, or the Requested AuthN Context Authentication Selector instance, PingFederate sets the authentication context as follows:
      • urn:oasis:names:tc:SAML:1.0:am:unspecified for SAML 1.x
      • urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified for SAML 2.0
      Tip:

      If you are configuring a WS-Federation connection to Microsoft Windows Azure Pack, add upn to the JWT's attribute contract.

      Tip:

      If you are configuring a SAML connection to an InCommon participant (see www.incommon.org/participants), the attribute contract may contain or require attributes such as urn:oid:0.9.2342.19200300.100.1.3 and urn:oid:2.5.4.42, which are standard names under various specifications, such as RFC4524 (tools.ietf.org/html/rfc4524) and RFC4519 (tools.ietf.org/html/rfc4519). The following table describes a subset of the OIDs (object IDs) referenced by the most common attributes used by InCommon participants.

      OID value Description
      0.9.2342.19200300.100.1.3 mail
      1.3.6.1.4.1.5923.1.1.1.6 eduPersonPrincipalName
      1.3.6.1.4.1.5923.1.1.1.7 eduPersonEntitlement
      1.3.6.1.4.1.5923.1.1.1.9 eduPersonScopedAffiliation
      1.3.6.1.4.1.5923.1.1.1.10 eduPersonTargetedID
      2.5.4.3 cn
      2.5.4.4 sn
      2.5.4.10 o
      2.5.4.42 givenName
      2.16.840.1.113730.3.1.241 displayName

      For other attributes, refer to the metadata from your partner. The FriendlyName values, if available, should provide additional information about the attributes. Alternatively, third-party resources, such as www.ldap.com/ldap-oid-reference and www.oid-info.com, might help as well.

    2. Select an attribute name format from the list.
      Applicable if you and the SP have agreed to a specific format (see Attribute contracts).
      Note:

      As needed, you can customize name-format alternatives in the <pf_install>/pingfederate/server/default/data/config-store/custom-name-formats.xml configuration file. (Restart of PingFederate is required to activate any changes made to this file.)

    3. Click Add.
    4. Repeat until all desired attributes are defined.

Use the Edit, Update, and Cancel workflow to make or undo a change to an item. Use the Delete and Undelete workflow to remove an item or cancel the removal request.