Authentication

This page covers building custom authentication providers. If you only need to configure platform login for a deployment, use Providers > Authentication.

Authentication providers handle platform login. When a user visits the Gestalt UI or hits the HTTP API without a valid session, the authentication provider drives the login flow, validates the callback, and returns an authenticated identity. Gestalt then issues a session cookie and manages session lifetime on its own.

Beyond the core login flow, an authentication provider can optionally validate externally issued tokens (so API clients can present a bearer token directly instead of going through the browser) and control session TTL.

The examples on this page use a Google OAuth provider as the running example.

Manifest

An authentication provider manifest declares kind: authentication. You can optionally include a configSchemaPath so Gestalt validates provider config at startup.


kind: authentication
source: github.com/your-org/authentication/google
version: 0.0.1
displayName: Google Authentication
description: Authenticate users with Google OAuth.
spec:
  configSchemaPath: ./authentication_config.json

Interface

You implement three methods: Configure, BeginLogin, and CompleteLogin. BeginLogin returns an authorization URL that Gestalt redirects the user to. CompleteLogin exchanges the callback parameters for an authenticated identity.

Go


package googleauth
 
import (
	"context"
	"fmt"
 
	gestalt "github.com/valon-technologies/gestalt/sdk/go"
	"golang.org/x/oauth2"
	googleoauth "golang.org/x/oauth2/google"
)
 
type GoogleAuth struct {
	clientID     string
	clientSecret string
}
 
func New() *GoogleAuth { return &GoogleAuth{} }
 
func (g *GoogleAuth) Configure(_ context.Context, _ string, config map[string]any) error {
	g.clientID, _ = config["clientId"].(string)
	g.clientSecret, _ = config["clientSecret"].(string)
	if g.clientID == "" || g.clientSecret == "" {
		return fmt.Errorf("clientId and clientSecret are required")
	}
	return nil
}
 
func (g *GoogleAuth) BeginLogin(_ context.Context, req gestalt.BeginLoginRequest) (*gestalt.BeginLoginResponse, error) {
	cfg := &oauth2.Config{
		ClientID:     g.clientID,
		ClientSecret: g.clientSecret,
		RedirectURL:  req.CallbackUrl,
		Scopes:       []string{"openid", "email", "profile"},
		Endpoint:     googleoauth.Endpoint,
	}
	return &gestalt.BeginLoginResponse{
		AuthorizationUrl: cfg.AuthCodeURL(req.HostState, oauth2.AccessTypeOffline),
	}, nil
}
 
func (g *GoogleAuth) CompleteLogin(ctx context.Context, req gestalt.CompleteLoginRequest) (*gestalt.AuthenticatedUser, error) {
	// Exchange req.Query["code"] for a token, then fetch userinfo.
	return &gestalt.AuthenticatedUser{
		Subject:       "user-123",
		Email:         "user@example.com",
		EmailVerified: true,
		DisplayName:   "Example User",
	}, nil
}

Python


import gestalt
 
class GoogleAuth(gestalt.AuthenticationProvider):
    def configure(self, name: str, config: dict) -> None:
        self.client_id = config["clientId"]
        self.client_secret = config["clientSecret"]
 
    def begin_login(self, request: gestalt.BeginLoginRequest) -> gestalt.BeginLoginResponse:
        auth_url = (
            "https://accounts.google.com/o/oauth2/v2/auth"
            f"?client_id={self.client_id}"
            f"&redirect_uri={request.callback_url}"
            f"&state={request.host_state}"
            "&response_type=code"
            "&scope=openid+email+profile"
        )
        return gestalt.BeginLoginResponse(authorization_url=auth_url)
 
    def complete_login(self, request: gestalt.CompleteLoginRequest) -> gestalt.AuthenticatedUser:
        # Exchange request.query["code"] for a token, then fetch userinfo.
        return gestalt.AuthenticatedUser(
            subject="user-123",
            email="user@example.com",
            email_verified=True,
            display_name="Example User",
        )

Rust


use std::sync::Mutex;
use gestalt::{AuthenticationProvider, AuthenticatedUser, BeginLoginRequest, BeginLoginResponse, CompleteLoginRequest};
 
#[derive(Default)]
pub struct GoogleAuth {
    client_id: Mutex<String>,
    client_secret: Mutex<String>,
}
 
#[gestalt::async_trait]
impl AuthenticationProvider for GoogleAuth {
    async fn configure(
        &self, _name: &str, config: serde_json::Map<String, serde_json::Value>,
    ) -> gestalt::Result<()> {
        *self.client_id.lock().unwrap() = config
            .get("clientId").and_then(|v| v.as_str()).unwrap_or("").to_string();
        *self.client_secret.lock().unwrap() = config
            .get("clientSecret").and_then(|v| v.as_str()).unwrap_or("").to_string();
        Ok(())
    }
 
    async fn begin_login(&self, req: BeginLoginRequest) -> gestalt::Result<BeginLoginResponse> {
        let client_id = self.client_id.lock().unwrap().clone();
        Ok(BeginLoginResponse {
            authorization_url: format!(
                "https://accounts.google.com/o/oauth2/v2/auth\
                ?client_id={client_id}&redirect_uri={}&state={}&response_type=code\
                &scope=openid+email+profile",
                req.callback_url, req.host_state,
            ),
            provider_state: vec![],
        })
    }
 
    async fn complete_login(&self, req: CompleteLoginRequest) -> gestalt::Result<AuthenticatedUser> {
        // Exchange req.query["code"] for a token, then fetch userinfo.
        Ok(AuthenticatedUser {
            subject: "user-123".into(),
            email: "user@example.com".into(),
            email_verified: true,
            display_name: "Example User".into(),
            ..Default::default()
        })
    }
}
 
gestalt::export_authentication_provider!(constructor = GoogleAuth::default);

TypeScript


import { defineAuthenticationProvider } from "@valon-technologies/gestalt";
 
let clientId = "";
let clientSecret = "";
 
export const provider = defineAuthenticationProvider({
  async configure(_name, config) {
    clientId = config.clientId as string;
    clientSecret = config.clientSecret as string;
  },
  async beginLogin(request) {
    return {
      authorizationUrl:
        `https://accounts.google.com/o/oauth2/v2/auth` +
        `?client_id=${encodeURIComponent(clientId)}` +
        `&redirect_uri=${encodeURIComponent(request.callbackUrl)}` +
        `&state=${encodeURIComponent(request.hostState)}` +
        `&response_type=code&scope=${encodeURIComponent("openid email profile")}`,
    };
  },
  async completeLogin(request) {
    // Exchange request.query.code for a token, then fetch userinfo.
    return {
      subject: "user-123",
      email: "user@example.com",
      emailVerified: true,
      displayName: "Example User",
    };
  },
});

Point package.json at the authentication provider with gestalt.provider:


{
  "gestalt": {
    "provider": {
      "kind": "authentication",
      "target": "./authentication.ts#provider"
    }
  }
}

Optional interfaces

Two optional interfaces extend the base contract.

ExternalTokenValidator lets API clients present a bearer token directly instead of going through the browser login flow. In Go, implement the ExternalTokenValidator interface on your provider. In Python, inherit from gestalt.ExternalTokenValidator. In Rust, override the validate_external_token method, which returns an unimplemented error by default. In TypeScript, provide the optional validateExternalToken handler to defineAuthenticationProvider.

SessionTTLProvider controls session lifetime. The default is 24 hours. In Go, implement the SessionTTLProvider interface. In Python, inherit from gestalt.SessionTTLProvider. In Rust, override the session_ttl method, which returns None (the 24-hour default) by default. In TypeScript, provide the optional sessionSettings handler to defineAuthenticationProvider.

Config Reference

To use a Google authentication provider in a Gestalt deployment, reference it as a named entry in providers.authentication:


providers:
  authentication:
    google:
      source: ./google-authentication/manifest.yaml
      config:
        clientId: ${GOOGLE_CLIENT_ID}
        clientSecret:
          secret:
            provider: default
            name: google-client-secret
        allowedDomains:
          - example.com

source: ./manifest.yaml points at the authentication provider’s manifest.yaml during development. For production, use a published provider-release.yaml metadata URL. The config block is passed to Configure at startup and validated against the config schema if one was declared in the manifest.

Structured secret refs like clientSecret.secret.provider: default are resolved through the configured secret manager before reaching the provider. Environment variable placeholders like ${GOOGLE_CLIENT_ID} are expanded during config loading. See Configuration for details on both.