Skip to content

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

Process overview

Preparations

  1. Worldline creates an Application User.

  2. The Client creates a key pair.

  3. The Client sends the public key to Worldline.

  4. Upon confirmation from Worldline that the key is registered with the Application user, you can access the service. The key must have the following properties:

Key algorithm RSA SHA256
Key length 2048 bits

Steps

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:

  1. The Client registers a public key, that corresponds to the private of their application user.

  2. The Client writes an application that generates a JWT, and signs it with their certificate.

  3. The JWT is POSTed to the token endpoint https://.../v2/oauth2/tokens.

  4. Worldline validates, the JWT signature, the JWT attributes, and issues an access_token

  5. You use the bearer token to access secured Worldline APIs.

Example JWT header

The JWT Header (PKCS#1 v1.5)
    {
        "alg": "RS256", "typ": "JWT”
    }
The JWT Header (PKCS#1 v2.1)
    {
        "alg": "PS256", "typ": "JWT”
    }

Example JWT body

Example of Body, the JWT Claim set
    {
        "aud": "drwp",
        "iss": "application-a@6512315123",
        "exp": "1521025468",
        "scope": "OrderProcessingService:POST:/v1/transactions/transfer",
        "iat": "1520939068"
    }

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:

Header Parameters

Parameter Description Predefined value Optional
alg (algorithm) header value. Yes. “RS256” or “PS256” No
typ (Type) Header Parameter Yes. “JWT” No

Claim Parameters

Parameter Description Predefined value Optional
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/{mid}/orders/{orderId}” No No

Response structure

Calling the security service with a valid JWT, will render the following result:

Parameter Description
access_token Bearer token
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.

Example response

Example respone object
    {
     "access_token": "b6afc7894e30fa3d58b319c4aca4f58dd3173bbf",
     "token_type": "Bearer",
     "expires_in": 1000,
     "number_of_retries": 10
    }

Error structure

On error, the server side may provide a response with the following parameters

Parameter Description
error Categorization of error
error_description A text field describing the problem
Back to top