BCSS - person signing: Role of Identity Proofing Service Provider (IPSP)
Abstract
The intended audience for this document is service providers assuming the role of “Identity Proofing Service Provider” This document should, together with the documents linked under Documents and regulations, contain all the details needed to create and manage the interface between Buypass Remote eSignature OIDC Server and the Identity Provider (IPSP).
Overview
For reference in the following text, the figure below shows
The services involved in the determination of End-User identity attributes
The overall control flow and data exchange when retrieving identity attributes
Step description
The Signature Creation Application (SCA) redirects the the End-User to Buypass in order to authenticate.
eSignature OIDC server delegates user authentication to an external IDP (IPSP)
The user presents an ID instrument and is authenticated
The external IDP returns tokens containing proof of authentication and ID claims to eSignature OIDC server
Optional step. eSignature OIDC server uses access-token to retrieve identity attributes / claims through the use of User info endpoint
eSignature OIDC server translates the retrieved claims in access/id-token and user-info into internal claims which are used to create the short-lived certificate for the End-User
Access/id-tokens are returned to the SCA
Authentication
The steps related to the SCA above are out of scope for the IPSP. But when the SCA initiates the authentication process with Buypass, several requests are sent to the IPSP configured for the given SCA.
The first one being, redirecting the End-User to the IPSP’s Authentication Endpoint. This is done through redirecting the User-Agent/End-User. A simple example would be something like this:
https://<IPSP-domain.no>/auth?
response_type=code
&redirect_uri=https%3A%2F%2Fauth.esign.qa-04.buypass.no%2Fauth%2Frealms%2Fesignature%2Fbroker%2F%3Cipsp%3E%2F
&state=OWhHgUpEsgOPWKElcRMNMvtJ8fCwSbL7Z_wYHlOszdU
&client_id=<ipsp configured client id>
&scope=openid....
After the IPSP has identified the user, the User-Agent is redirected back to the redirect_uri in the initial authentication request (including the state and code as query parameters):
HTTP/1.1 302 Found
Location: https://auth.esign.qa-04.buypass.no/auth/realms/esignature/broker/<ipsp>/
code=xxxxx
&state=OWhHgUpEsgOPWKElcRMNMvtJ8fCwSbL7Z_wYHlOszdU
The eSignature OIDC server will process this GET request and use the configured client credentials it has, in addition to the “code”, to acquire access/id-token. Example:
POST https://<IPSP-domain.no>/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
grant_type=authorization_code
&code=xxxxx
&redirect_uri=https%3A%2F%2Fauth.esign.qa-04.buypass.no%2Fauth%2Frealms%2Fesignature%2Fbroker%2F%3Cipsp%3E%2F
A valid response, once the token request has been validated, should be something like:
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIxNFVL...",
"expires_in": 300,
"token_type": "Bearer",
"scope": "openid"
}
OpenID Connect Configuration
The role of the IPSP is to identify the End-User and retrieve the identity attributes needed in order for Buypass to issue a valid certificate.
When the SCA asks Buypass to authenticate the End-User, we delegate that to IPSP through the authorization code flow described in the OpenID Connect Specification.
For Buypass to be able to use this we need the IPSP to support the following:
Establish a OpenID Connect client for this purpose
Client Credentials (ClientId + ClientSecret/assertion)
Offer an Authentication Endpoint (/auth)
Inform Buypass of what scopes are needed to get the relevant claims
Redirect the End-User back to Buypass given a redirect_uri configured in a white-list
Offer a Token Endpoint (/token) where Buypass can exchange the authorization code for access and id tokens
Optionally supply a api resource for getting the claims by presenting the access_token retrieved in the previous step (/user-info)
Claim mapping
Buypass collects the identity attributes for the End-User based on the IPSP’s self declared mapping table. After the IPSP has successfully identified the End-User, the user is redirected back to Buypass in accordance with the Authorization Code Flow. Buypass retrieves the access/id-token for the given user in this context, and optionally uses the access-token to fetch additional claims from the Userinfo resource provided by the the IPSP.
The Userinfo response and payload of the id-token (JWT) are both specified to be a json-structure and key-value pairs, where the values may be complex. The access-token can also be treated as a JWT and the inspected for claims in the payload if supported.
Buypass consolidates the claims collected and then uses the claim mapping to construct the data that is to be used in issuing the short lived certificate for the End-User. If the IPSP fails to provide one or several claims in the response after authentication, Buypass will alert the initiator of the process (SCA) of the error.
Table of Contents