Module jwt
API
ballerina/jwt Ballerina library
Package Overview
This package provides a listener JWT authentication provider, which can be used to authenticate the provided credentials against the provided JWT validator configurations, and a client self-signed JWT authentication provider, which can be used to authenticate against an external endpoint with a self-signed JWT issued against the provided JWT issuer configurations. Also, this module provides the functionality related to issuing and validating a JWT.
For information on the operations, which you can perform with this module, see the below Functions. For examples on the usage of the operations, see the following.
Functions
decode
Decodes the provided JWT string.
[jwt:Header, jwt:Payload]|jwt:Error [header, payload] = jwt:decode(jwt);
Parameters
- jwt string - JWT that needs to be decoded
issue
function issue(IssuerConfig issuerConfig) returns string|Error
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
.
string|jwt:Error jwt = jwt:issue(issuerConfig);
Parameters
- issuerConfig IssuerConfig - JWT issuer configurations
validate
function validate(string jwt, ValidatorConfig validatorConfig) returns Payload|Error
Validates the provided JWT, against the provided configurations.
jwt:Payload|jwt:Error result = 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.
jwt:ClientSelfSignedJwtAuthProvider provider = new({ issuer: "example", 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|auth:Error token = provider.generateToken();
jwt: ListenerJwtAuthProvider
Represents the listener JWT Auth provider, which authenticates by validating a JWT.
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 provided JWT against jwt:ValidatorConfig
.
boolean|auth:Error result = provider.authenticate("<credential>");
Parameters
- credential string - JWT to be authenticated
Constants
Enums
jwt: HttpVersion
Represents HTTP versions.
Members
Records
jwt: CertKey
Represents combination of certificate, private key 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
- username string? - JWT username, which is mapped to the
sub
- issuer string? - JWT issuer, which is mapped to the
iss
- 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
- config record {| crypto:KeyStore keyStore; string keyAlias; string keyPassword; |} |record {| string keyFile; string keyPassword?; |} ? - KeyStore configurations or private key configurations
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
- jti string? - JWT ID, unique identifier for 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
jwt: SecureSocket
Represents the SSL/TLS configurations.
Fields
- disable boolean(default false) - Disable SSL validation
- cert TrustStore|string - Configurations associated with the
crypto:TrustStore
or single certificate file that the client trusts
jwt: ValidatorConfig
Represents JWT validator configurations.
Fields
- issuer string? - Expected issuer, which is mapped to the
iss
- 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 {| string url; cache:CacheConfig cacheConfig?; ClientConfiguration clientConfig = {}; |} ? - JWKS configurations
- certFile string? - Public certificate file
- trustStoreConfig record {| crypto:TrustStore trustStore; string certAlias; |} ? - JWT TrustStore configurations
Errors
jwt: Error
Represents the JWT error. This will be returned if an error occurred while issuing/validating a JWT or any operation related to JWT.