Module auth
ballerina/auth Ballerina library
Overview
This module provides a framework for authentication and authorization based on the Basic Authentication scheme specified in RFC 7617, used to define auth providers for clients and listeners of different protocol connectors.
Key Features
- File-based and LDAP-based Basic Auth providers for listeners
- Basic Auth provider for clients
- Credentials transmitted as Base64-encoded user-id/password pairs, per RFC 7617
Listener file user store Basic Auth provider
Represents the file user store based listener Basic Auth provider, which is used to authenticate the provided credentials against the provided file user store configurations. The users are denoted by a section in the Config.toml file. The username, password, and the scopes of a particular user are denoted as keys under the users section as shown below. For multiple users, the complete section has to be duplicated.
[[ballerina.auth.users]] username="alice" password="xxx" scopes=["read", "write"]
Listener LDAP user store Basic Auth provider
Represents the LDAP-based listener Basic Auth provider, which is used to authenticate the provided credentials against the provided LDAP user store configurations. This connects to an active directory or an LDAP, which retrieves the necessary user information and performs authentication and authorization.
Client Basic Auth provider
Represents the client Basic Auth provider, which is used to authenticate with an external endpoint by generating a Basic Auth token against the provided credential configurations.
Functions
extractUsernameAndPassword
Extracts the username and the password from the Base64-encoded username:password value.
[string, string] [username, password] = check auth:extractUsernameAndPassword("<credential>");
Parameters
- credential string - The Base64-encoded
username:passwordvalue
Classes
auth: ClientBasicAuthProvider
Represents the client Basic Auth provider, which is used to authenticate with an external endpoint by generating a Basic Auth token against the provided credential configurations.
auth:CredentialsConfig config = { username: "tom", password: "123" } auth:ClientBasicAuthProvider provider = new(config);
Constructor
Provides authentication based on the provided Basic Auth configurations.
init (CredentialsConfig credentialsConfig)- credentialsConfig CredentialsConfig - Credentials configuration
generateToken
Generates a Base64-encoded token for Basic Auth authentication.
string token = check provider.generateToken();
auth: ListenerFileUserStoreBasicAuthProvider
Represents the file user store based listener Basic Auth provider, which is used to authenticate the provided credentials against the provided file user store configurations.
auth:ListenerFileUserStoreBasicAuthProvider provider = new;
The users are denoted by a section in the Config.toml file. The username, password, and the scopes of a particular
user are denoted as keys under the users section as shown below. For multiple users, the complete section has to be
duplicated.
[[ballerina.auth.users]] username = "alice" password = "password1" scopes = ["scope1", "scope2"]
Constructor
Provides authentication based on the provided configurations.
init (FileUserStoreConfig fileUserStoreConfig)- fileUserStoreConfig FileUserStoreConfig {} - file user store configurations
authenticate
function authenticate(string credential) returns UserDetails|ErrorAuthenticate the Base64-encoded username:password credentials.
auth:UserDetails result = check provider.authenticate("<credential>");
Parameters
- credential string - The Base64-encoded
username:passwordvalue
Return Type
- UserDetails|Error -
auth:UserDetailsif the authentication is successful or else anauth:Errorif an error occurred
auth: ListenerLdapUserStoreBasicAuthProvider
Represents the LDAP-based listener Basic Auth provider, which is used to authenticate the provided credentials against the provided LDAP user store configurations. This connects to an active directory or an LDAP, retrieves the necessary user information, and performs authentication and authorization.
auth:LdapUserStoreConfig config = { domainName: "ballerina.io", connectionURL: "ldap://localhost:389", connectionName: "cn=admin,dc=avix,dc=lk" }; auth:ListenerLdapUserStoreBasicAuthProvider provider = new(config);
Constructor
Creates an LDAP auth store with the provided configurations.
init (LdapUserStoreConfig ldapUserStoreConfig)- ldapUserStoreConfig LdapUserStoreConfig - The LDAP user store configurations
authenticate
function authenticate(string credential) returns UserDetails|ErrorAttempts to authenticate the Base64-encoded username:password credentials.
auth:UserDetails result = check provider.authenticate("<credential>");
Parameters
- credential string - The Base64-encoded
username:passwordvalue
Return Type
- UserDetails|Error -
auth:UserDetailsif the authentication is successful or else anauth:Errorif an error occurred
Configurables
Records
auth: CredentialsConfig
Represents credentials for Basic Auth authentication.
Fields
- username string - Username for Basic Auth authentication
- password string - Password for Basic Auth authentication
auth: FileUserStoreConfig
Represents the file user store configurations.
auth: LdapUserStoreConfig
Represents the LDAP user store configurations.
Fields
- domainName string - Unique name to identify the user store
- connectionUrl string - Connection URL of the LDAP server
- connectionName string - The username used to connect to the LDAP server
- connectionPassword string - The password used to connect to the LDAP server
- 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, which contains the distinguished names (DN) of user objects that are there in a group
- userRolesCacheEnabled boolean(default false) - To indicate whether to cache the role list of a user
- connectionPoolingEnabled boolean(default true) - Define whether LDAP connection pooling is enabled
- connectionTimeout decimal(default 5) - Connection timeout (in seconds) when making the initial LDAP connection
- readTimeout decimal(default 60) - Reading timeout (in seconds) for LDAP operations
- secureSocket? SecureSocket - The SSL configurations for the LDAP client socket. This needs to be configured in order to communicate through LDAPs
auth: SecureSocket
Represents the SSL/TLS configurations.
Fields
- cert TrustStore|string - Configurations associated with the
crypto:TrustStoreor single certificate file that the client trusts
auth: UserDetails
Represents the details of the authenticated user.
Fields
- username string - The username of the authenticated user
- scopes? string[] - The scopes of the authenticated user
Errors
auth: Error
Represents the error type of the module. This will be returned if an error occurred while any of the listener Basic Auth providers try to authenticate the received credentials and client Basic Auth providers try to generate the token.
Object types
auth: ListenerBasicAuthProvider
Represents the listener Basic Auth provider, which could be used to authenticate credentials.
The auth:ListenerBasicAuthProvider acts as the interface for all the Basic Auth listener authentication providers.
Any type of implementation such as file store, LDAP user store, in memory user store, JDBC user store etc. should be
object-wise similar.
authenticate
function authenticate(string credential) returns UserDetails|ErrorAuthenticates the user based on the user credentials (i.e., the username/password).
Parameters
- credential string - The
stringcredential value
Return Type
- UserDetails|Error -
auth:UserDetailsif the authentication is successful or else anauth:Errorif an error occurred