Documentation
¶
Overview ¶
Package browsersession provides browser-based OIDC authentication and cookie-managed sessions for the portal UI. It implements:
- HMAC-SHA256 signed JWT session cookies (stateless)
- OIDC authorization code flow with PKCE
- Cookie-based authenticator for the HTTP auth chain
Index ¶
- Constants
- func ClearCookie(w http.ResponseWriter, cfg *CookieConfig)
- func SetCookie(w http.ResponseWriter, cfg *CookieConfig, tokenString string)
- func SignSession(claims SessionClaims, cfg *CookieConfig) (string, error)
- type Authenticator
- type CookieConfig
- type Flow
- type FlowConfig
- type SessionClaims
Constants ¶
const ( DefaultCookieName = "mcp_session" DefaultCookiePath = "/" DefaultTTL = 8 * time.Hour )
Default configuration values.
Variables ¶
This section is empty.
Functions ¶
func ClearCookie ¶
func ClearCookie(w http.ResponseWriter, cfg *CookieConfig)
ClearCookie removes the session cookie.
func SetCookie ¶
func SetCookie(w http.ResponseWriter, cfg *CookieConfig, tokenString string)
SetCookie writes the session JWT as an HTTP-only cookie.
func SignSession ¶
func SignSession(claims SessionClaims, cfg *CookieConfig) (string, error)
SignSession creates a signed JWT string from session claims.
Types ¶
type Authenticator ¶
type Authenticator struct {
// contains filtered or unexported fields
}
Authenticator checks for a valid session cookie and returns user info. It is designed to be used as the first step in an HTTP auth chain — if no cookie is present or the cookie is invalid, it returns nil (allowing fallback to token-based authentication).
func NewAuthenticator ¶
func NewAuthenticator(cfg CookieConfig) *Authenticator
NewAuthenticator creates a cookie-based authenticator.
func (*Authenticator) AuthenticateHTTP ¶
func (a *Authenticator) AuthenticateHTTP(r *http.Request) (*middleware.UserInfo, error)
AuthenticateHTTP checks the HTTP request for a valid session cookie. Returns nil, nil when no valid cookie is found (no error, just unauthenticated).
func (*Authenticator) ExtractIDToken ¶ added in v0.36.2
func (a *Authenticator) ExtractIDToken(r *http.Request) string
ExtractIDToken extracts the OIDC id_token from the session cookie. Returns empty string if no valid session exists or no id_token is stored.
type CookieConfig ¶
type CookieConfig struct {
// Name is the cookie name (default: "mcp_session").
Name string
// Domain restricts the cookie to a specific domain.
Domain string
// Path restricts the cookie to a specific path (default: "/").
Path string
// Secure marks the cookie as HTTPS-only (default: true).
Secure bool
// SameSite controls cross-site cookie behavior (default: Lax).
SameSite http.SameSite
// TTL is the session lifetime (default: 8h).
TTL time.Duration
// Key is the HMAC-SHA256 signing key. Must be at least 32 bytes.
Key []byte
}
CookieConfig controls session cookie behavior.
type Flow ¶
type Flow struct {
// contains filtered or unexported fields
}
Flow implements the OIDC authorization code flow with PKCE.
func NewFlow ¶
func NewFlow(ctx context.Context, cfg FlowConfig) (*Flow, error)
NewFlow creates a new OIDC flow by performing provider discovery.
func (*Flow) CallbackHandler ¶
func (f *Flow) CallbackHandler(w http.ResponseWriter, r *http.Request)
CallbackHandler processes the OIDC provider's callback after authentication. It validates the state, exchanges the authorization code for tokens, creates a session cookie, and redirects to the portal.
func (*Flow) LoginHandler ¶
func (f *Flow) LoginHandler(w http.ResponseWriter, r *http.Request)
LoginHandler initiates the OIDC authorization code flow. It generates state + PKCE verifier, stores them in a temporary cookie, and redirects the user to the OIDC provider's authorization endpoint.
func (*Flow) LogoutHandler ¶
func (f *Flow) LogoutHandler(w http.ResponseWriter, r *http.Request)
LogoutHandler clears the session cookie and redirects to the OIDC end_session endpoint.
type FlowConfig ¶
type FlowConfig struct {
// Issuer is the OIDC provider's issuer URL.
Issuer string
// ClientID is the OIDC client identifier.
ClientID string
// ClientSecret is the OIDC client secret for confidential clients.
ClientSecret string // #nosec G117 -- OIDC client secret from admin config
// RedirectURI is the callback URL (e.g., "https://example.com/portal/auth/callback").
RedirectURI string
// Scopes to request (default: [openid, profile, email]).
Scopes []string
// RoleClaim is the JSON path to roles in the id_token claims.
RoleClaim string
// RolePrefix filters roles to those with this prefix.
RolePrefix string
// Cookie configures the session cookie.
Cookie CookieConfig
// PostLoginRedirect is where to redirect after successful login (default: "/portal/").
PostLoginRedirect string
// PostLogoutRedirect is the absolute URL sent as post_logout_redirect_uri
// to the OIDC provider. Must be an absolute URL (Keycloak rejects relative paths).
// Falls back to PostLoginRedirect if empty.
PostLogoutRedirect string
// HTTPClient is used for OIDC discovery and token exchange.
// If nil, http.DefaultClient is used.
HTTPClient *http.Client
}
FlowConfig configures the OIDC authorization code flow.
type SessionClaims ¶
type SessionClaims struct {
UserID string `json:"sub"`
Email string `json:"email,omitempty"`
Roles []string `json:"roles"`
IDToken string `json:"idt,omitempty"` // raw id_token for logout id_token_hint
}
SessionClaims holds the claims stored in the session JWT cookie.
func ParseFromRequest ¶
func ParseFromRequest(r *http.Request, cfg *CookieConfig) (*SessionClaims, error)
ParseFromRequest reads the session cookie from the request and verifies it.
func VerifySession ¶
func VerifySession(tokenString string, key []byte) (*SessionClaims, error)
VerifySession validates a signed JWT and returns the session claims.
Source Files