clworkos

package
v0.38.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2024 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package clworkos provides auth-flow middleware and endpoint using WorkOS.

Index

Constants

This section is empty.

Variables

View Source 
var ErrBasicAuthNotAllowed = errors.New("basic auth is not allowed")

ErrBasicAuthNotAllowed is returned when a user is not allowed to use basic auth.

View Source 
var ErrCallbackCodeNotProvided = errors.New("missing code query parameter")

ErrCallbackCodeNotProvided is returned when the code query parameter is missing.

View Source 
var ErrNoAccessTokenForSignOut = errors.New("no credentials to sign-out with")

ErrNoAccessTokenForSignOut is returned when no access token is present for sign out.

View Source 
var ErrNoAuthentication = errors.New("no authentication")

ErrNoAuthentication is returned when no authentication is present in the request.

View Source 
var ErrRedirectToNotProvided = errors.New("missing redirect_to query parameter")

ErrRedirectToNotProvided is returned when the redirect_to query parameter is missing.

View Source 
var ErrStateNonceMismatch = errors.New("state nonce mismatch")

ErrStateNonceMismatch is returned when the nonce from the query does not match the nonce from the state cookie.

Functions

func IsBadRequestError 

func IsBadRequestError(err error) bool

IsBadRequestError will return true if the error is an error that describes bad input from the user. this is useful to provide the client with more information about what went wrong.

func NewOrganizations added in v0.31.0 

func NewOrganizations(cfg Config) *organizations.Client

NewOrganizations creates a new UserManagement implementation with the provided configuration.

func NewUserManagement 

func NewUserManagement(cfg Config) *usermanagement.Client

NewUserManagement creates a new UserManagement implementation with the provided configuration.

func Provide 

func Provide() fx.Option

Provide configures the DI for providng rpc.

func TestProvide 

func TestProvide(tb testing.TB, clockAt int64) fx.Option

TestProvide provides the WorkOS handler with well-known (public) testing keys. It will also Mock the WorkOS API client and put the wall-clock on a fixed point in time.

func WithIdentity added in v0.30.8 

func WithIdentity(ctx context.Context, identity Identity) context.Context

WithIdentity stores the identity in the request context.

Types

type C added in v0.35.0 

type C struct{}

C describes typed context values.

type Clock 

type Clock interface{ jwt.Clock }

Clock is an interface for fetching the wall-clock time.

type Config 

type Config struct {
	// WorkOS API key.
	APIKey string `env:"API_KEY"`
	// WorkOS main client ID.
	MainClientID string `env:"MAIN_CLIENT_ID"`
	// Full url to where the user will be send after WorkOS has done the authorization.
	CallbackURL *url.URL `env:"CALLBACK_URL" envDefault:"http://localhost:8080/auth/callback"`
	// AccessTokenIssuer is used to check the access token issuer.
	AccessTokenIssuer string `env:"ISSUER" envDefault:"https://api.workos.com"`
	// TokenValidationAcceptableSkew provides some slack in checking token times.
	TokenValidationAcceptableSkew time.Duration `env:"TOKEN_VALIDATION_ACCEPTABLE_SKEW" envDefault:"10s"`
	// AllCookieSecure will set the secure flag on all cookies.
	AllCookieSecure bool `env:"ALL_COOKIE_SECURE" envDefault:"true"`
	// AllCookieDomain configures the domain for all cookies
	AllCookieDomain string `env:"ALL_COOKIE_DOMAIN" envDefault:"localhost"`
	// AllCookiePath configures the path attribute for session cookies
	AllCookiePath string `env:"ALL_COOKIE_PATH" envDefault:"/"`
	// AllCookieSameSite configures the same-site attribute for all cookies
	AllCookieSameSite http.SameSite `env:"ALL_COOKIE_SAME_SITE" envDefault:"4"`
	// ShowErrorMessagesToClient will show server errors to the client, should only be visible in development.
	ShowErrorMessagesToClient bool `env:"SHOW_ERROR_MESSAGES_TO_CLIENT" envDefault:"false"`
	// RedirectToAllowedHosts is a list of hosts that are allowed to be redirected to.
	RedirectToAllowedHosts []string `env:"REDIRECT_TO_ALLOWED_HOSTS" envDefault:"localhost"`
	// JWKEndpoint is the endpoint for fetching the public key set for verifying the access key.
	JWKEndpoint string `env:"JWK_ENDPOINT" envDefault:"https://api.workos.com/sso/jwks/"`
	// PubPrivSigningKeySetB64JSON will hold private keys for JWE encryption
	PubPrivEncryptKeySetB64JSON string `env:"PUB_PRIV_ENCRYPT_KEY_SET_B64_JSON" envDefault:"eyJrZXlzIjpbXX0="`
	// PrivateSigningKeys will hold private keys for signing JWTs
	PubPrivSigningKeySetB64JSON string `env:"PUB_PRIV_SIGNING_KEY_SET_B64_JSON" envDefault:"eyJrZXlzIjpbXX0="`
	// DefaultSignKeyID defines the default key id used for signing
	DefaultSignKeyID string `env:"DEFAULT_SIGN_KEY_ID" envDefault:"key1"`
	// DefaultEncryptKeyID defines the default encryption id used for encryption
	DefaultEncryptKeyID string `env:"DEFAULT_ENCRYPT_KEY_ID" envDefault:"key1"`
	// DefaultRedirectTo is the URL to redirect to if there is no state cookie
	DefaultRedirectTo *url.URL `env:"DEFAULT_REDIRECT_TO" envDefault:"http://localhost:8080/healthz"`
	// SessionCookiePath is the name he access token cookie will get.
	SessionCookieName string `env:"SESSION_COOKIE_NAME" envDefault:"cl_session"`
	// StateCookieName is the Name for the state nonce cookie will be set
	StateCookieName string `env:"AUTH_NONCE_COOKIE_NAME" envDefault:"cl_auth_state"`
	// AccessTokenCookiePath is the name he access token cookie will get.
	AccessTokenCookieName string `env:"ACCESS_TOKEN_COOKIE_NAME" envDefault:"cl_access_token"`
	// instructs the browser on how long the session cookie should be stored.
	SessionCookieMaxAgeSeconds int `env:"SESSION_COOKIE_MAX_AGE_SECONDS" envDefault:"34560000"`
	// instructs the browser on how long the access token cookie should be stored.
	AccessTokenCookieMaxAgeSeconds int `env:"ACCESS_TOKEN_COOKIE_MAX_AGE_SECONDS" envDefault:"34560000"`
	// allow username/password auth only for certain (system) users.
	BasicAuthWhitelist []string `env:"BASIC_AUTH_WHITELIST"`
	// configure how long we cache basic auth identities
	BasicAuthCacheExpiry time.Duration `env:"BASIC_AUTH_CACHE_EXPIRY" envDefault:"1h"`
	// size of the basic auth cache, unlikely to hit this but good practice to limit memory
	BasicAuthCacheSize int `env:"BASIC_AUTH_CACHE_SIZE" envDefault:"1000"`
}

Config configures the package components.

type Engine 

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

Engine implements the core business logic for WorkOS-powered authentication.

func NewEngine 

func NewEngine(
	cfg Config,
	logs *zap.Logger,
	hooks Hooks,
	keys *Keys,
	clock Clock,
	um UserManagement,
	orgs Organizations,
) (eng *Engine, err error)

NewEngine creates a new Engine with the provided UserManagement implementation.

func (Engine) AuthenticateUsernamePassword added in v0.35.1 

func (e Engine) AuthenticateUsernamePassword(
	ctx context.Context, uname, passwd string,
) (idn Identity, fromCache bool, err error)

AuthenticateUsernamePassword is used to authenticate a user with a username and password. This method is only allowed for certain white-listed usernames since it is generally considered insure when used wrongly.

func (Engine) BuildSessionToken 

func (e Engine) BuildSessionToken(session Session) (string, error)

BuildSessionToken builds an signed and encrypted session token.

func (Engine) BuildSignedStateToken 

func (e Engine) BuildSignedStateToken(nonce, redirectTo string) (string, error)

BuildSignedStateToken builds a signed state token with the provided nonce and redirect_to values. It is a public method to make black box testing easier.

func (Engine) ContinueSession 

func (e Engine) ContinueSession(ctx context.Context, w http.ResponseWriter, r *http.Request) (idn Identity, err error)

ContinueSession will continue the user's session, potentially by refreshing it. It is expected to be called on every request as part of some middleware logic.

func (Engine) HandleSignInCallback 

func (e Engine) HandleSignInCallback(ctx context.Context, w http.ResponseWriter, r *http.Request) (*url.URL, error)

HandleSignInCallback handles the sign-in callback as the user returns from WorkOS.

func (Engine) StartAuthenticationFlow added in v0.30.11 

func (e Engine) StartAuthenticationFlow(
	ctx context.Context, w http.ResponseWriter, r *http.Request, screenHint string,
) (*url.URL, error)

StartAuthenticationFlow starts the sign-in flow as the user is redirected to WorkOS.

func (Engine) StartSignOutFlow 

func (e Engine) StartSignOutFlow(ctx context.Context, w http.ResponseWriter, r *http.Request) (*url.URL, error)

StartSignOutFlow starts the sign-out flow as the user is redirected to WorkOS.

type Handler 

type Handler struct {
	http.Handler
	// contains filtered or unexported fields
}

Handler provides WorkOS auth-flow functionality.

func New 

func New(cfg Config, logs *zap.Logger, engine *Engine) *Handler

New creates a new Handler with the provided configuration and logger.

func (Handler) Authenticate 

func (h Handler) Authenticate() bhttp.StdMiddleware

Authenticate provides the authentication middleware. It will set an identity in the request context based on the access token. If the access token is expired it will try to refresh the token ad-hoc.

type Hooks added in v0.30.13 

type Hooks interface {
	AuthenticateWithCodeDidSucceed(
		ctx context.Context, clientID string, idn Identity, accessToken, refreshToken string,
	) (string, Session, error)
}

Hooks can be optionally provided to the engine to allow custom behavior at various points in the authentication flow.

type Identity 

type Identity struct {
	// IsValid is set to true when the identity could be determined and the identity is valid.
	IsValid bool `mapstructure:"-"`
	// describes when the token that backs this identity expires.
	ExpiresAt time.Time `mapstructure:"-"`
	// WorkOS user id
	UserID string `mapstructure:"-"`
	// WorkOS organization id the user is a member of
	OrganizationID string `mapstructure:"org_id"`
	// ID of the session, used for logout.
	SessionID string `mapstructure:"sid"`
	// Role of the user in the organization.
	Role string `mapstructure:"role"`
	// Impersonator describes who is impersonating the user (if any)
	Impersonator Impersonator `mapstructure:"act"`
}

Identity describes the identity as determined by the authentication process.

func IdentityFromContext 

func IdentityFromContext(ctx context.Context) Identity

IdentityFromContext retrieves the identity from the request context.

type Impersonator 

type Impersonator struct {
	// Email of the impersonator.
	Email string `mapstructure:"sub"`
}

Impersonator describes who is impersonating the user (if any).

type InvalidInputError 

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

InvalidInputError can wrap any error to mark it as being invalid input.

func InputErrorf 

func InputErrorf(format string, args ...interface{}) InvalidInputError

InputErrorf is a helper function to create a new InvalidInputError.

type KeyNotFoundError 

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

KeyNotFoundError is returned when a key with a specific id is not found.

func (KeyNotFoundError) Error 

func (e KeyNotFoundError) Error() string

type Keys 

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

Keys hold our own private keys, and the WorkOS public keys.

func NewKeys 

func NewKeys(cfg Config) (*Keys, error)

NewKeys creates a new Keys instance.

type Lister added in v0.31.2 

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

Lister provides WorkOS list functionality.

func NewLister added in v0.31.2 

func NewLister(cfg Config, logs *zap.Logger, users UserManagement, orgs Organizations) *Lister

NewLister inits the WorkOS lister.

func (*Lister) ListAllOrganizations added in v0.31.2 

func (ls *Lister) ListAllOrganizations(ctx context.Context) (users []organizations.Organization, err error)

ListAllOrganizations returns all users in WorkOS.

func (*Lister) ListAllUsers added in v0.31.2 

func (ls *Lister) ListAllUsers(ctx context.Context) (users []usermanagement.User, err error)

ListAllUsers returns all users in WorkOS.

type NoOpHooks added in v0.30.14 

type NoOpHooks struct{}

NoOpHooks is a no-op implementation of Hooks that is the default value if not is provided. This is exported so implementations can embed it and only override the methods they care about.

func (NoOpHooks) AuthenticateWithCodeDidSucceed added in v0.30.14 

func (NoOpHooks) AuthenticateWithCodeDidSucceed(
	ctx context.Context,
	clientID string,
	idn Identity,
	accessToken, refreshToken string,
) (string, Session, error)

type Organizations added in v0.31.0 

type Organizations interface {
	CreateOrganization(ctx context.Context, opts organizations.CreateOrganizationOpts) (organizations.Organization, error)
	GetOrganization(ctx context.Context, opts organizations.GetOrganizationOpts) (organizations.Organization, error)
	ListOrganizations(
		ctx context.Context,
		opts organizations.ListOrganizationsOpts,
	) (organizations.ListOrganizationsResponse, error)
	UpdateOrganization(
		ctx context.Context,
		opts organizations.UpdateOrganizationOpts,
	) (organizations.Organization, error)
}

Organizations interface provides organization information from WorkOS.

type RedirectToNotAllowedError 

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

RedirectToNotAllowedError is returned when the redirect URL is not allowed.

func (RedirectToNotAllowedError) Error 

func (e RedirectToNotAllowedError) Error() string

type Session added in v0.37.0 

type Session struct {
	// The WorkOS refresh token
	RefreshToken string `mapstructure:"rt"`
	// The session may overwrite the organization ID in the identity.
	OrganizationIDOverwrite string `mapstructure:"org_id_o"`
	// The session may overwrite the role of the user in the organization.
	RoleOverwrite string `mapstructure:"role_o"`
}

Session holds data that we set.

type UserManagement 

type UserManagement interface {
	GetAuthorizationURL(
		opts usermanagement.GetAuthorizationURLOpts) (*url.URL, error)
	GetLogoutURL(
		opts usermanagement.GetLogoutURLOpts) (*url.URL, error)
	AuthenticateWithCode(
		ctx context.Context,
		opts usermanagement.AuthenticateWithCodeOpts) (usermanagement.AuthenticateResponse, error)
	AuthenticateWithRefreshToken(
		ctx context.Context,
		opts usermanagement.AuthenticateWithRefreshTokenOpts) (usermanagement.RefreshAuthenticationResponse, error)
	AuthenticateWithPassword(
		ctx context.Context,
		opts usermanagement.AuthenticateWithPasswordOpts,
	) (usermanagement.AuthenticateResponse, error)
	GetUser(ctx context.Context, opts usermanagement.GetUserOpts) (usermanagement.User, error)
	ListUsers(ctx context.Context, opts usermanagement.ListUsersOpts) (usermanagement.ListUsersResponse, error)
	CreateOrganizationMembership(
		ctx context.Context, opts usermanagement.CreateOrganizationMembershipOpts,
	) (usermanagement.OrganizationMembership, error)
	UpdateUser(ctx context.Context, opts usermanagement.UpdateUserOpts) (usermanagement.User, error)
	SendInvitation(ctx context.Context, opts usermanagement.SendInvitationOpts) (usermanagement.Invitation, error)
}

UserManagement interface describes the interface with the WorkOS User Management API.

type WorkOSCallbackError 

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

WorkOSCallbackError is an error returned from the WorkOS callback logic.

func (WorkOSCallbackError) Error 

func (e WorkOSCallbackError) Error() string

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.