JWT with OAuth 2.0¶
In order to communicate with the Worldline Security Service, the Client must sign the JWT with a private key, and Worldline need to hold the public key to verify the message. Keys are valid only for a certain period of time . Worldline supports key rollover by allowing the Client to have two active key pairs.
For a practical step-by-step guide on how to acquire and use a bearer token, see the tech guide on acquiring a bearer token
Worldline creates an Application User.
The Client creates a key pair.
The Client sends the public key to Worldline.
Upon confirmation from Worldline that the key is registered with the Applioation user, you can access the service. The key must have the following properties:
|Key algorithm||RSA SHA256|
|Key length||2048 bits|
The JWT is POSTed to the OAuth token endpoint, which in turn processes the JWT, and issues an access_token based upon prior approval of the application. However, the client doesn’t need to have or store a refresh_token, nor is a client_secret required to be passed to the token endpoint.
JWT bearer flow supports the RSA SHA256 algorithm, which uses an uploaded certificate as the signing secret.
The OAuth 2.0 JWT bearer token flow involves the following general steps:
The Client registers a public key, that corresponds to the private of their application user.
The Client writes an application that generates a JWT, and signs it with their certificate.
The JWT is POSTed to the token endpoint https://.../v2/oauth2/tokens.
Worldline validates, the JWT signature, the JWT attributes, and issues an access_token
You use the bearer token to access secured Worldline APIs.
Example JWT header¶
1 2 3
1 2 3
Example JWT body¶
1 2 3 4 5 6 7
OAuth 2.0 JWT Bearer Structure¶
Figure 2 shows a JWT claim set. Detailed information of what each parameter consists are shown in the figure 2 below:
|alg||(algorithm) header value.||Yes. “RS256” or “PS256”||No|
|typ||(Type) Header Parameter||Yes. “JWT”||No|
|aud||(Audience) Claim. This identifies whom the JWT is intended for.||Yes. "drwp"||No|
|iss||The "iss" (issuer) claim identifies the principal that issued the JWT.||No||No|
|exp||The validity (exp) must be the expiration time of the JWT, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC.||No||No|
|iat||The issued at must be the time when the JWT was issued, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC.||No||No|
|consumerid||The consumer id consists of a unique end-user id who can own several devices.||No||Yes|
|scope||A delimited set of resources space separated. E.g. “OrderProcessingService:GET:/v2/merchants/||No||No|
Calling the security service with a valid JWT, will render the following result:
|token_type||Access token type. Will be “Bearer”|
|expires_in||Seconds until the access token expires.|
|number_of_retries||Number of uses of the token until it gets invalidated.|
1 2 3 4 5 6
On error, the server side may provide a response with the following parameters
|error||Categorization of error|
|error_description||A text field describing the problem|