oauth

Documentation

Overview

Package oauth provides adapters for integrating the github.com/giantswarm/mcp-oauth library with the mcp-kubernetes MCP server.

This package bridges the mcp-oauth library with our existing server architecture, providing token provider integration and configuration mapping for Kubernetes contexts that may require OAuth authentication.

User Info Integration

This package provides convenience functions for accessing authenticated user information from request contexts:

• UserInfoFromContext: Retrieves the full UserInfo from context
• HasUserInfo: Checks if user info is present in context
• GetUserEmailFromContext: Extracts just the user's email
• GetUserGroupsFromContext: Extracts the user's group memberships

For Kubernetes impersonation, use the conversion functions:

• ToFederationUserInfo: Converts OAuth UserInfo to federation.UserInfo
• ToFederationUserInfoWithExtra: Converts with additional claims
• ValidateUserInfoForImpersonation: Validates minimum required fields

Dependency Security Note

This package depends on github.com/giantswarm/mcp-oauth for OAuth 2.1 implementation. The library provides: PKCE enforcement, refresh token rotation, rate limiting, and audit logging. Security posture: Actively maintained, implements OAuth 2.1 specification.

Index

• func ContextWithAccessToken(ctx context.Context, idToken string) context.Context
• func GetAccessTokenFromContext(ctx context.Context) (string, bool)
• func GetIDToken(token *oauth2.Token) string
• func GetUserEmailFromContext(ctx context.Context) string
• func GetUserGroupsFromContext(ctx context.Context) []string
• func HasUserInfo(ctx context.Context) bool
• func ToFederationUserInfo(user *UserInfo) *federation.UserInfo
• func ToFederationUserInfoWithExtra(user *UserInfo, extra map[string][]string) *federation.UserInfo
• func ValidateUserInfoForImpersonation(user *UserInfo) error
• type UserInfo
  • func UserInfoFromContext(ctx context.Context) (*UserInfo, bool)

Functions

func ContextWithAccessToken

func ContextWithAccessToken(ctx context.Context, idToken string) context.Context

ContextWithAccessToken creates a context with the given OAuth ID token. This is used to pass the user's OAuth ID token for downstream Kubernetes OIDC authentication. Note: Kubernetes OIDC requires the ID token, not the access token.

func GetAccessTokenFromContext

func GetAccessTokenFromContext(ctx context.Context) (string, bool)

GetAccessTokenFromContext retrieves the OAuth ID token from the context. This returns the user's OAuth ID token that can be used for downstream Kubernetes OIDC authentication. Returns the ID token and true if present, or empty string and false if not available.

func GetIDToken

func GetIDToken(token *oauth2.Token) string

GetIDToken extracts the ID token from an OAuth2 token. OIDC providers include an id_token in the Extra data. Kubernetes OIDC authentication requires the ID token, not the access token.

func GetUserEmailFromContext

func GetUserEmailFromContext(ctx context.Context) string

GetUserEmailFromContext extracts just the email address from the context. This is a convenience function for common use cases where only the email is needed. Returns empty string if no user info is available.

func GetUserGroupsFromContext

func GetUserGroupsFromContext(ctx context.Context) []string

GetUserGroupsFromContext extracts the user's group memberships from the context. This is a convenience function for RBAC-related operations. Returns nil if no user info is available.

func HasUserInfo

func HasUserInfo(ctx context.Context) bool

HasUserInfo checks if the context contains authenticated user information. This is a convenience function that returns true if a valid UserInfo is present.

func ToFederationUserInfo

func ToFederationUserInfo(user *UserInfo) *federation.UserInfo

ToFederationUserInfo converts a UserInfo (from OAuth provider) to a federation.UserInfo. This enables using OAuth-authenticated user info for Kubernetes impersonation in multi-cluster operations.

The conversion maps:

• UserInfo.Email -> federation.UserInfo.Email (used as Impersonate-User)
• UserInfo.Groups -> federation.UserInfo.Groups (used as Impersonate-Group)
• UserInfo.ID -> federation.UserInfo.Extra["sub"] (subject claim)

Returns nil if the input user info is nil.

Note: This function creates a defensive copy of the Groups slice to prevent unintended modifications from affecting the original UserInfo.

func ToFederationUserInfoWithExtra

func ToFederationUserInfoWithExtra(user *UserInfo, extra map[string][]string) *federation.UserInfo

ToFederationUserInfoWithExtra converts a UserInfo to federation.UserInfo with additional extra claims. This is useful when you need to pass additional context beyond the standard OAuth claims.

The extra map is merged with the automatically extracted claims (like "sub"). Caller-provided values take precedence over auto-extracted values.

Security Warning

The extra parameter is merged directly into the federation.UserInfo.Extra map, which is used for Kubernetes Impersonate-Extra headers. Callers MUST ensure that:

• The extra map contains only trusted, validated data
• Values do not originate from untrusted user input without validation
• Keys and values comply with Kubernetes impersonation header requirements

Failure to validate the extra parameter could lead to impersonation of unintended identities or injection of malicious header values.

func ValidateUserInfoForImpersonation

func ValidateUserInfoForImpersonation(user *UserInfo) error

ValidateUserInfoForImpersonation performs comprehensive validation of UserInfo for Kubernetes impersonation use cases.

This function validates:

• User is not nil (ErrUserInfoRequired)
• Email is not empty (ErrUserEmailRequired) - used as Impersonate-User header
• All fields pass federation.ValidateUserInfo security checks including:
• Email format and length validation
• Group name validation (length, control characters)
• Extra header key/value validation

This provides defense-in-depth by ensuring that user info is both present and safe for use in HTTP headers before impersonation occurs.

Types

type UserInfo

type UserInfo = providers.UserInfo

UserInfo represents user information from an OAuth provider. This is a type alias for the library's providers.UserInfo type. It includes fields like Email, Groups, ID, Name, etc.

func UserInfoFromContext

func UserInfoFromContext(ctx context.Context) (*UserInfo, bool)

UserInfoFromContext retrieves the authenticated user's info from the context. This is a wrapper around the mcp-oauth library's UserInfoFromContext function. The user info is set by the OAuth ValidateToken middleware after successful JWT validation.

Returns the UserInfo pointer and true if present, or nil and false if not available.

Usage in tool handlers:

user, ok := oauth.UserInfoFromContext(ctx)
if !ok {
    return nil, fmt.Errorf("access denied: no authenticated user")
}
// Use user.Email, user.Groups, user.ID, etc.