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.

Verifying the login status of the user

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"
}

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.

Custom SSO integration

Verifying the login status of the user

Acquiring user information

Changing the redirecturl