By default PKIsigning uses OpenIDconnect or OAuth2.0 SSO integrations. Only if this type of integration is not possible, a fallback can be implemented using information below.

Custom SSO is a five-step process:

Integrating party redirects user to PKIsigning IDP using a preconfigured parameter.
PKIsigning IDP redirects the user back to a preconfigured url of integrating party to verify login-status of user
User is redirected back to PKIsigning IDP
PKIsigning IDP uses a backchannel API call to acquire user details
User is logged in

This guide will explain what is necessary for an integrating party to fulfull steps 2 and 4. At the end also the changes for the redirect-url of step 1 is explained.

To verify the loginstatus of the user, the PKIsigning IDP redirect the user back to a predefined url of the integrating party (e.g. https://…/getToken).

Please specify to us an url that only an authenticated user can access. We will append a query-parameter named returnUrl to that url with an encoded url.

The response of this page should be a form with method post containing a single hidden field “jwt”. The value is a token PKIsigning IDP can use in the next step to acquire user info. The page should post itself to the presented returnurl.

If the user is not logged in, a login page could be shown or a 403 error page.

By posting the form, the user is automatically redirected to the PKIsigning IDP again, which takes care of step 3 as mentioned above.

<html>
<head></head>
<body>
  <form method="post" id="jwtSubmitForm" action="https://accidentity.pkisigning.io">
    <input type="hidden" name="jwt" value="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvdGVzdC5waW5rd2ViLm5sIiwic3ViIjoiaW5pdGlhdGVHZXRVc2VySW5mb1JlcXVlc3QiLCJpYXQiOjE2MDY4MzcxNzYsImV4cCI6MTYwNjgzNzIwNiwiaGFuZHNoYWtlVG9rZW4iOiIwYmJlMTcyNDc4M2FmYjM5ZjE5NjcxZmE4MWNiOTg4NyJ9.0k3xUmzAYCcVT4HSYCaEj3gaVjeGqTeeiM4EhnhCbCo" />
  </form>
  <script type="text/javascript">
    document.getElementById('jwtSubmitForm').submit();
  </script>
</body>
</html>

Please check the returnurl you get in the queryparameter to match the pkisigning.io domain. This to prevent against open redirect url attacks.

https://owasp.org/www-project-web-security-testing-guide/v41/4-Web_Application_Security_Testing/11-Client_Side_Testing/04-Testing_for_Client_Side_URL_Redirect

Acquiring user information

The PKIsigning IDP will do a backchannel API call to acquire user information. This is done to a second url (e.g. https://…/getUserInfo), using the token as acquired in step 2 as bearer authentication method. The response of the third party should be like following snippet:

{
  "Id":"internal unique id of integrating party indicating the user parmanently",
  "Email":"emailaddress of the user",
  "Mobilephone":"mobile number of user in international format",
  "Surname":"Surname of user",
  "Firstname":"First name of the user",
  "Infix":"infix/prefix of lastname",
  "OrganisationId":"id of the organisation as can be provided by application administrator"
}

The content-type of the response should be text/json.

This backchannel call will be done immediately after the callback of step 3, so the used token doesn’t need to have a very long validity period.

Changing the redirecturl

Depending on the environment used, the user is directed to a specified PKIsigning IDP by the integrating partner: http://identity.pkisigning.io/connect/authorize?…

Please add an extra parameter named acr_values to this url. This parameter will instruct the PKIsigning IDP to skip the loginpage altogether and directly use the specified SSO integration.

http://identity.pkisigning.io/connect/authorize?…&acr_values=idp:SSO_ID

Please note the colon-sign ( : ) between idp and the SSO_ID. This should preferrably encoded as %3A.

The specified SSO_ID will be given to you by the PKIsigning development team.

PKIsigning kennisbank

Custom SSO integration

Acquiring user information

Changing the redirecturl

Verifying the login status of the user

Acquiring user information

Changing the redirecturl