Documentation
¶
Overview ¶
Package session provides OAuth session management for the authorization server. Sessions link issued access tokens to upstream identity provider tokens, enabling token exchange and refresh operations.
Index ¶
Constants ¶
const ClientIDClaimKey = "client_id"
ClientIDClaimKey is the JWT claim key for the OAuth client ID. This identifies which client was issued the token.
const EmailClaimKey = "email"
EmailClaimKey is the JWT claim key for the user's email address. Per OIDC Core Section 5.1.
const NameClaimKey = "name"
NameClaimKey is the JWT claim key for the user's display name. Per OIDC Core Section 5.1.
const TokenSessionIDClaimKey = "tsid"
TokenSessionIDClaimKey is the JWT claim key for the token session ID. This links JWT access tokens to stored upstream IDP tokens. We use "tsid" instead of "sid" to avoid confusion with OIDC session management which defines "sid" for different purposes (RFC 7519, OIDC Session Management).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Factory ¶
Factory is a function that creates a new session given subject, IDP session ID, and client ID. This allows storage implementations to create sessions without importing this package directly.
The factory is primarily used during deserialization where the clientID may be empty because the client_id claim is preserved in the JWT claims Extra map from the original serialized session data.
type Session ¶
type Session struct {
*oauth2.JWTSession
// UpstreamSessionID links this session to stored upstream IDP tokens.
// This ID is used to retrieve the IDP tokens from storage.
UpstreamSessionID string
}
Session extends fosite's JWT session with an IDP session reference. This allows the authorization server to link issued tokens to upstream IDP tokens stored separately.
Most methods are provided by the embedded *oauth2.JWTSession. This type only adds IDP session tracking and overrides Clone() to include the UpstreamSessionID field.
Concurrency: Sessions are designed to be request-scoped and are not safe for concurrent access from multiple goroutines. This follows Fosite's design pattern where sessions are created per-request, populated by handlers, and then persisted to storage. The storage layer is responsible for thread-safe access to stored sessions.
func New ¶
func New(subject, idpSessionID, clientID string, claims UserClaims) *Session
New creates a new Session with the given subject, IDP session ID, client ID, and optional user profile claims.
Parameters:
- subject: The OAuth subject (user identifier). May be empty for placeholder sessions.
- idpSessionID: Links to upstream IDP tokens in storage. If provided, it will be included in the JWT claims as "tsid" to allow proxy middleware to look up upstream IDP tokens.
- clientID: The OAuth client ID. When provided, it will be included in the JWT claims as "client_id" for binding verification per RFC 9068.
- claims: Optional user profile claims (name, email) from the upstream IDP. Included in the JWT per OIDC Core Section 5.1.
ClientID handling:
- For token issuance (authorize handler): Pass the client ID to ensure RFC 9068 compliance. The client_id claim will be embedded in the JWT.
- For token exchange (token handler): May be empty - Fosite copies claims from the stored authorize session, preserving the original client_id.
- For deserialization: May be empty - the client_id claim is preserved in the JWT claims Extra map from the serialized session data.
Note: The remaining RFC 9068 required claims (iss, aud, exp, iat, jti) are populated by Fosite during token generation. This session only initializes custom claims that are not part of Fosite's standard JWT handling.
func (*Session) Clone ¶
Clone creates a deep copy of the session. This overrides the embedded JWTSession.Clone() to also copy UpstreamSessionID.
func (*Session) GetIDPSessionID ¶
GetIDPSessionID returns the IDP session ID.
func (*Session) SetIDPSessionID ¶
SetIDPSessionID sets the IDP session ID.
type UpstreamSession ¶
type UpstreamSession interface {
oauth2.JWTSessionContainer
GetIDPSessionID() string
}
UpstreamSession is an interface for sessions that support IDP linking and JWT claims. It embeds oauth2.JWTSessionContainer (which includes fosite.Session, GetJWTClaims, and GetJWTHeader) and adds IDP session tracking. This interface is used by the storage layer for serialization/deserialization.
type UserClaims ¶ added in v0.11.2
type UserClaims struct {
// Name is the user's display name (OIDC "name" claim).
Name string
// Email is the user's email address (OIDC "email" claim).
Email string
}
UserClaims holds optional user profile claims from the upstream IDP. Using a struct avoids parameter-ordering mistakes in function signatures that accept multiple string parameters.
Source Files