PingFederate Server

Attribute contracts

An attribute contract represents an agreement between partners about user attributes sent in a SAML assertion, a JSON web token (JWT), or an OpenID Connect ID token.

The contract is a list of case-sensitive attribute names. Partners must configure attribute contracts to match.

When privacy is required for sensitive attributes, you can configure PingFederate to mask their values in log files. For more information, see Attribute masking.

For an identity provider (IdP) or an OpenID Provider (OP), the attribute contract defines which attributes PingFederate sends in an assertion, a JWT, or an ID token. While all users authenticate to the partner through this fixed contract, the values used to fulfill the contract might differ from one user to the next. Relying on a combination of different data sources might also fulfill the attribute contract:

  • The IdP adapter or security token service (STS) token processor

  • An IdP attribute source, which identifies the location of individual attributes in a datastore

  • Static text values for some attributes, or text values combined with variables

  • Expressions (see Attribute mapping expressions)

For a service provider (SP) or an OpenID Connect Relying Party, the attribute contract defines the attributes PingFederate expects in a SAML assertion, an ID token, or from the UserInfo endpoint at the OP. To pass these attributes to the SP adapter or, for web services, to the SP token generator, configure PingFederate accordingly. For more information, see Managing SP adapters or Managing token generators. In addition, you can configure PingFederate to use attributes to look up additional attributes in local data stores, which often help start a user session or create a local security token for web services. For more information, see Adapter contracts or STS token contracts.

The attribute contract always contains the user identifier SAML_SUBJECT in a SAML assertion and sub in a JWT or an ID token unless you are using account linking for browser-based single sign-on (SSO). This attribute is automatically included when creating a new contract.

You create attribute contracts on a per-connection basis. For example, if an SP has deployed two session-creation adapters for two separate applications, the IdP connection partner creates a single attribute contract. This single contract supplies all the attributes required by both SP adapters.

Name formats

By agreement with an SP partner, an IdP might specify a format, such as email, associated with the SAML_SUBJECT. The SP might further require this information to facilitate handling of the format.

The partner agreement might also include a requirement for the IdP to provide format specifications associated with other attributes.

PingFederate provides a means for an IdP administrator to select from among standard subject, attribute formats, or both, depending on the relevant SAML specifications. An administrator also defines a customized selection of additional attribute formats. For more information, see Setting up an attribute contract.

The designation of formats does not apply to SP administrators. The information about formats remains available in the incoming assertion to an SP application that needs the information for particular processing requirements.

For the WS-Trust IdP configuration, attribute-name formats remain unspecified. If needed however, an administrator might user a special variable in the attribute contract to set the subject-name format. For more information, see Defining an attribute contract for IdP STS. Browser-based SSO attribute contracts also use the same variable, but the feature has deprecated.

STS namespaces

By agreement with an SP partner for a WS-Trust STS connection, an IdP specifies an XML namespace to associate with an attribute, for example, to use claims-based authorization with WIF clients. For more information, see WSC and WSP support. The only attributes that allow specified namespaces belong to a WS-Trust IdP configuration usingSAML 1.1 or SAML 1.1 for Office 365 as the default token type. For more information, see Defining an attribute contract for IdP STS.