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.
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.
The getUserInfo and getToken endpoint need to share the same path.
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.