authsaml

README

togo-framework/auth-saml

SAML 2.0 SSO (service-provider) for the togo auth family — enterprise login via Okta, Azure AD, OneLogin, etc.

Install

togo install togo-framework/auth-saml

Adds SAML 2.0 service-provider login to togo. It configures a SAML SP from env, exposes the standard SP endpoints, and on a verified IdP assertion finds-or-creates the user by the asserted email and issues an auth session via the auth plugin. When unconfigured it registers cleanly and its endpoints return 501 (no crash).

Configuration

Env	Description
SAML_ROOT_URL	the app's external base URL, e.g. https://app.example.com
SAML_SP_CERT	the SP's X.509 certificate (PEM)
SAML_SP_KEY	the SP's RSA private key (PEM)
SAML_IDP_METADATA_URL	the IdP metadata URL (or use SAML_IDP_METADATA_XML)
SAML_IDP_METADATA_XML	the IdP metadata XML inline (alternative to the URL)
SAML_RETURN_URL	post-login redirect (default /)

Generate an SP keypair:

openssl req -x509 -newkey rsa:2048 -keyout sp.key -out sp.crt -days 3650 -nodes -subj "/CN=app.example.com"
export SAML_SP_CERT="$(cat sp.crt)"  SAML_SP_KEY="$(cat sp.key)"

Register the SP with your IdP using the metadata at /api/auth/saml/metadata (Entity ID + ACS URL are derived from SAML_ROOT_URL).

Endpoints

Method	Path	Purpose
GET	/api/auth/saml/metadata	SP metadata XML (give this to the IdP)
GET	/api/auth/saml/login?return=/admin	SP-initiated login → redirect to the IdP
POST	/api/auth/saml/acs	Assertion Consumer Service → verify, issue session, redirect
GET	/api/auth/saml/status	{ "configured": bool }

On success the ACS issues an auth session (cookie/JWT via the auth plugin) and redirects to the validated RelayState/return URL (open-redirect-safe — local paths only).

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package authsaml adds SAML 2.0 SSO (service-provider) login to the togo auth family. It configures a crewjam/saml ServiceProvider from env, exposes the standard SP endpoints (metadata / login / ACS), and on a verified assertion finds-or-creates the user by the asserted email and issues an auth session via the auth plugin.

Configure with SAML_SP_CERT + SAML_SP_KEY (PEM keypair), SAML_IDP_METADATA_URL (or SAML_IDP_METADATA_XML), and SAML_ROOT_URL (the app's external base URL). When unconfigured the plugin still registers, but its endpoints return 501.

Index

• type Config
• type Provider
  • func FromKernel(k *togo.Kernel) (*Provider, bool)
  • func (p *Provider) Ready() bool

Types

type Config

type Config struct {
	RootURL    string // SAML_ROOT_URL, e.g. https://app.example.com
	CertPEM    string // SAML_SP_CERT
	KeyPEM     string // SAML_SP_KEY
	IDPMetaURL string // SAML_IDP_METADATA_URL
	IDPMetaXML string // SAML_IDP_METADATA_XML
	ReturnURL  string // SAML_RETURN_URL (post-login redirect, default "/")
}

Config holds the SP configuration resolved from the environment.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider holds the configured SAML ServiceProvider.

func FromKernel

func FromKernel(k *togo.Kernel) (*Provider, bool)

FromKernel returns the auth-saml Provider.

func (*Provider) Ready

func (p *Provider) Ready() bool

Ready reports whether SAML is fully configured.