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