ballerina/auth package

Package Overview

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

Authentication Provider

An authentication provider defines an authentication scheme that could be used to protect endpoints. The auth:AuthProvider 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 that. They are, auth:ConfigAuthProvider which authenticates based on usernames and passwords stored in ‘ballerina.conf’, and 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 : authenticate the user based on a credential, which can be username/password or a token such as JWT.
  • getScopes : provide the scopes associated with the user. Scopes are primarily permissions that are required to access a protected resource.

Package Contents

Records Summary

Record Description
ConfigJwtAuthProviderConfig
JWTAuthProviderConfig

Represents JWT validator configurations

Objects Summary

Object Description
AuthProvider

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

ConfigAuthProvider

Represents the ballerina.conf based auth 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 AuthProvider object

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

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

  • <AuthProvider> 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 ConfigAuthProvider object

Represents the ballerina.conf based auth provider

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

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

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

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

    Parameter Name Data Type Default Value Description
    instanceId string
    property string
    Return Type Description
    string
  • <ConfigAuthProvider> 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:ConfigJwtAuthProviderConfig
configAuthProvider auth:ConfigAuthProvider
  • <ConfigJwtAuthProvider> new(auth:ConfigJwtAuthProviderConfig configJwtAuthProviderConfig)

    Parameter Name Data Type Default Value Description
    configJwtAuthProviderConfig auth: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:JWTAuthProviderConfig
  • <JWTAuthProvider> new(auth:JWTAuthProviderConfig jwtAuthProviderConfig)

    Parameter Name Data Type Default Value Description
    jwtAuthProviderConfig auth: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