Refactor outbound authentication with custom providers and handlers

[ldclakmal]

Purpose

This PR provides the capability of custom authentication providers and handlers engagement for outbound authentication. The current design of HTTP outbound authentication is not extensible. Also, it creates cyclic dependencies, in future (ex: When adding JWKs support). And the user cannot attach a custom provider and handler because the authentication mechanisms and their related logic are tightly coupled with the http_secure_client of Ballerina.

This is a similar approach done at refactoring inbound authentication with custom providers and handlers by #15056.

Refer the email discussion @ ballerina-dev [1] for more information.
[1] https://groups.google.com/d/msg/ballerina-dev/OvlUscsjT-I/VmTTBg-DBAAJ

Fixes #15487

Approach

• ballerina/auth module provides an abstract object named OutboundAuthProvider, which is responsible for the following 2 actions:
  • generateToken() - Generate the token that is used to authenticate with the external endpoint
  • inspect(map<anydata> data) - Inspect the received map of data from outbound authentication
• auth:OutboundBasicAuthProvider, jwt:OutboundJwtAuthProvider and oauth2:OutboundOAuth2Provider are implementations of the auth:OutboundAuthProvider for different authentication mechanisms.

---

• ballerina/http module provides an abstract object named OutboundAuthnHandler, which is responsible for the following 2 actions:
  • prepare(http:Request req) - Prepare the HTTP request for outbound authentication
  • inspect(http:Request req, http:Response resp) - Inspect the received HTTP request and response from outbound authentication
• http:BasicAuthHandler and http:BearerAuthHandler are implementations of the http:OutboundAuthHandler for different use cases.

---

If a user wants to engage a custom authentication logic, it is needed to write an outbound custom auth provider and outbound custom auth handler as follows. Or else already implemented handlers and providers can be used.

Outbound Custom Auth Provider

import ballerina/auth;

public type OutboundCustomAuthProvider object {

    *auth:OutboundAuthProvider;

    public function generateToken() returns string|error {
        // Logic related to generating the tokens for outbound authentication
    }

    public function inspect(map<anydata> data) returns string|error? {
        // Logic related to inspect the provided the tokens for outbound authentication
    }
}

Outbound Custom Auth Handler

import ballerina/auth;
import ballerina/http;

public type OutboundCustomAuthHandler object {

    *http:OutboundAuthHandler;

    public auth:OutboundAuthProvider authProvider;

    public function __init(auth:OutboundAuthProvider authProvider) {
        self.authProvider = authProvider;
    }

    public function prepare(Request req) returns Request|error {
        // Logic related to preparing the provided HTTP request for outbound authentication
    }

    public function inspect(Request req, Response resp) returns Request|error? {
        // Logic related to inspection of received HTTP request and response from outbound authentication
    }
};

Samples

Sample 1 - Outbound authentication with Basic Auth

import ballerina/auth;
import ballerina/http;

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

http:Client nyseEP = new("https://localhost:9090", config = {
    auth: {
        authHandler: basicAuthHandler
    }
});

Sample 2 - Outbound authentication with JWT Auth

import ballerina/http;
import ballerina/jwt;

jwt:OutboundJwtAuthProvider jwtAuthProvider = new({
        issuer: "ballerina",
        audience: ["ballerina"],
        issuerConfig: {
            keyAlias: "ballerina",
            keyPassword: "ballerina",
            keyStore: {
                path: "${ballerina.home}/bre/security/ballerinaKeystore.p12",
                password: "ballerina"
            }
        }
    }
});
http:BearerAuthHandler jwtAuthHandler = new(jwtAuthProvider);

http:Client nyseEP = new("https://localhost:9090", config = {
    auth: {
        authHandler: jwtAuthHandler
    }
});

Sample 3 - Outbound authentication with OAuth2

import ballerina/http;
import ballerina/oauth2;

oauth2:OutboundOAuth2Provider oauth2Provider = new({
    tokenUrl: "https://localhost:9196/oauth2/token",
    clientId: "3MVG9YDQS5WtC11paU",
    clientSecret: "92053723741"
});
http:BearerAuthHeaderHandler oauth2Handler = new(oauth2Provider);

http:Client nyseEP = new("https://localhost:9090", config = {
    auth: {
        authHandler: oauth2Handler
    }
});

Sample 4 - Outbound authentication with Custom Auth

This is a sample program which handles authentication with authorization with a custom header.

sample.bal

import ballerina/http;

OutboundCustomAuthProvider customAuthProvider = new;
OutboundCustomAuthHandler customAuthHandler = new(customAuthProvider);

http:Client nyseEP = new("https://localhost:9090", config = {
    auth: {
        authHandler: customAuthHandler
    }
});

outbound_custom_auth_provider.bal

import ballerina/auth;

public type OutboundCustomAuthProvider object {

    *auth:OutboundAuthProvider;

    public function generateToken() returns string|error {
        return "sUA4M8A!k7pU";
    }

    public function inspect(map<anydata> data) returns string|error? {
        return ();
    }
}

outbound_custom_auth_handler.bal

import ballerina/auth;
import ballerina/http;

public type OutboundCustomAuthHandler object {

    *http:OutboundAuthHandler;

    public OutboundCustomAuthProvider authProvider;

    public function __init(OutboundCustomAuthProvider authProvider) {
        self.authProvider = authProvider;
    }

    public function prepare(Request req) returns Request|error {
        string token = chekc self.authProvider.generateToken();
        req.addHeader("Authorization", token);
        return req;
    }

    public function inspect(Request req, Response resp) returns Request|error? {
        self.authProvider.inspect(new);
    }
};

Check List

• Read the Contributing Guide
• Required Balo version update
• Updated Change Log
• Checked Tooling Support (#)
• Added necessary tests
  • Unit Tests
  • Spec Conformance Tests
  • Integration Tests
  • Ballerina By Example Tests
• Increased Test Coverage
• Added necessary documentation
  • API documentation
  • Module documentation in Module.md files
  • Ballerina By Examples