This chapter will describe the basics in authenticating with PKIsigning.
...
OpenID Connect
PKIsigning uses the opensource solution ThinkTecture IdentityServer 4 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 4 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.
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 OpenId Connect 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.
OpenId Connect OIDC 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 IdentityServerOIDC. Also for PHP some middleware libraries are available to
authenticate against OpenId Connect. For more information please check
http://openid.net/developers/certified.y
| Informatie |
|---|
Endpoints The PKIsigning authentication server listens on endpoint https://identity.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 identity platformauthentication 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 token_id token” “code” as response type.
| Informatie |
|---|
| Urgent |
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.
| Informatie |
|---|
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
identityserverauthentication 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)
| Codeblok |
|---|
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 |
| Tip |
|---|
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. |
| Informatie |
|---|
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.
| Urgent |
|---|
To prevent redirection attacks, |
...
redirect urls |
...
need to be whitelisted. Please provide our |
After authentication, an access token can be requested by a secondary call, probably
automated by the used middleware.
| Informatie |
|---|
For an example request for obtaining an accesstoken, see: https://identityserver4.readthedocs.io/en/latest/endpoints/token.html |
All url’s needed are provided at the default discovery endpoint for OpenId Connect clients: https://identity.pkisigning.io/.well-known/openid-configuration
...
More information on OpenIdConnect
...
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.
...
| Codeblok | ||
|---|---|---|
| ||
// 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.
| Codeblok | ||
|---|---|---|
| ||
{
"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 |
|---|---|---|
| Protocol error, such as a missing required parameter. | Fix the request or app registration and resubmit the request. |
| The authorization code or PKCE code verifier is invalid or has expired. | Try a new request to the |
| 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. |
| Client authentication failed. | The client credentials aren't valid. To fix, the application administrator updates the credentials. |
| 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. |
| Non-standard, as the OIDC specification calls for this code only on the | Retry the |
| 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. |
| The request requires user consent. This error is non-standard. It's usually only returned on the | The client should send the user back to the |
| The scope requested by the app is invalid. | Update the value of the |
| Informatie |
|---|
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).
| Codeblok | ||
|---|---|---|
| ||
// 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:
| Codeblok | ||
|---|---|---|
| ||
{
"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.