--- title: Setting up an attribute contract description: 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. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:help_assertioncreationtasklet_createattributecontractstate canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/help_assertioncreationtasklet_createattributecontractstate.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: July 5, 2022 section_ids: about-this-task: About this task steps: Steps --- # 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](../introduction_to_pingfederate/pf_attr_contract.html). 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](pf_select_saml_name_id_type.html). 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 …​** checkbox 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 …​** checkbox 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](pf_importing_sp_metadata.html). | ## Steps 1. Follow the required steps to create an SSO token depending on your federation protocol. For more information, see [Configure IdP Browser SSO](help_spconnectionconfigtasklet_spbrowserssostate.html). 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](pf_select_saml_name_id_type.html). 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](../introduction_to_pingfederate/pf_attr_contract.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | As needed, you can customize name-format alternatives in the `/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](pf_configuring_contract_fulfillment_idp_browser_sso.html). 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 (Learn more in [InCommon Community Organizations](https://incommon.org/community-organizations/)), 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](https://tools.ietf.org/html/rfc4524) and [RFC4519](https://tools.ietf.org/html/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 displayNameFor 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 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](../introduction_to_pingfederate/pf_attr_contract.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | As needed, you can customize name-format alternatives in the `/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.