ballerina/auth package

Package Overview

This package provides a set of default authentication store providers that can be extended to create new authentication store providers.

Authentication Store Provider

An authentication store provider defines an authentication scheme that could be used to protect endpoints. The auth:AuthStoreProvider type acts as the interface for all the authentication providers. Any type of implementation, such as LDAP, JDBC, and file based, should be object-wise similar.

By default, there are two implementations of the auth:AuthProvider. They are, the auth:ConfigAuthProvider, which authenticates based on usernames and passwords stored in a configuration file, and the auth:JWTAuthProvider, which authenticates by validating a JWT. It is possible to implement more such authentication mechanisms.

When creating a new authentication provider, there are two functions that need to be implemented.

  • authenticate : Authenticates the user based on a credential, which can be username/password, or a token such as JWT.
  • getScopes : Provides the scopes associated with the user. Scopes are primarily permissions that are required to access a protected resource.

Config Auth Store Provider

ConfigAuthStoreProvider is an implementation of the AuthStoreProvider interface, which uses the Ballerina configuration file to store usernames, passwords, scopes and the relevant associations.

A user is denoted by a section in the configuration file. The password and the scopes assigned to the user are denoted as keys under the relevant user section as seen below.

[b7a.users.<username>]
password="<password>"
scopes="<comma_separated_scopes>"

Records Summary

Record Description
ConfigJwtAuthProviderConfig
JWTAuthProviderConfig Represents JWT validator configurations

Objects Summary

Object Description
AuthStoreProvider

Represents the auth store provider. Any type of implementation, such as LDAP, JDBC, file based, etc. should be object-wise similar

ConfigAuthStoreProvider

Represents Ballerina configuration file based auth store provider

ConfigJwtAuthProvider
JWTAuthProvider

Represents a JWT Authenticator

public type ConfigJwtAuthProviderConfig

Field Name Data Type Default Value Description
issuer string
audience string
expTime int
keyAlias string
keyPassword string
keyStoreFilePath string
keyStorePassword string
signingAlg string

public type JWTAuthProviderConfig

Represents JWT validator configurations

Field Name Data Type Default Value Description
issuer string
audience string
clockSkew int
certificateAlias string
trustStoreFilePath string
trustStorePassword string

public type AuthStoreProvider object

Represents the auth store provider. Any type of implementation, such as LDAP, JDBC, file based, etc. should be object-wise similar

  • <AuthStoreProvider> authenticate(string username, string password) returns (boolean)

    Parameter Name Data Type Default Value Description
    username string

    user name

    password string

    password

    Return Type Description
    boolean

    true if authentication is a success, else false

  • <AuthStoreProvider> getScopes(string username) returns (string[])

    Reads the scope(s) for the user with the given username

    Parameter Name Data Type Default Value Description
    username string

    user name

    Return Type Description
    string[]

    array of groups for the user denoted by the username

public type ConfigAuthStoreProvider object

Represents Ballerina configuration file based auth store provider

  • <ConfigAuthStoreProvider> authenticate(string user, string password) returns (boolean)

    Attempts to authenticate with username and password

    Parameter Name Data Type Default Value Description
    user string

    user name

    password string

    password

    Return Type Description
    boolean

    true if authentication is a success, else false

  • <ConfigAuthStoreProvider> getScopes(string username) returns (string[])

    Reads the scope(s) for the user with the given username

    Parameter Name Data Type Default Value Description
    username string

    username

    Return Type Description
    string[]

    array of groups for the user denoted by the username

  • <ConfigAuthStoreProvider> readPassword(string username) returns (string)

    Reads the password hash for a user

    Parameter Name Data Type Default Value Description
    username string

    username

    Return Type Description
    string

    password hash read from userstore, or nil if not found

  • <ConfigAuthStoreProvider> getConfigAuthValue(string instanceId, string property) returns (string)

    Parameter Name Data Type Default Value Description
    instanceId string
    property string
    Return Type Description
    string
  • <ConfigAuthStoreProvider> getArray(string groupString) returns (string[])

    Construct an array of groups from the comma separed group string passed

    Parameter Name Data Type Default Value Description
    groupString string

    comma separated string of groups

    Return Type Description
    string[]

    array of groups, nil if the groups string is empty/nil

public type ConfigJwtAuthProvider object

Field Name Data Type Default Value Description
configJwtAuthProviderConfig auth:0.0.0:ConfigJwtAuthProviderConfig
configAuthProvider auth:0.0.0:ConfigAuthStoreProvider
  • <ConfigJwtAuthProvider> new(auth:0.0.0:ConfigJwtAuthProviderConfig configJwtAuthProviderConfig)

    Parameter Name Data Type Default Value Description
    configJwtAuthProviderConfig auth:0.0.0:ConfigJwtAuthProviderConfig
  • <ConfigJwtAuthProvider> authenticate(string username, string password) returns (boolean)

    Parameter Name Data Type Default Value Description
    username string
    password string
    Return Type Description
    boolean
  • <ConfigJwtAuthProvider> getScopes(string username) returns (string[])

    Parameter Name Data Type Default Value Description
    username string
    Return Type Description
    string[]

public type JWTAuthProvider object

Represents a JWT Authenticator

Field Name Data Type Default Value Description
jwtAuthProviderConfig auth:0.0.0:JWTAuthProviderConfig
  • <JWTAuthProvider> new(auth:0.0.0:JWTAuthProviderConfig jwtAuthProviderConfig)

    Parameter Name Data Type Default Value Description
    jwtAuthProviderConfig auth:0.0.0:JWTAuthProviderConfig
  • <JWTAuthProvider> authenticate(string jwtToken) returns (boolean | error)

    Authenticate with a jwt token

    Parameter Name Data Type Default Value Description
    jwtToken string

    Jwt token extracted from the authentication header

    Return Type Description
    boolean | error

    true if authentication is a success, else false