Authentication

This chapter will describe the basics in authenticating with PKIsigning.

IdentityServer

PKIsigning uses the opensource solution ThinkTecture IdentityServer to authenticate users
and API clients. This solution enables PKIsigning to easily manage users and clients and
provides authentication standards to third parties eliminating the need for custom build
scenarios.

IdentityServer is built on ASP.Net Core 2.0, enabling cross-platform support and easy
migration to the Microsoft Azure platform.

The PKIsigning identityserver is located at the following URL: https://identity.pkisigning.io
and has been equipped with an Extended Validation SSL certificate (green address bar). For
development purposes, we will provide accounts on our staging environment which is
located at the following URL: https://accidentity.pkisigning.io.

OpenId Connect

IdentityServer is an authentication solution for OpenId Connect authentication. OpenId
Connect is a successor of OAuth 2.0. Whereas OAuth 2.0 is very suitable for end-user
authentication, it is less suitable for server to server authentication.

End-user authentication

The authentication flow of OpenId Connect is most easily compared to logging in with a
Google or Facebook account. The end-user is redirect to a page of a trusted party and is then
asked to provide credentials and will possibly see a consent screen to allow sharing of
personal data with the calling party. It is to the end-user to either disclose the data or not.
OpenId Connect will work in the same manner.

For ASP.Net 4.x and ASP.Net Core 1.x and 2.0 middleware libraries are available to easily
integrate with IdentityServer. Also for PHP some middleware libraries are available to
authenticate against OpenId Connect. For more information please check
http://openid.net/developers/certified.

Client authentication

Every application using the PKIsigning API is considered a client. A client will receive its own
clientid and clientsecret which are required to establish a server to server connection with
our identity platform. Please contact our technical team to acquire your credentials.

A connection is created based on scopes. Scopes are areas of functionality to which the enduser
will grant the client access to.

Every client should request the “openid” scope. For platform integration, also the “pkisigning.platform” scope is required.

For signing pdf documents directly with our engine (no platform integration), the client should
request the “pkisigningAPI.signpdf” scope. To sign XBRL, the client should request the
“pkisigningAPI.signxbrl” scope.

An authentication request should also use “code” as response type.

Authentication flow

When a user wants to sign a document, it will have to authenticate itself with the
identityserver. Based on the API used, a call will be issues to the user_info endpoint to
request the information of the logged-in user. When the user_info returns that the user is
not logged in, an authentication flow should be started. Depending on the middleware used,
this call is probably performed automatically.

After being authenticated on our identity server, the user will be redirected back to an url of
the application. To prevent redirection attacks, these urls are whitelisted. Please provide our
technical team with the URL(s) for your application. Multiple redirect urls are allowed per
application.

After authentication, an access token can be requested by a secondary call, probably
automated by the used middleware.

All url’s needed are provided at the default discovery endpoint for OpenId Connect clients: https://identity.pkisigning.io/.well-known/openid-configuration