Standard library

jwt

ballerina/jwt

Overview

This module provides a framework for authentication/authorization with JWTs and generation/validation of JWTs as specified in the RFC 7519, RFC 7515, and RFC 7517.

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure enabling the claims to be signed digitally or protecting the integrity with a Message Authentication Code(MAC) and/or encrypted.

The Ballerina jwt module facilitates auth providers that are to be used by the clients and listeners of different protocol connectors. Also, it provides the APIs for issuing a self-signed JWT and validating a JWT.

Listener JWT Auth Provider

Represents the listener JWT Auth provider, which is used to authenticate the provided credentials (JWT) against the provided JWT validator configurations.

Client JWT Auth Provider

Represents the client JWT Auth provider, which is used to authenticate with an external endpoint by issuing a self-signed JWT against the provided JWT issuer configurations.

JWT Issuer

A self-signed JWT can be issued with the provided configurations using this API as follows:

1jwt:IssuerConfig issuerConfig = {
2    username: "ballerina",
3    issuer: "wso2",
4    audience: "vEwzbcasJVQm1jVYHUHCjhxZ4tYa",
5    expTime: 3600,
6    signatureConfig: {
7        config: {
8            keyFile: "resource/path/to/private.key"
9        }
10    }
11};
12
13string jwt = check jwt:issue(issuerConfig);

JWT Validator

A JWT can be validated with the provided configurations using the API as follows:

1string jwt = "eyJ0eXAiOiJKV1QiLA0KI[...omitted for brevity...]mB92K27uhbwW1gFWFOEjXk";
2
3jwt:ValidatorConfig validatorConfig = {
4    issuer: "wso2",
5    audience: "vEwzbcasJVQm1jVYHUHCjhxZ4tYa",
6    clockSkew: 60,
7    signatureConfig: {
8        certFile: "../resource/path/to/public.crt"
9    }
10};
11
12jwt:Payload result = check jwt:validate(jwt, validatorConfig);

Functions

[3]

decode

Decodes the provided JWT into the header and payload.

issue

Issues a JWT based on the provided configurations.

validate

Validates the provided JWT, against the provided configurations.

Classes

[2]

ClientSelfSignedJwtAuthProvider

Represents the client JWT Auth provider, which is used to authenticate with an external endpoint by issuing a self-signed JWT against the provided JWT issuer configurations.

ListenerJwtAuthProvider

Represents the listener JWT Auth provider, which is used to authenticate the provided credentials (JWT) against the provided JWT validator configurations.

Records

[9]

CertKey

Represents the combination of the certificate file path, private key file path, and private key password if encrypted.

ClientConfiguration

Represents the configurations of the client used to call the JWKS endpoint.

Represents JWT header.

IssuerConfig

Represents JWT issuer configurations.

IssuerSignatureConfig

Represents JWT signature configurations.

Payload

Represents JWT payload.

SecureSocket

Represents the SSL/TLS configurations.

ValidatorConfig

Represents JWT validator configurations.

ValidatorSignatureConfig

Represents JWT signature configurations.

Constants

[7]

HS256

The HMAC-SHA256 algorithm.

HS384

The HMAC-SHA384 algorithm.

HS512

The HMAC-SHA512 algorithm.

NONE

Unsecured JWS (no signing).

RS256

The RSA-SHA256 algorithm.

RS384

The RSA-SHA384 algorithm.

RS512

The RSA-SHA512 algorithm.

Enums

[1]

HttpVersion

Represents the HTTP versions.

Types

[1]

SigningAlgorithm

Represents the cryptographic algorithms used to secure the JWS.

Errors

[1]

Error

Represents the error type of the module.