Authentication

Authentication providers handle platform login for the Gestalt server. Authentication is separate from Authorization, which decides what the caller may access, and External Credentials, which provide upstream credentials for configured connections.

How authentication providers work

When a request arrives without a valid session, Gestalt asks the configured authentication provider to begin login, redirects the user to the identity provider, and then calls the provider again to complete the callback. After that, Gestalt issues and stores its own session.

First-Party Authentication Providers

Published first-party authentication providers live under valon-technologies/gestalt-providers/auth.

Provider	Use case
`github.com/valon-technologies/gestalt-providers/auth/oidc`	Generic OpenID Connect providers such as Google, Okta, Auth0, Azure AD, or Keycloak

Configuring `providers.authentication`


providers:
  authentication:
    oidc:
      source:
        package: github.com/valon-technologies/gestalt-providers/auth/oidc
        version: 0.0.1-alpha.1
      config:
        issuerUrl: https://login.example.com
        clientId: ...
        clientSecret: ...

Structured secret refs such as clientSecret.secret.provider: default are resolved through providers.secrets before the authentication provider receives its config.

To disable platform authentication entirely, omit providers.authentication.

For local development, omission is the simple default: every request is treated as the same anonymous user.

Local source during development


providers:
  authentication:
    oidc:
      source: ./oidc-auth/manifest.yaml
      config:
        issuerUrl: https://login.example.com
        clientId: ...
        clientSecret: ...

Building your own authentication provider

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

The authentication surface has two required methods: BeginLogin and CompleteLogin. BeginLogin returns an authorization URL that Gestalt redirects the user to. CompleteLogin exchanges 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


from gestalt import (
    AuthenticationProvider,
    BeginLoginRequest,
    BeginLoginResponse,
    CompleteLoginRequest,
    AuthenticatedUser,
)
 
class GoogleAuth(AuthenticationProvider):
    def configure(self, name: str, config: dict) -> None:
        self.client_id = config["clientId"]
        self.client_secret = config["clientSecret"]
 
    def begin_login(self, request: BeginLoginRequest) -> 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 BeginLoginResponse(authorization_url=auth_url)
 
    def complete_login(self, request: CompleteLoginRequest) -> AuthenticatedUser:
        # Exchange request.query["code"] for a token, then fetch userinfo.
        return 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",
    };
  },
});

The authentication provider manifest points Gestalt at the executable artifact produced by its build command:


build:
  command:
    - npm
    - run
    - build
  inputs:
    - package.json
    - package-lock.json
    - authentication.ts
entrypoint:
  artifactPath: .gestalt/build/authentication

Optional interfaces

Two optional interfaces extend the base contract.

External token validation

External token validation lets API clients present a bearer token directly instead of going through the browser login flow. Return a user when the token is valid. Return nil, None, null, or undefined when the token is not recognized.

Go

Implement ExternalTokenValidator on the same provider type:


import (
    "context"
 
    gestalt "github.com/valon-technologies/gestalt/sdk/go"
)
 
func (g *GoogleAuth) ValidateExternalToken(ctx context.Context, token string) (*gestalt.AuthenticatedUser, error) {
    if token == "" {
        return nil, nil
    }
 
    // Validate the bearer token with the upstream issuer, then map the
    // token claims into a Gestalt identity.
    return &gestalt.AuthenticatedUser{
        Subject:       "user-123",
        Email:         "user@example.com",
        EmailVerified: true,
        DisplayName:   "Example User",
        Claims: map[string]string{
            "issuer": "https://accounts.google.com",
        },
    }, nil
}

Python

Inherit from ExternalTokenValidator and implement validate_external_token:


from typing import Any
 
from gestalt import AuthenticationProvider, ExternalTokenValidator, AuthenticatedUser
 
class GoogleAuth(AuthenticationProvider, ExternalTokenValidator):
    def validate_external_token(self, token: str) -> Any:
        if not token:
            return None
 
        # Validate the bearer token with the upstream issuer, then map the
        # token claims into a Gestalt identity.
        return AuthenticatedUser(
            subject="user-123",
            email="user@example.com",
            email_verified=True,
            display_name="Example User",
            claims={"issuer": "https://accounts.google.com"},
        )

Rust

Override validate_external_token on the AuthenticationProvider implementation:


use std::collections::BTreeMap;
use gestalt::AuthenticatedUser;
 
async fn validate_external_token(
    &self,
    token: &str,
) -> gestalt::Result<Option<AuthenticatedUser>> {
    if token.is_empty() {
        return Ok(None);
    }
 
    // Validate the bearer token with the upstream issuer, then map the
    // token claims into a Gestalt identity.
    Ok(Some(AuthenticatedUser {
        subject: "user-123".into(),
        email: "user@example.com".into(),
        email_verified: true,
        display_name: "Example User".into(),
        claims: BTreeMap::from([(
            "issuer".into(),
            "https://accounts.google.com".into(),
        )]),
        ..Default::default()
    }))
}

TypeScript

Add validateExternalToken to defineAuthenticationProvider:


import { defineAuthenticationProvider } from "@valon-technologies/gestalt";
 
export const provider = defineAuthenticationProvider({
  // configure, beginLogin, and completeLogin omitted for brevity
 
  async validateExternalToken(token) {
    if (!token) {
      return null;
    }
 
    // Validate the bearer token with the upstream issuer, then map the
    // token claims into a Gestalt identity.
    return {
      subject: "user-123",
      email: "user@example.com",
      emailVerified: true,
      displayName: "Example User",
      claims: {
        issuer: "https://accounts.google.com",
      },
    };
  },
});

Session TTL

Session TTL controls how long Gestalt persists a successful browser login. If you do not implement the optional hook, sessions default to 24 hours.

Go

Implement SessionTTLProvider on the same provider type:


import "time"
 
func (g *GoogleAuth) SessionTTL() time.Duration {
    return 8 * time.Hour
}

Python

Inherit from SessionTTLProvider and return a datetime.timedelta:


import datetime as dt
from gestalt import AuthenticationProvider, SessionTTLProvider
 
class GoogleAuth(AuthenticationProvider, SessionTTLProvider):
    def session_ttl(self) -> dt.timedelta:
        return dt.timedelta(hours=8)

Rust

Override session_ttl on the AuthenticationProvider implementation:


fn session_ttl(&self) -> Option<std::time::Duration> {
    Some(std::time::Duration::from_secs(8 * 60 * 60))
}

TypeScript

Add sessionSettings to defineAuthenticationProvider:


import { defineAuthenticationProvider } from "@valon-technologies/gestalt";
 
export const provider = defineAuthenticationProvider({
  // configure, beginLogin, and completeLogin omitted for brevity
 
  sessionSettings() {
    return {
      sessionTtlSeconds: 8 * 60 * 60,
    };
  },
});

Deploying the provider

Configure a custom authentication provider through the same providers.authentication block shown in Configuring providers.authentication. That section is the source of truth for local manifest paths, published provider release URLs, and structured secret refs. For packaging and release mechanics, see Releasing provider packages.

Authentication

How authentication providers work

First-Party Authentication Providers

Configuring providers.authentication

Local source during development

Building your own authentication provider

Manifest

Interface

Go

Python

Rust

TypeScript

Optional interfaces

External token validation

Go

Python

Rust

TypeScript

Session TTL

Go

Python

Rust

TypeScript

Deploying the provider

What To Read Next

Configuring `providers.authentication`