Service Provider High-Level Design

This document focuses on the SP and the consumption of identity and user attribute information.  This document will refer to the IAM's Common Interface, which is detailed in Archived User Provisioning High-Level Design.

IAM Enumeration

In a typical Shibboleth authentication request, an SP will use some technique to discover which IAM to use. In the user provisioning process, an SP must be capable of enumerating a set of supported IAMs. If using the snapshot or point-in-time access strategy, the SP will query each IAM in turn, retrieving identity information in accordance with the IAM's Attribute Release Policy.  If using a subscription strategy, the SP will prepare to receive messages from each supported IAM.

Examples of SP / IAM relationships

SP Attribute Request Process

Snapshot Process

1. SP initiates "Snapshot" call

The SP selects the appropriate IAM and initiates a "Snapshot" call.

SP request for identity information from IAM includes the following:

2. IAM prepares snapshot

The IAM uses an internal process for interrogating all identity repositories supporting the IAM processes and building a list of all community members associated with the given SP. This prepared snapshot is saved for later transmission by a subsequent out-of-band SP call.

To prevent unwanted information disclosure, the snapshot shall contain only those attributes allowed by the given SP's Attribute Release Policy.

Only one prepared snapshot per SP is allowed: each subsequent snapshot request shall overwrite the previous prepared snapshot.

The IAM shall allow the SP to download the prepared snapshot until the specified deletion deadline has passed.

The IAM response to the SP shall include:

3. SP retrieves snapshot

The SP shall retrieve the snapshot prepared by the IAM during step #2 by calling the Retrieval endpoint specified in the IAM's response.

During the idenity transmission from IAM to SP, the IAM shall prevent simultaneous calls from the same SP using a locking mechanism.

If the IAM returned an error response code, the SP shall log relevant information and abort the process.

4. SP consumes snapshot

The SP parses, filters (see "Validation"), merges (see "Identity Merging"), and updates its internal representation of identity information.

Subscription Process

1. SP requests subscription

SP request for subscription to future identity changes shall include the following:

2. IAM subscribes SP

IAM responds to SP subscription request with the following:

3. Ongoing: IAM pushes changes to SP

Details of messaging are left to the messaging implementation.

4. SP unsubscribes from IAM

SP request to unsubscribe from future identity changes shall include the following:

Changelog Process

1. SP initiates the "Changelog" call

The SP selects the appropriate IAM and initiates a "Changelog" call.

SP request for identity information from IAM includes the following:

2. IAM prepares changelog

The IAM prepares the log of changed identity records available to the given SP. Only those records changed since the last successful Snapshot, Changelog, or Subscription call shall be included in the changelog. The IAM shall provide all new change transactions that occurred since the SP-specified Transaction ID (excluding the specified Transaction ID).

If the SP specifies the Transaction ID of a change that it has already retrieved, the IAM shall return an "Expired Transaction ID" response code. Similarly, if the SP specifies a Transaction ID of a change that the IAM has pruned due to local policy, the SP will receive the same error.

The IAM response to the SP shall include the following:

3. SP retrieves changelog

The SP shall retrieve the changelog prepared by the IAM during step #2 by calling the Retrieval endpoint specified in the IAM's response.

Once fetched, the IAM shall not allow the SP to re-fetch the changelog via the same Retrieval endpoint.

Essential data that should be found in every changelog entry provided by the IAM:

During the identity transmission from IAM to SP, the IAM shall prevent simultaneous calls from the same SP using a locking mechanism.

If the IAM returned an error response code, the SP shall log relevant information and abort the process.

4. SP consumes changelog

The SP parses, filters (see "Validation"), merges (see "Identity Merging"), and updates its internal representation of identity information.

Validation

The SP shall validate that the data provided by the IAM meets the following criteria:

• Data conforms to the specified formats
• Any institution information listed in the identity information correctly matches the IAM's institution.
• Transaction IDs are consistent, as described in Thoughts about Interchange Formats.

The SP shall reject all data that does not pass validation prior to updating internal identity data.

Identity Merging

When identity information for one user appears in multiple IAM data sets, SPs may opt to unify the identity information using a identity merge process. Currently, there is no universal way to determine if two identity records strongly match, indicating the two records should be merged. This being said, the UC system does generate UCnetIDs for employees and some other classes of users.  UCnetIDs, when present, will uniquely identify a user across the entire UC system.  UCnetIDs will allow an employee-only SP to merge identity records, however this ID cannot be relied on for the more general SP (student, affiliate, and some non-salaried appointments).

The solution for multi-campus user provisioning does not specify a common design for merging identity records.  The design of merging identity records is left to individual SPs.

Response codes

The SP shall be capable of interpreting the following response codes sent by the IAM:

References