Files
ca/Documentation/api/server_service_auth.md

19 KiB

auth

import "github.com/effective-security/trustyca/server/service/auth"

Index

Constants

const (
    DefaultTokenTTL   = 48 * time.Hour
    DefaultOTCSeconds = 30
)

ServiceName provides the Service Name for this package

const ServiceName = "auth"

func Factory

func Factory(server gserver.GServer) any

Factory returns a factory of the service

type OTCState

type OTCState struct {
    Token               string `json:"token,omitempty"`
    ExpiresIn           uint32 `json:"expires_in,omitempty"`
    CodeChallenge       string `json:"code_challenge,omitempty"`
    CodeChallengeMethod string `json:"code_challenge_method,omitempty"`
}

type Request

Request specifies Authorization request

type Request struct {
    ClientID     string
    DeviceID     string
    ResponseMode string
    ResponseType string
    Scope        string
    RedirectURI  string
    Provider     pb.IDP_Enum
    Nonce        string
    Audience     []string
}

func (*Request) Validate

func (c *Request) Validate() error

Validate interface to check the data before saving

type Service

Service defines the Auth service

type Service struct {
    // allow to change in unittest
    BaseURL   *url.URL
    JwtSigner jwt.Signer
    JwtParser jwt.Parser
    // contains filtered or unexported fields
}

func (*Service) AuthHTTPHandler

func (s *Service) AuthHTTPHandler() restserver.Handle

func (*Service) AuthOrgHandler

func (s *Service) AuthOrgHandler() restserver.Handle

AuthOrgHandler handles pb.PathForAuthOrg: the org switch of a REST caller, the one a cookie session uses. A cookie session (the auth cookie and no Authorization header) receives the new token in the auth cookie, with a new CSRF cookie, and the response omits AccessToken; the cookies last until the token expires with RememberMe, else for the browser session. A caller with an Authorization header receives AccessToken, and its cookies are not replaced.

func (*Service) AuthProvider

func (s *Service) AuthProvider(ctx context.Context, provider pb.IDP_Enum) (*oauth2client.Client, error)

OAuthConfig returns oauth2client.Config, to be used in tests

func (*Service) AuthProviderForEmail

func (s *Service) AuthProviderForEmail(ctx context.Context, email string) (cl *oauth2client.Client, err error)

AuthProviderForEmail checks if the email is allowed to login, and returns oauth2client.Client for the provider. On a local instance (config.Service.IsLocal) an address with the localEmailPrefix signs in through the `local` provider, which needs no invitation; elsewhere it is an ordinary address.

func (*Service) AuthProvidersHandler

func (s *Service) AuthProvidersHandler() restserver.Handle

AuthProvidersHandler handles pb.PathForAuthProviders endpoint

func (*Service) AuthenticateAPIKey

func (s *Service) AuthenticateAPIKey(ctx context.Context, req *emptypb.Empty) (*pb.UserTokenResponse, error)

AuthenticateAPIKey authenticates an API key and returns a user token response

func (*Service) AuthenticateAPIKeyHandler

func (s *Service) AuthenticateAPIKeyHandler() restserver.Handle

AuthenticateAPIKeyHandler is the handler for the AuthenticateAPIKey endpoint It is used to authenticate API keys. It expects the following headers: Date: <timestamp> Authorization: APIKey <key_id>:<signature>

func (*Service) AuthorizeHandler

func (s *Service) AuthorizeHandler() restserver.Handle

AuthorizeHandler handles pb.PathForAuthorize

func (*Service) CallbackHandler

func (s *Service) CallbackHandler() restserver.Handle

CallbackHandler handles pb.PathForAuthCallback

func (*Service) Caller

func (s *Service) Caller(ctx context.Context, _ *emptypb.Empty) (*pb.CallerStatusResponse, error)

Caller returns the status of the caller.

func (*Service) Close

func (s *Service) Close()

Close the subservices and its resources

func (*Service) Db

func (s *Service) Db() db.OrgsDb

Db returns OrgsDb for unit tests

func (*Service) ExchangeCode

func (s *Service) ExchangeCode(ctx context.Context, req *pb.ExchangeCodeRequest) (*pb.Token, error)

func (*Service) GetAllowedMethods

func (s *Service) GetAllowedMethods(ctx context.Context, req *emptypb.Empty) (*pb.ServiceAccessInfo, error)

GetAllowedMethods returns the allowed methods for the caller

func (*Service) GetCallerScope

func (s *Service) GetCallerScope(ctx context.Context, req *emptypb.Empty) (*pb.CallerScope, error)

GetCallerScope returns the caller's resolved scope and the method access rules

func (*Service) GetProviders

func (s *Service) GetProviders(ctx context.Context, req *pb.AuthProvidersRequest) (*pb.AuthProvidersResponse, error)

GetProviders returns the list of supported providers

func (*Service) GetUserInfo

func (s *Service) GetUserInfo(ctx context.Context, idpType pb.IDP_Enum, cl *oauth2client.ClientConfig, _ *oauth2.Config, token *oauth2.Token) (*pb.UserInfo, jwt.MapClaims, error)

GetUserInfo returns the user the IdP signed in with the token. A user the service cannot sign in (no verified email, no name) is PermissionDenied, a failed call to the IdP is Unavailable; the answer of the IdP stays in the cause, for the server log.

func (*Service) GetUserToken

func (s *Service) GetUserToken(ctx context.Context, _ *emptypb.Empty) (*pb.UserTokenResponse, error)

GetUserToken returns the user token info

func (*Service) IsReady

func (s *Service) IsReady() bool

IsReady indicates that the service is ready to serve its end-points

func (*Service) Name

func (s *Service) Name() string

Name returns the service name

func (*Service) OAuthProvider

func (s *Service) OAuthProvider() *oauth2client.Provider

OAuthProvider returns the OAuth2 client registry. Config returns a copy, so tests that retarget a provider register a new client.

func (*Service) OnStarted

func (s *Service) OnStarted() error

OnStarted is called when the server started and is ready to serve requests

func (*Service) Protect

func (s *Service) Protect(ctx context.Context, v any) (string, error)

Protect returns encrypted value in base64url encoded format

func (*Service) RegisterGRPC

func (s *Service) RegisterGRPC(r *grpc.Server)

RegisterGRPC registers gRPC handler

func (*Service) RegisterRoute

func (s *Service) RegisterRoute(r restserver.Router)

RegisterRoute adds the Status API endpoints to the overall URL router

func (*Service) RemoveCookieHandler

func (s *Service) RemoveCookieHandler() restserver.Handle

RemoveCookieHandler returns handler for removing the auth cookie

func (*Service) RevokeToken

func (s *Service) RevokeToken(ctx context.Context, _ *emptypb.Empty) (*emptypb.Empty, error)

RevokeToken revokes the user token

func (*Service) RevokeTokenHandler

func (s *Service) RevokeTokenHandler() restserver.Handle

RevokeTokenHandler handles DELETE /pb.Auth/RevokeToken, the sign-out of a REST caller and of a cookie session: it removes the auth and CSRF cookies whatever the outcome, then revokes the caller's token

func (*Service) SelectOrg

func (s *Service) SelectOrg(ctx context.Context, req *pb.SelectOrgRequest) (*pb.UserTokenResponse, error)

SelectOrg verifies the caller's access to the org and returns a new token scoped to it, with the original expiry. Access requires an active org-wide or project grant.

A cookie session does not receive AccessToken, and gRPC cannot set a cookie: such a session switches the org with POST pb.PathForAuthOrg (AuthOrgHandler), which writes the new token into the auth cookie.

func (*Service) SetAuthProvider

func (s *Service) SetAuthProvider(ctx context.Context, cfg *oauth2client.ClientConfig) error

SetAuthProvider sets the OAuth2 client for the provider, override the existing client if it exists. to be used in tests

func (*Service) Unprotect

func (s *Service) Unprotect(ctx context.Context, protected string, v any) error

Unprotect decrypts and unmarshals protected string to a struct

func (*Service) UserTokenHandler

func (s *Service) UserTokenHandler() restserver.Handle

UserTokenHandler returns UserTokenResponse

func (*Service) UserinfoHandler

func (s *Service) UserinfoHandler() restserver.Handle

UserinfoHandler returns handler for returning the user info

type State

State is OAuth state provided by an authenticating client

type State struct {
    RedirectURL string      `json:"rurl,omitempty"`
    Provider    pb.IDP_Enum `json:"idp,omitempty"`
    Email       string      `json:"email,omitempty"`
    IssuedAt    int64       `json:"isa,omitempty"`
    ClientID    string      `json:"cid,omitempty"`
    DeviceID    string      `json:"did,omitempty"`
    Scope       string      `json:"scope,omitempty"`
    Nonce       string      `json:"nonce,omitempty"`
    // ResponseType specifies response type: code|token
    ResponseType        string   `json:"rt,omitempty"`
    ResponseMode        string   `json:"rm,omitempty"`
    DPoPJwk             string   `json:"dpop,omitempty"`
    Audience            []string `json:"aud,omitempty"`
    CodeChallenge       string   `json:"cc,omitempty"`
    CodeChallengeMethod string   `json:"ccm,omitempty"`
    RememberMe          bool     `json:"remember_me,omitempty"`
}

Generated by gomarkdoc