JWKS

To enhance performance and minimize latencies, consider utilizing the JSON Web Key Set (JWKS) endpoint for token verification, rather than making a validation endpoint request for every transaction.

It is advised to cache our Auth-JWKS for up to 10 minutes.

Given that access tokens may be revoked, periodic validation via the validation endpoint is still necessary. Our suggested strategy is to implement JWKS verification for each request on your end, and perform a validation request to the Authentication API at least once every 5 minutes per access token.

Using JWKS to validate a token involves the following steps:

1. Retrieve the JWKS: The first step is to fetch the JWKS from the appropriate URL: https://{{tenant-space}}.auth.scayle.cloud/.well-known/jwks.json
2. Parse the JWKS: Once you have the JWKS, parse it to extract the public keys. Each key will have metadata associated with it, including the key type and use.
3. Select the Correct Key: Identify the key that corresponds to the key ID (kid) specified in the JWT header. The kid is used to indicate which key was used to sign the JWT.
4. Verify the Signature: Using the selected key, verify the digital signature on the JWT. This process will depend on the cryptographic algorithm used (e.g., RSA, ECDSA).
5. Check Token Claims: After verifying the signature, check the claims within the token to ensure it meets your application's requirements (e.g., expiration time, issuer).
6. Optional: Additional Checks: Depending on your application's requirements, you may perform additional checks, such as ensuring the token is not expired, validating the audience, or checking custom claims.

Code examples

This code assumes that the JWT is in the form of "header.payload.signature", so it extracts the header to get the key ID (kid). It then searches the JWKS for a key with a matching kid. If a matching key is found, it verifies the signature. Finally, you can add additional checks for token claims as needed for your specific application.

JavaScriptPHPcURLGoLang

Copy

// Make sure to install the required Node.js libraries by running:
// npm install axios jsonwebtoken

const axios = require('axios');
const jwt = require('jsonwebtoken');

// Step 1: Retrieve the JWKS
const jwksUrl = 'https://{{tenant-space}}.auth.scayle.cloud/.well-known/jwks.json';

axios.get(jwksUrl)
  .then(response => {
    const keys = response.data.keys;

    // Assuming you have a JWT named token to validate
    const token = 'your_jwt_token_here';

    // Step 2: Extract the key ID (kid) from the JWT header
    const jwtHeader = Buffer.from(token.split('.')[0], 'base64').toString();
    const kid = JSON.parse(jwtHeader).kid;

    // Step 3: Find the corresponding key in JWKS
    const selectedKey = keys.find(key => key.kid === kid);

    if (selectedKey) {
      // Step 4: Verify the signature
      const publicKey = `-----BEGIN PUBLIC KEY-----\n${selectedKey.x5c[0]}\n-----END PUBLIC KEY-----`;

      jwt.verify(token, publicKey, { algorithms: ['RS256'] }, (err, decoded) => {
        if (err) {
          console.error('Token verification failed!', err);
        } else {
          // Step 5: Check token claims (expiration, issuer, audience, etc.)
          // This step is application-specific and depends on your use case.

          // Step 6: Perform any additional checks if needed.
          console.log('Token is valid!');
        }
      });
    } else {
      console.log(`No matching key found for kid: ${kid}`);
    }
  })
  .catch(error => {
    console.error('Error fetching JWKS:', error);
  });