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:ConfigJwtAuthProviderConfig | ||
configAuthProvider | auth:ConfigAuthStoreProvider |
-
<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