ballerina/auth module

Module Overview

This module 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
InferredJwtAuthProviderConfig Represents authentication provider configurations that supports generating JWT for client interactions.
JWTAuthProviderConfig Represents JWT validator configurations
LdapAuthProviderConfig Represents configurations that required for LDAP auth store.
SecureClientSocket Configures the SSL/TLS options to be used for LDAP communication.
TrustStore A record for providing trust store related 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

LdapAuthStoreProvider

Represents Ballerina configuration for LDAP based auth store provider

LdapJwtAuthProvider

Represents LDAP authentication provider that supports generating JWT for client interactions

Functions Summary

Return Type Function and Description
initLdapConnectionContext(auth:LdapAuthStoreProvider ldapAuthStoreProvider, string instanceId)

Initailizes LDAP connection context

public type InferredJwtAuthProviderConfig record

Represents authentication provider configurations that supports generating JWT for client interactions.

Field Name Data Type Default Value Description
issuer string

Expected JWT token issuer

audience string

Expected JWT token audience

expTime int

Expiry time for newly issued JWT tokens

keyAlias string

Key alias for signing newly issued JWT tokens

keyPassword string

Key password for signing newly issued JWT tokens

keyStoreFilePath string

Path to the key-store file containing signing key

keyStorePassword string

Password of the key-store file containing signing key

signingAlg string

Signing algorithm for signing newly issued JWT tokens

public type JWTAuthProviderConfig record

Represents JWT validator configurations

Field Name Data Type Default Value Description
issuer string

Identifier of the token issuer

audience string

Identifier of the token recipients

clockSkew int

Time in seconds to mitigate clock skew

certificateAlias string

Token signed key alias

trustStoreFilePath string

Path to the trust store file

trustStorePassword string

Trust store password

public type LdapAuthProviderConfig record

Represents configurations that required for LDAP auth store.

Field Name Data Type Default Value Description
domainName string

Unique name to identify the user store

connectionURL string

Connection URL to the LDAP server

connectionName string

The username used to connect to the LDAP server

connectionPassword string

Password for the ConnectionName user

userSearchBase string

DN of the context or object under which the user entries are stored in the LDAP server

userEntryObjectClass string

Object class used to construct user entries

userNameAttribute string

The attribute used for uniquely identifying a user entry

userNameSearchFilter string

Filtering criteria used to search for a particular user entry

userNameListFilter string

Filtering criteria for searching user entries in the LDAP server

groupSearchBase string[]

DN of the context or object under which the group entries are stored in the LDAP server

groupEntryObjectClass string

Object class used to construct group entries

groupNameAttribute string

The attribute used for uniquely identifying a group entry

groupNameSearchFilter string

Filtering criteria used to search for a particular group entry

groupNameListFilter string

Filtering criteria for searching group entries in the LDAP server

membershipAttribute string

Define the attribute that contains the distinguished names (DN) of user objects that are in a group

userRolesCacheEnabled boolean false

To indicate whether to cache the role list of a user

connectionPoolingEnabled boolean true

Define whether LDAP connection pooling is enabled

ldapConnectionTimeout int 5000

Timeout in making the initial LDAP connection

readTimeout int 60000

The value of this property is the read timeout in milliseconds for LDAP operations

retryAttempts int 0

Retry the authentication request if a timeout happened

secureClientSocket auth:SecureClientSocket?

The SSL configurations for the ldap client socket. This needs to be configured in order to communicate through ldaps.

public type SecureClientSocket record

Configures the SSL/TLS options to be used for LDAP communication.

Field Name Data Type Default Value Description
trustStore auth:TrustStore?

Configures the trust store to be used

trustedCertFile string

A file containing a list of certificates or a single certificate that the client trusts

public type TrustStore record

A record for providing trust store related configurations.

Field Name Data Type Default Value Description
path string

Path to the trust store file

password string

Trust store password

public function initLdapConnectionContext(auth:LdapAuthStoreProvider ldapAuthStoreProvider, string instanceId)

Initailizes LDAP connection context

Parameter Name Data Type Default Value Description
ldapAuthStoreProvider auth:LdapAuthStoreProvider

LdapAuthStoreProvider provider object

instanceId string

Unique id generated to identify an endpoint

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)

    Authenticate with username and password

    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:InferredJwtAuthProviderConfig
configAuthProvider auth:ConfigAuthStoreProvider
  • <ConfigJwtAuthProvider> new(auth:InferredJwtAuthProviderConfig configJwtAuthProviderConfig)

    Parameter Name Data Type Default Value Description
    configJwtAuthProviderConfig auth:InferredJwtAuthProviderConfig
  • <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:JWTAuthProviderConfig

JWT authentication provider configurations

  • <JWTAuthProvider> new(auth:JWTAuthProviderConfig jwtAuthProviderConfig)

    Provides authentication based on the provided jwt token

    Parameter Name Data Type Default Value Description
    jwtAuthProviderConfig auth:JWTAuthProviderConfig

    JWT authentication provider configurations

  • <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 successful, false otherwise. If an error occur during authentication, the error will be returned.

public type LdapAuthStoreProvider object

Represents Ballerina configuration for LDAP based auth store provider

Field Name Data Type Default Value Description
ldapAuthProviderConfig auth:LdapAuthProviderConfig

LDAP auth store configurations

instanceId string

Endpoint instance id

  • <LdapAuthStoreProvider> new(auth:LdapAuthProviderConfig ldapAuthProviderConfig, string instanceId)

    Create an LDAP auth store with the given configurations.

    Parameter Name Data Type Default Value Description
    ldapAuthProviderConfig auth:LdapAuthProviderConfig

    LDAP auth store configurations

    instanceId string

    Endpoint instance id

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

    Authenticate with username and password

    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

  • <LdapAuthStoreProvider> 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

  • <LdapAuthStoreProvider> doAuthenticate(string username, string password) returns (boolean)

    Authenticate with username and password

    Parameter Name Data Type Default Value Description
    username string
    password string

    password

    Return Type Description
    boolean

    true if authentication is a success, else false

  • <LdapAuthStoreProvider> getScopesOfUser(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

public type LdapJwtAuthProvider object

Represents LDAP authentication provider that supports generating JWT for client interactions

Field Name Data Type Default Value Description
ldapJwtAuthProviderConfig auth:InferredJwtAuthProviderConfig

JWT configurations

ldapAuthProvider auth:LdapAuthStoreProvider

LDAP auth store provider

  • <LdapJwtAuthProvider> new(auth:InferredJwtAuthProviderConfig ldapJwtAuthProviderConfig, auth:LdapAuthStoreProvider ldapAuthProvider)

    Provides authentication based on the configured LDAP user store

    Parameter Name Data Type Default Value Description
    ldapJwtAuthProviderConfig auth:InferredJwtAuthProviderConfig

    Configuration for JWT token propagation

    ldapAuthProvider auth:LdapAuthStoreProvider

    LDAP auth store provider

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

    Authenticate with username and password using LDAP user store

    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

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

    Reads the scope(s) for the user with the given username from LDAP user store

    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