Keepeek - OAuth 2 / Token JWT

Presentation

This feature has been available since version 4.28.0 of the back office and allows the use of the Keepeek API with the OAuth2 protocol.
For each API call, a JWT (JSON Web Token / ID Token) containing the user's identity (the Keepeek login) is used.

Flow

Context : An application wants to use the Keepeek API with OAuth2.

1. The application generates a JWT token containing a Keepeek login and signs this token using a private key (which is also known to Keepeek).
2. For each Keepeek API call, the application sets the JWT token in the "Authorization" header as follows: Bearer .
3. Keepeek detects that a JWT token is being used and verifies its validity using the same private key.
4. If the token is valid, the user is authenticated and can use the API.

Token Generation / Signing

To generate a JWT token, there are numerous clients available for various programming languages (see the page here: https://jwt.io/#libraries-io).

Several algorithms exist for signing a token:

• HMAC : A private key is shared between the application and Keepeek.
• RSA : Private key with a public key.

Currently, only HMAC is supported by Keepeek and must use at least SHA256.
HMAC relies on a private key to sign/validate a token, so the same key must be shared between Keepeek and the application that signed the token.

⚠️ IMPORTANT: The private key must consist only of alphanumeric characters.

A JWT token consists of several parts :

• A header
• A payload (claims)
• The signature

To test/validate a token, you can use the following site: http://jwt.io/.

Here is an example of a valid Keepeek token :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJrZWVwZWVrLXRlc3QiLCJs
b2dpbiI6ImR1cG9uZCIsImlhdCI6MTYxNjIzOTAyMiwiZXhwIjoxNjE5NTk5MDIyfQ.Dq9kHJpoEi
4s_GpOqI2-9ytglUVmKz5wS02LXaRMK0I

Example of Java code for JWT generation

Here is an example of Java code using the https://github.com/auth0/java-jwt library to generate a JWT token :

Builder builder = JWT.create();
builder.withClaim("client_id", "mon-instance-keepeek");
builder.withClaim("login", "dupond");
builder.withIssuedAt(new Date());
builder.withExpiresAt(new Date(System.currentTimeMillis() + 1000 * 60));
String token = builder.sign(Algorithm.HMAC512(secretKey));