An attribute contract represents an agreement between partners about user attributes sent in a SAML assertion, a JSON web tokens (JWTs), 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 (see Attribute masking).
For an IdP or an OpenID Provider (OP), the attribute contract defines which attributes PingFederate sends in an assertion, a JWT, or an ID token. While this contract is fixed for all users authenticating to the partner, the values used to fulfill the contract may differ from one user to the next. The attribute contract may be fulfilled by relying on a combination of different data sources:
- The IdP adapter or 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 an 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. PingFederate can be configured to pass these attributes to the SP adapter or, for web services, to the SP token generator (see Managing SP adapters or Managing token generators). You can also use attributes to look up additional attributes in local datastores, which may be needed to start a user session or create a local security token for web services (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)—the primary information used to identify the user—unless you are using account linking for browser-based 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, a single attribute contract can be created for the IdP connection partner. This single contract would be constructed to supply all the attributes needed by both SP adapters.
By agreement with an SP partner, an IdP may specify a format (email, for example) associated with the SAML_SUBJECT. The SP may require this information to facilitate handling of the format.
The partner agreement may also include a requirement for the IdP to provide format specifications associated with other attributes.
For browser-based SSO connections, 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 can also define a customized selection of additional attribute formats (see Setting up an attribute contract).
The designation of formats is not applicable to SP administrators. The information is simply available in the incoming assertion to an SP application that might need it for particular processing requirements.
For the WS-Trust IdP configuration, attribute-name formats cannot be specified. If needed, however, an administrator can use a special variable in the attribute contract to set the subject-name format (see Defining an attribute contract for IdP STS). (The same variable is also available for browser-based SSO attribute contracts, but the feature is deprecated.)
By agreement with an SP partner for a WS-Trust STS connection, an IdP may specify an XML namespace to be associated with an attribute (for example, to use claims-based authorization with WIF clients—see WSC and WSP support). Namespaces can be specified only for attributes of a WS-Trust IdP configuration using SAML 1.1 or SAML 1.1 for Office 365 as the default token type (see Defining an attribute contract for IdP STS).