PingFederate Server

Setting up an attribute contract

An attribute contract is the set of user attributes that you and your partner have agreed will be sent in the single sign-on (SSO) tokens for this connection.

About this task

You specify the attributes for the name identifier on your WS-Federation or, optionally, for your SAML configuration on the Attribute Contract tab. For more information, see Attribute contracts.

WS-Federation connections require you to define attribute contracts. For SAML connections, attribute contracts are optional if you are sending either pseudonym or transient identifiers to the partners. For more information, see Selecting a SAML Name ID type.

When establishing an attribute contract, you can 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 tab.

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 window. Otherwise the Attribute Contract window 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 window. Otherwise the Attribute Contract window 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.

If you are creating or updating a SAML service provider (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. For more information, see Importing SP metadata.

Steps

  1. Follow the required steps to create an SSO token depending on your federation protocol. For more information, see Configure IdP Browser SSO.

  2. If you are using a SAML protocol, on the Identity Mapping tab you must select either Pseudonym or Transient, and also select the Include Attributes box to access the Attribute Contract tab. For more information, see Selecting a SAML Name ID type.

  3. Optional: Click the Attribute Name Format drop-down to select a different format for the built-in subject identifier, SAML_SUBJECT.

    Applicable if you and the SP have agreed to a specific format. For more information, see Attribute contracts.

    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 PingFederate to activate any changes made to this file.

  4. Extend the contract with additional attributes.

    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.

      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 identity provider (IdP) application.

      The value of this attribute can then be mapped later on the Attribute Contract Fulfillment window. For more information, see Configuring contract fulfillment for IdP Browser SSO. 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:

      • For SAML 1.x urn:oasis:names:tc:SAML:1.0:am:unspecified

      • For SAML 2.0 urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

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

      If you are configuring a SAML connection to an InCommon participant (see Incommon federation participants), the attribute contract might 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 andhttps://tools.ietf.org/html/rfc4519[RFC4519] . The following table describes a subset of the object IDs referenced by the most common attributes used by InCommon participants.

      Object ID 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, see the metadata from your partner. The FriendlyName values, if available, should provide additional information about the attributes. Alternatively, third-party resources, such as https://www.ldap.com/ldap-oid-reference and http://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. For more information, see Attribute contracts.

      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 PingFederate to activate any changes made to this file.

    3. Click Add.

    4. Repeat until all desired attributes are defined.

  5. Optional: Click Edit to change the configuration of an existing attribute.

  6. Optional: Click Delete to remove an existing attribute.

  7. Click Next to save changes.