Module auth
API
Declarations
ballerina/auth Ballerina library
Package Overview
This package provides listener Basic authentication providers, which can be used to authenticate the provided credentials against a file user store or an LDAP user store, and a client Basic authentication provider, which can be used to authenticate against an external endpoint.
For information on the operations, which you can perform with this package, see the below Functions. For examples on the usage of the operations, see the following.
Functions
extractUsernameAndPassword
Extracts the username and the password from the base64-encoded username:password
value.
[string, string]|auth:Error [username, password] = auth:extractUsernameAndPassword("<credential>");
Parameters
- credential string - Base64-encoded
username:password
value
Classes
auth: ClientBasicAuthProvider
Represents the client Basic Auth provider. This uses the auth:CredentialsConfig
configurations provided and generes
the token for Basic Auth authentication.
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 - Credential configurations
generateToken
Generates a token for Basic Auth authentication.
string|auth:Error token = provider.generateToken();
auth: ListenerFileUserStoreBasicAuthProvider
Represents the file user store based listener Basic Auth provider, which is an implementation of the
auth:ListenerBasicAuthProvider
object.
auth:ListenerFileUserStoreBasicAuthProvider provider = new;
The users are denoted by a section in the Ballerina configurations 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.
[[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|Error
Authenticate the base64-encoded username:password
credentials.
auth:UserDetails|auth:Error result = provider.authenticate("<credential>");
Parameters
- credential string - Base64-encoded
username:password
value
Return Type
- UserDetails|Error -
auth:UserDetails
if the authentication is successful,auth:Error
in case of an error of authentication failure
Fields
- Fields Included from * ListenerBasicAuthProvider
auth: ListenerLdapUserStoreBasicAuthProvider
Represents the LDAP based listener Basic Auth provider. This connects to an active directory or an LDAP,
retrieves the necessary user information, and performs authentication and authorization. This is an implementation
of the auth:ListenerBasicAuthProvider
object.
auth:LdapUserStoreConfig config = { domainName: "ballerina.io", connectionURL: "ldap://localhost:389", connectionName: "cn=admin,dc=avix,dc=lk" }; auth:ListenerLdapUserStoreBasicAuthProvider provider = new(config);
A user is denoted by a section in the Ballerina configuration file. The password and the scopes assigned to the user are denoted as keys under the relevant user section as shown below.
[b7a.users.<username>] password="<password>" scopes="<comma_separated_scopes>"
Constructor
Creates an LDAP auth store with the provided configurations.
init (LdapUserStoreConfig ldapUserStoreConfig)
- ldapUserStoreConfig LdapUserStoreConfig - The
auth:LdapUserStoreConfig
instance
authenticate
function authenticate(string credential) returns UserDetails|Error
Attempts to authenticate the base64-encoded username:password
credentials.
auth:UserDetails|auth:Error result = provider.authenticate("<credential>");
Parameters
- credential string - Base64-encoded
username:password
value
Return Type
- UserDetails|Error -
auth:UserDetails
if the authentication is successful,auth:Error
in case of an error of authentication failure
Fields
- Fields Included from * ListenerBasicAuthProvider
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 configurations that are required for an LDAP user store.
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
Configures the SSL/TLS options to be used for LDAP communication.
Fields
- cert TrustStore|string - Configurations associated with the
crypto:TrustStore
or 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 Auth error. 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 provider 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|Error
Authenticates the user based on the user credentials (i.e., the username/password).
Parameters
- credential string - The
string
credential value
Return Type
- UserDetails|Error -
auth:UserDetails
if the authentication is successful,auth:Error
in case of an error of authentication failure