Module : auth

Module Overview

This module provides default authentication provider configurations that can be extended to create new authentication providers.

Inbound Authentication Provider

An inbound authentication provider defines an authentication scheme that could be used to authenticate endpoints. The auth:InboundAuthProvider acts as the interface for all the inbound authentication providers. Any type of implementation such as LDAP, JDBC, JWT, OAuth2, and file-based should be object-equivalent.

When creating a new inbound authentication provider, you need to implement the below function.

Inbound Basic Auth Provider

The auth:InboundBasicAuthProvider is an implementation of the auth:InboundAuthProvider interface, which uses the Ballerina configuration file to read usernames, passwords, scopes, and the relevant associations.

auth:InboundBasicAuthProvider basicAuthProvider = new;

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 shown below.

[b7a.users.<username>]
password="<password>"
scopes="<comma_separated_scopes>"

Outbound Authentication Provider

An outbound authentication provider defines an authentication scheme that could be used to authenticate external endpoints. The auth:OutboundAuthProvider acts as the interface for all the outbound authentication providers. Any type of implementation such as JDBC, JWT, OAuth2, and file-based should be object-equivalent.

When creating a new outbound authentication provider, you need to implement the below functions.

Outbound Basic Auth Provider

The auth:OutboundBasicAuthProvider is an implementation of the auth:OutboundAuthProvider interface, which uses usernames and passwords provided Ballerina configurations to authenticate external endpoints.

auth:OutboundBasicAuthProvider basicAuthProvider = new({
    username: "tom",
    password: "123"
});

Records

BasicAuthConfig The `BasicAuthConfig` record can be used to configure inbound Basic Authentication configurations.
Credential The `Credential` record can be used to configure Basic Authentication, which is used by the HTTP endpoint.

Objects

InboundAuthProvider

Represents the inbound Auth provider. Any type of implementation such as JWT, OAuth2, LDAP, JDBC, file-based etc. should be object-wise similar.

InboundBasicAuthProvider

Represents the inbound basic Auth provider, which is a configuration-file-based Auth provider.

OutboundAuthProvider

Represents the outbound Auth provider. Any type of implementation such as JWT and OAuth2 should be object-wise similar to the OutboundAuthProvider object.

OutboundBasicAuthProvider

Represents the outbound Basic Auth authenticator.

Functions

checkForScopeMatch

Check whether the scopes of the user and scopes of resource matches.

extractUsernameAndPassword

Extracts the username and password from the credential values.

prepareError

Log and prepare error as a Error.

setAuthenticationContext

Set the authentication related values (scheme, auth token) to the authentication context of the invocation context.

setPrincipal

Set the authentication related values (user id, username, scopes, claims) to the principal of the invocation context.

Constants

AUTH_ERROR

Represents the Auth error reason.

DEFAULT_CHARSET

Default charset to be used with password hashing.

CONFIG_PREFIX

Prefix used to denote special configuration values.

CONFIG_PREFIX_SHA256

Prefix used to denote that the config value is a SHA-256 hash.

CONFIG_PREFIX_SHA384

Prefix used to denote that the config value is a SHA-384 hash.

CONFIG_PREFIX_SHA512

Prefix used to denote that the config value is a SHA-512 hash.

AUTH_SCHEME_BASIC

Prefix used to denote Basic Authentication scheme.

AUTH_SCHEME_BEARER

Prefix used to denote Bearer Authentication scheme.

Errors

Error

Represents the Auth error type with details. This will be returned if an error occurred while inbound auth providers try to authenticate the received credentials and outbound auth providers try to generate the token.