Module jwt
API
ballerina/jwt Ballerina library
Functions
decode
Decodes the provided JWT into the header and payload.
[jwt:Header, jwt:Payload] [header, payload] = check jwt:decode(jwt);
Parameters
- jwt string - JWT that needs to be decoded
issue
function issue(IssuerConfig issuerConfig) returns string|ErrorIssues 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.
string jwt = check jwt:issue(issuerConfig);
Parameters
- issuerConfig IssuerConfig - JWT issuer configurations
validate
function validate(string jwt, ValidatorConfig validatorConfig) returns Payload|ErrorValidates the provided JWT, against the provided configurations.
jwt:Payload result = check jwt:validate(jwt, validatorConfig);
Parameters
- jwt string - JWT that needs to be validated
- validatorConfig ValidatorConfig - JWT validator configurations
Classes
jwt: 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.
jwt:ClientSelfSignedJwtAuthProvider provider = new({ issuer: "wso2", audience: "ballerina", keyStoreConfig: { keyAlias: "ballerina", keyPassword: "ballerina", keyStore: { path: "/path/to/keystore.p12", password: "ballerina" } } });
Constructor
Provides authentication based on the provided JWT configurations.
init (IssuerConfig issuerConfig)- issuerConfig IssuerConfig - JWT issuer configurations
generateToken
Issues a self-signed JWT for authentication.
string token = check provider.generateToken();
jwt: ListenerJwtAuthProvider
Represents the listener JWT Auth provider, which is used to authenticate the provided credentials (JWT) against the provided JWT validator configurations.
jwt:ListenerJwtAuthProvider provider = new({ issuer: "example", audience: "ballerina", signatureConfig: { certificateAlias: "ballerina", trustStore: { path: "/path/to/truststore.p12", password: "ballerina" } } });
Constructor
Provides authentication based on the provided JWT.
init (ValidatorConfig validatorConfig)- validatorConfig ValidatorConfig - JWT validator configurations
authenticate
Authenticates the provided JWT.
boolean result = check provider.authenticate("<credential>");
Parameters
- credential string - JWT to be authenticated
Constants
jwt: HS256
The HMAC-SHA256 algorithm.
jwt: HS384
The HMAC-SHA384 algorithm.
jwt: HS512
The HMAC-SHA512 algorithm.
jwt: NONE
Unsecured JWS (no signing).
jwt: RS256
The RSA-SHA256 algorithm.
jwt: RS384
The RSA-SHA384 algorithm.
jwt: RS512
The RSA-SHA512 algorithm.
Enums
jwt: HttpVersion
Represents the HTTP versions.
Members
Records
jwt: CertKey
Represents the combination of the certificate file path, private key file path, and private key password if encrypted.
Fields
- certFile string - A file containing the certificate
- keyFile string - A file containing the private key
- keyPassword? string - Password of the private key (if encrypted)
jwt: ClientConfiguration
Represents the configurations of the client used to call the JWKS endpoint.
Fields
- httpVersion HttpVersion(default HTTP_1_1) - The HTTP version of the client
- secureSocket? SecureSocket - SSL/TLS-related configurations
jwt: Header
Represents JWT header.
Fields
- alg? SigningAlgorithm - Cryptographic algorithm used to secure the JWS
- typ? string - Media type of the JWT
- cty? string - Content type, convey structural information about the JWT
- kid? string - Key ID, hint indicating which key was used to secure the JWS
jwt: IssuerConfig
Represents JWT issuer configurations.
Fields
- issuer? string - JWT issuer, which is mapped to the
iss
- username? string - JWT username, which is mapped to the
sub
- jwtId? string - JWT ID, which is mapped to the
jti
- keyId? string - JWT key ID, which is mapped the
kid
- customClaims? map<json> - Map of custom claims
- expTime decimal(default 300) - Expiry time in seconds
- signatureConfig? IssuerSignatureConfig - JWT signature configurations
jwt: IssuerSignatureConfig
Represents JWT signature configurations.
Fields
- algorithm SigningAlgorithm(default RS256) - Cryptographic signing algorithm for JWS
jwt: Payload
Represents JWT payload.
Fields
- iss? string - Issuer, identifies the principal that issued the JWT
- sub? string - Subject, identifies the principal that is the subject of the JWT
- exp? int - Expiration time, identifies the expiration time (seconds since the Epoch) on or after which the JWT must not be accepted
- nbf? int - Not before, identifies the time (seconds since the Epoch) before which the JWT must not be accepted
- iat? int - Issued at, identifies the time (seconds since the Epoch) at which the JWT was issued
- jti? string - JWT ID, unique identifier for the JWT
jwt: SecureSocket
Represents the SSL/TLS configurations.
Fields
- disable boolean(default false) - Disable SSL validation
- cert? TrustStore|string - Configurations associated with the
crypto:TrustStoreor single certificate file that the client trusts
- key? KeyStore|CertKey - Configurations associated with the
crypto:KeyStoreor combination of certificate and private key of the client
jwt: ValidatorConfig
Represents JWT validator configurations.
Fields
- issuer? string - Expected issuer, which is mapped to the
iss
- username? string - Expected username, which is mapped to the
sub
- jwtId? string - Expected JWT ID, which is mapped to the
jti
- keyId? string - Expected JWT key ID, which is mapped the
kid
- customClaims? map<json> - Expected map of custom claims
- clockSkew decimal(default 0) - Clock skew (in seconds) that can be used to avoid token validation failures due to clock synchronization problems
- signatureConfig? ValidatorSignatureConfig - JWT signature configurations
- cacheConfig? CacheConfig - Configurations related to the cache, which are used to store parsed JWT information
jwt: ValidatorSignatureConfig
Represents JWT signature configurations.
Fields
- jwksConfig? record {| url string, cacheConfig CacheConfig, clientConfig ClientConfiguration |} - JWKS configurations
- certFile? string|PublicKey - Public certificate file path or a
crypto:PublicKey
- trustStoreConfig? record {| trustStore TrustStore, certAlias string |} - JWT TrustStore configurations
- secret? string - HMAC secret configuration
Errors
jwt: Error
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.
Union types
Import
import ballerina/jwt;Metadata
Released date: 11 months ago
Version: 2.14.0
License: Apache-2.0
Compatibility
Platform: java21
Ballerina version: 2201.11.0-20241209-162400-0c015833
GraalVM compatible: Yes
Pull count
Total: 82636
Current verison: 0
Weekly downloads
Keywords
security
authentication
jwt
jwk
jws
Contributors