Introduction

JSON Web Tokens (JWT) have become popular for securing APIs and managing user authentication and authorization. Understanding the structure of a JWT token is crucial for implementing secure authentication and authorization mechanisms.

A JSON Web Token (JWT) is a compact, URL-safe token format that securely transmits information between parties. The structure of a JWT token consists of three parts: Header, Payload, and Signature. These parts are encoded in Base64URL and separated by dots (.).

Keycloak, an open-source identity and access management solution, provides robust support for JWT. In this blog post, we’ll explore various strategies for validating JWT tokens in Keycloak, ensuring your applications remain secure and reliable.

Signature Verification

The most fundamental aspect of JWT validation is verifying the token’s signature. This ensures that the token has not been tampered with and is indeed issued by a trusted source. Keycloak uses asymmetric cryptography (RSA) to sign tokens, and you can verify these signatures using the public key provided by Keycloak.

Steps

• Retrieve the Public Key from Keycloak – Keycloak signs JWT tokens using its private key. To verify the token’s signature, you need the corresponding public key. This key can be retrieved from Keycloak’s JWKS (JSON Web Key Set) endpoint. https://your-keycloak-domain/auth/realms/your-realm/protocol/openid-connect/certs

• Extract the Key ID (kid) from the JWT Header – The JWT header contains a kid (Key ID) field that specifies which key was used to sign the token. This helps in selecting the correct public key for verification.

• Retrieve the Signing Key Using the Key ID – Using the kid extracted from the JWT header, retrieve the corresponding public key from the JWKS endpoint.

• Verify the JWT Signature – With the public key in hand, use a JWT library to sign the payload component of the JWT token and compare the generated signature with the signature present in the JWT token. If both the signatures are the same, then the JWT token is valid, otherwise, it’s tampered.

Token Introspection

Keycloak provides an introspection endpoint that allows one to validate tokens by making an API call. This is particularly useful for validating opaque tokens or when you need to check additional token attributes.

Steps

• First, you need to obtain the JWT token that you want to validate. This token is typically received from the client as part of the authentication process.

•  Prepare the Introspection Request – Prepare a POST request to the Keycloak introspection endpoint. One will need the client ID and client secret to authenticate the request. Send the POST request to the Keycloak introspection endpoint. Keycloak checks the validity of the token and return metadata.

Example:
curl -X POST \
  -d "token=$TOKEN" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  "$INTROSPECTION_URL"

INTROSPECTION_URL="https://your-keycloak-domain/auth/realms/your-realm/protocol/openid-connect/token/introspect"

• Analyze the Introspection Response – The response from the introspection endpoint will indicate whether the token is active (valid) and provide additional information about the token.

Example Response:

{
  "active": true,
  "exp": 1516242622,
  "iat": 1516239022,
  "sub": "1234567890",
  "aud": "your-client-id",
  "iss": "https://your-keycloak-domain/auth/realms/your-realm",
  "username": "john.doe",
  "realm_access": {
    "roles": ["user", "admin"]
  }
}

Conclusion

Validating JWT tokens is a critical aspect of securing your applications. Keycloak offers multiple strategies to ensure tokens are valid and trustworthy. By leveraging signature verification, and token introspection you can enhance the security of your applications and protect sensitive data.