OAuth2 provider
Authorization, in the form of an access token for use of the web services, can be provided either by local authorization or by an external OAuth2 provider (RFC 6749).
The following describes only the authorization by an external OAuth provider (which provides the tokens) when using the web services directly. The portal authorization, i.e. logging in with Single Sign On, is described under Portal.
In the case that an OAuth2 provider is to be used, this must be configured via the Admin Portal under Server > OAuth.
In this case, a configured OAuth2 provider handles the authentication of the user and provides an access token (and refresh token if required). This access token is then used and passed as authorization in a SOAP or REST web service call.
The webPDF API expects the access token in the Authorization header as Bearer token in the web service call.
Example: Calling the REST web service /converter with passing the access token (in blue) in the request header:
curl -X POST -i -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer eyJraWQiOiJyb3ZZTFQ4TXgwcTd1WW1i ... CO2TLHCiQCsuMf-1Vw' -d '{"converter": {"embedFonts": true,"jpegQuality": 90}}' http://localhost:8080/webPDF/rest/converter/605c045c129a40adb95d7623e279fe8a
The webPDF server itself does not request an access token from the OAuth2 provider. It also does not extend an access token with a refresh token.
It is the sole task of the client application to provide the corresponding access token and pass it to the API of the webPDF server. The webPDF server itself validates the token with regard to the digital signature and checks the content (claims) of the issued token. Based on this check, the appropriate authorization to use the web services is then granted.
The OAuth2 provider must be configured in the server so that the access token can be checked.
Access token format
The access token is verified based on the configuration of the OAuth2 provider. It must be a JSON Web Token (JWT) that has a digital signature, i.e. a "JSON Web Signature" (JWS) token. The signature must be based on RSA cryptography (consisting of a public and private key). The keys used must be retrievable from the OAuth2 provider based on the configuration.
Verify signature using "OIDC Discovery
To verify the digital signature of access tokens provided by an external OAuth2 provider, webPDF uses the "OIDC Discovery" standard (URL). This URL must be provided by the OAuth2 provider and configured accordingly in the Admin Portal of webPDF.
https://YOUR_DOMAIN/.well-known/openid-configuration
From the provided data, webPDF uses the entry jwks_uri (RFC 7517) to access the URL with the corresponding keys. These keys thus determined are used to check the validity of the signature.
Claims verification
If an access token is provided, then some additional values, the so-called "claims", are checked from the payload of the JWT (see RFC 7519).
In any case, the time specifications exp, nbf and iat must be correct and match the local time settings. The values aud and iss in the token must match the configured values of the OAuth2 provider. These are usually the values for application id and client id stored with the provider (names can vary with the provider).
In order to create a valid session with an external access token, the claims sub, azp and roles are also required.
roles: group assignment of the logged in user for the access permission.sub: Unique ID to form a session IDazp: Unique client ID, e.g. to uniquely identify a user (independent of his displayed user name)
Since the names of these claims vary greatly from provider to provider, the claim names can be adapted.