HTTP_1_1

HTTP_2

HttpVersion

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.
```ballerina
jwt:ClientSelfSignedJwtAuthProvider provider = new({
    issuer: "wso2",
    audience: "ballerina",
    keyStoreConfig: {
        keyAlias: "ballerina",
        keyPassword: "ballerina",
        keyStore: {
            path: "/path/to/keystore.p12",
            password: "ballerina"
        }
    }
});
```


Provides authentication based on the provided JWT configurations.



init

issuerConfig

IssuerConfig

Issues a self-signed JWT for authentication.
```ballerina
string token = check provider.generateToken();
```



generateToken

Generated token or else a `jwt:Error` if an error occurred


ClientSelfSignedJwtAuthProvider

Represents the listener JWT Auth provider, which is used to authenticate the provided credentials (JWT) against
the provided JWT validator configurations.
```ballerina
jwt:ListenerJwtAuthProvider provider = new({
    issuer: "example",
    audience: "ballerina",
    signatureConfig: {
        certificateAlias: "ballerina",
        trustStore: {
            path: "/path/to/truststore.p12",
            password: "ballerina"
        }
    }
});
```


Provides authentication based on the provided JWT.



validatorConfig

ValidatorConfig

Authenticates the provided JWT.
```ballerina
boolean result = check provider.authenticate("<credential>");
```



authenticate

credential

string

`jwt:Payload` if authentication is successful or else a `jwt:Error` if an error occurred


ListenerJwtAuthProvider

HS256

HS384

HS512

NONE

RS256

RS384

RS512

## Overview

This module provides a framework for authentication/authorization with JWTs and generation/validation of JWTs as specified in the [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519), [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515), and [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).

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:

```ballerina
jwt:IssuerConfig issuerConfig = {
    username: "ballerina",
    issuer: "wso2",
    audience: "vEwzbcasJVQm1jVYHUHCjhxZ4tYa",
    expTime: 3600,
    signatureConfig: {
        config: {
            keyFile: "resource/path/to/private.key"
        }
    }
};

string jwt = check jwt:issue(issuerConfig);
```

### JWT Validator

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

```ballerina
string jwt = "eyJ0eXAiOiJKV1QiLA0KI[...omitted for brevity...]mB92K27uhbwW1gFWFOEjXk";

jwt:ValidatorConfig validatorConfig = {
    issuer: "wso2",
    audience: "vEwzbcasJVQm1jVYHUHCjhxZ4tYa",
    clockSkew: 60,
    signatureConfig: {
        certFile: "../resource/path/to/public.crt"
    }
};

jwt:Payload result = check jwt:validate(jwt, validatorConfig);
```


Represents the error type of the module. This will be returned if an error occurred while issuing/validating a JWT
or any operation related to JWT auth providers.


Error

Decodes the provided JWT into the header and payload.
```ballerina
[jwt:Header, jwt:Payload] [header, payload] = check jwt:decode(jwt);
```



decode

The `jwt:Header` and `jwt:Payload` as a tuple or else a `jwt:Error` if an error occurred


Issues a JWT based on the provided configurations. JWT will be signed (JWS) if `crypto:KeyStore` information is
provided in the `jwt:KeyStoreConfig` and the `jwt:SigningAlgorithm` is not `jwt:NONE`.
```ballerina
string jwt = check jwt:issue(issuerConfig);
```



issue

JWT as a `string` or else a `jwt:Error` if an error occurred


Validates the provided JWT, against the provided configurations.
```ballerina
jwt:Payload result = check jwt:validate(jwt, validatorConfig);
```



validate

`jwt:Payload` or else a `jwt:Error` if an error occurred


Payload

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



certFile

keyFile

Password of the private key (if encrypted)


keyPassword

CertKey

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



httpVersion

secureSocket

SecureSocket

ClientConfiguration

Cryptographic algorithm used to secure the JWS


SigningAlgorithm

Content type, convey structural information about the JWT


Key ID, hint indicating which key was used to secure the JWS


Header

JWT issuer, which is mapped to the `iss`


issuer

JWT username, which is mapped to the `sub`


username

JWT audience, which is mapped to the `aud`


audience

jwtId

keyId

customClaims

json

expTime

decimal

signatureConfig

IssuerSignatureConfig

Represents JWT signature configurations.



algorithm

KeyStore configurations, private key configurations or shared key configurations


config

Issuer, identifies the principal that issued the JWT


Subject, identifies the principal that is the subject of the JWT


Audience, identifies the recipients that the JWT is intended for


Expiration time, identifies the expiration time (seconds since the Epoch) on or after which the JWT must not be accepted


Not before, identifies the time (seconds since the Epoch) before which the JWT must not be accepted


Issued at, identifies the time (seconds since the Epoch) at which the JWT was issued


disable

boolean

Configurations associated with the `crypto:TrustStore` or single certificate file that the client trusts


cert

TrustStore

Configurations associated with the `crypto:KeyStore` or combination of certificate and private key of the client


KeyStore

Represents JWT validator configurations.



Expected issuer, which is mapped to the `iss`


Expected username, which is mapped to the `sub`


Expected audience, which is mapped to the `aud`


Expected JWT ID, which is mapped to the `jti`


Expected JWT key ID, which is mapped the `kid`


Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems


clockSkew

ValidatorSignatureConfig

Configurations related to the cache, which are used to store parsed JWT information


cacheConfig

CacheConfig

jwksConfig

clientConfig

trustStoreConfig

trustStore

certAlias

secret

This module provides a framework for authentication/authorization with JWTs and generation/validation of JWTs as specified in the [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519), [RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515), and [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).


Represents the cryptographic algorithms used to secure the JWS.


Enum: HttpVersion

Members