Integrating into SSO System

To make your application/service a part of an SSO system, you must realize protocols and programming interfaces used to exchange security content between SSO system participants. Some protocols/interfaces must be added to an SP, others are optional. All obligatory interfaces/protocols are mentioned in the Obligatory protocols/interfaces sub-section of this section, the rest are mentioned in the Optional protocols/interfaces sub-section.

Before starting the implementation, you need to choose the SP base API URL - the URL that is a prefix to all programming interfaces which your SP will use to communicate with IdP (SP_BASE_API_URL in the Specification). After adding each interface, you must configure your server to properly process requests to the endpoint of the interface you added.

Obligatory protocols/interfaces

First, an SP must be able to register itself in IdP, update its registration settings, and cancel the registration. Registration in IdP is required, because this is the only way for an SP to retrieve data that will be used in further communications with IdP. The data includes an SSL certificate and a private key generated by IdP for the SP, an IdP public key, etc. The SP registration is managed via the interface called the Configuration of SP in IdP interface. This interface is consumed by an SP. For details on how to add the interface, refer to the Configuration of SP in IdP Interface section. For details on the interface, refer to the IdP Interfaces>Back Channel Interfaces> Configuration of SP in IdP Interface section of the Specification.

When the Configuration of SP in IdP interface is added, an SP is able to send to IdP information about users who want to access the SP resources. In terms of the SAML Specification, an SP is able to generate assertions for the local accounts. When IdP retrieves an assertion, it tries to identify a local account for which the assertion was created. The assertion containing results of identification is sent back from IdP to SP. Depending on the assertion contents, an SP decides to grant or deny access to a specific user for a specific resource. Syntax and semantic of assertions are defined by the Authentication Request protocol. An SP must consume an interface that uses this protocol to exchange assertions with IdP. For details on how to add such interface, refer to the Authentication Request Protocol section. For details on the protocol, refer to the Authentication in IdP section of the Specification.

According to the Authentication Request protocol, user account credentials cannot be wrapped into an assertion. That is why an SP must utilize the challenge for credentials IdP user interface via which users can enter their credentials and send them to IdP. If a user has more than one account at an SP, he must be granted an opportunity to choose the account that will be used to access a specific SP resource. This is done by selecting local account IdP user interface. Additionally, users must be able to manage/access global accounts and federated identities to cache (at IdP) local accounts available for them. Without this functionality, users cannot feel bonuses provided by SSO system (they will have to enter local accounts credentials each time a global session is opened - almost like they did before SSO support). The functionality is provided by the FI management IdP user interfaces. All IdP UIs mentioned in this paragraph are controlled by Front Channel IdP programming interface that must be consumed by an SP. For details on how to add the interface to an SP, refer to the Front Channel Interface section. For details on the operations accompanied by the IdP UIs, refer to the IdP Interfaces>Front Channel Interface section of the Specification.

Users can enter credentials either to a global or local account. First, IdP verifies the credentials against its database. If a user has entered credentials of a global account, IdP authenticates such user by its own means. If a user has entered credentials of a local account, IdP sends the credentials to the Proxied Authentication Request service of the SP that initiated the user authentication. If the SP successfully verifies the credentials, such user is also considered to be authenticated by IdP. The SP is required to have the service. Additionally, the service must provide the proxied authentication request interface. For implementation details, refer to the Proxied Authentication Request Interface section. For details on the service interface, refer to the IdP Interfaces>Back Channel Interfaces>Proxied Authentication Request Interface section of the Specification.

Optional protocols/interfaces

SPs send local account IDs to IdP in assertions. The service requires them to perform operations related to users authentication. Typically, SPs provide IdP with local account login names, but they can send any information that identifies a local account (for instance, e-mail address). If an SP supplies IdP with local account IDs different from local account login names, it must have a service that resolves the IDs to login names. This service is called local account ID mapping service. The service must provide the account identifier mapping interface. For implementation details, refer to the Local Account ID Mapping Interface section. For details on the service interface, refer to the IdP Interfaces>Back Channel Interfaces>Local Account ID Mapping Interface section of the Specification.

Once a user has authenticated to IdP, the authenticating entity establishes a global session with such user. From this moment, all local sessions opened for the user are linked with the global session. If at some later time this user wishes to terminate the global session (and thus all local sessions), the Single Logout protocol is used. You can add the interface that uses this protocol to support single logout. This interface is consumed by an SP. For details on how to add the interface, refer to the Single Logout Protocol section. For details on the protocol, refer to the Single Logout section of the Specification.