Authentication

This chapter will describe the basics in authenticating with PKIsigning.

OpenID Connect

PKIsigning is using the OpenID Connect (OIDC) standard for authentication. OIDC extends the OAuth 2.0 authorization protocol for use also as an authentication protocol.

The full specification for OIDC is available on the OpenID Foundation’s website at OpenID Connect Core 1.0 specification.

End-user authentication

The authentication flow of OIDC 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.
OIDC will work in the same manner.

For ASP.Net middleware libraries are available to easily integrate with OIDC. Also for PHP some libraries are available to authenticate. For more information please check http://openid.net/developers/certified.y

Endpoints

The PKIsigning authentication server listens on endpoint https://identity.pkisigning.io.
For development purposes, please use our staging endpoint: https://accidentity.pkisigning.io.

Protocol flow

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 authentication server. 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, which is required for OIDC. For platform integration, the “pkisigning.platform” scope is required.

For signing pdf documents directly with our engine (not required for 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.

For security purposes, the authentication information as supplied by PKIsigning will differ between production and staging environments. Please do not store PKIsigning credentials in config files in clear text.

Fetch the OpenID configuration document

OpenID providers like the PKIsigning authentication server provide an OpenID Provider Configuration Document at a publicly accessible endpoint containing the provider's OIDC endpoints, supported claims, and other metadata. Client applications can use the metadata to discover the URLs to use for authentication and the authentication service's public signing keys, among other things.

Authentication libraries are the most common consumers of the OpenID configuration document, which they use for discovery of authentication URLs, the provider's public signing keys, and other service metadata. If you use an authentication library in your app (recommended), you likely won't need to hand-code requests to and responses from the OpenID configuration document endpoint.

The PKIsigning configuration document is located at https://identity.pkisigning.io/.well-known/openid-configuration.

Authentication flow

When a user wants to sign a document, it will have to authenticate itself with the
authentication server. 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.

Please direct the browser of the user to the following url (line-breaks included for readability only)

GET https://identity.pkisigning.io/connect/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid%20pkisigning.platform
&state=12345
&nonce=678910

The nature of OIDC is to use credentials only at the authentication page of the supplier of these credentials. Therefore it is not possible to send credentials directly from any third party application. The authentication page has to be shown to the end-user.

The use of the PKIsigning authentication page in an iframe has been explicitly blocked to prevent clickjacking and overlay attacks.

After being authenticated on our identity server, the user will be redirected back to an url of
the application. In the query string a code parameter will be specified, which is required to obtain an accesstoken.

To prevent redirection attacks, redirect urls need to be whitelisted. Please provide our
technical team with the URL(s) for your application. Multiple redirect urls are allowed per
application.

Obtaining an access token

After the user has been redirect back to the application, use the code specified in the query string to obtain an access token. The values in the request should match the values being sent earlier to redirect the user to the PKIsigning authentication page.

// Line breaks for readability only

POST /connect/token HTTP/1.1
Host: https://identity.pkisigning.io
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=openid%20pkisigning.platform
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: This secret needs to be URL-Encoded.

A successful result will return the following result.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "openid%20pkisigning.platform",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",    // OPTIONAL
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

For common error responses, please check the table below:

Error Code	Description	Client Action

Error Code	Description	Client Action
`invalid_request`	Protocol error, such as a missing required parameter.	Fix the request or app registration and resubmit the request.
`invalid_grant`	The authorization code or PKCE code verifier is invalid or has expired.	Try a new request to the `/authorize` endpoint and verify that the `code_verifier` parameter was correct.
`unauthorized_client`	The authenticated client isn't authorized to use this authorization grant type.	This error usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. The application can prompt the user with instruction for installing the application and adding it to Azure AD.
`invalid_client`	Client authentication failed.	The client credentials aren't valid. To fix, the application administrator updates the credentials.
`unsupported_grant_type`	The authorization server doesn't support the authorization grant type.	Change the grant type in the request. This type of error should occur only during development and be detected during initial testing.
`interaction_required`	Non-standard, as the OIDC specification calls for this code only on the `/authorize` endpoint. The request requires user interaction. For example, another authentication step is required.	Retry the `/authorize` request with the same scopes.
`temporarily_unavailable`	The server is temporarily too busy to handle the request.	Retry the request after a small delay. The client application might explain to the user that its response is delayed because of a temporary condition.
`consent_required`	The request requires user consent. This error is non-standard. It's usually only returned on the `/authorize`endpoint per OIDC specifications. Returned when a `scope` parameter was used on the code redemption flow that the client app doesn't have permission to request.	The client should send the user back to the `/authorize` endpoint with the correct scope to trigger consent.
`invalid_scope`	The scope requested by the app is invalid.	Update the value of the `scope` parameter in the authentication request to a valid value.

For security reasons it is not possible to send a request for obtaining an access token from a browser. This would require having the client secret available in an untrusted environment. Webbrowsers will block these requests because of CORS policy violation errors.

Refresh tokens

As access tokens only have a short lifespan, they should be refreshed at a regular interval. To prevent round tripping to the authentication server for the user, refresh tokens can be used. Now users can stay logged in longer without having to sign in each time. This will also allow for executing background tasks as downloading requests when they are completed.

To use refresh tokens, please add “offline_access” to the list of scopes. As this scope is not enabled by default, please contact our technical team to have it enabled.

When obtaining an access token, also a refresh token is generated. Refresh tokens have a longer lifespan and should be stored for future usage (e.g. windows registry or database).

// Line breaks for readability only

POST /connect/token HTTP/1.1
Host: https://identity.pkisigning.io
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=openid%20pkisigning.platform
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: This secret needs to be URL-Encoded

This should produce a response like the following:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "openid%20pkisigning.platform",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Please note that a new refresh token is sent as well. The old refresh token has been invalidated and the new refresh token should be stored for future use.

PKIsigning kennisbank