26 KiB
authctx
import "github.com/effective-security/trustyca/internal/authctx"
Index
- Constants
- Variables
- func AllowsRole(allowedRoles []string, role pb.Role_Enum) bool
- func CanAssumeRole(callerRole pb.Role_Enum, allowedRoles []string) bool
- func CheckAccess(ctx context.Context, authorizer Authorizer, req any, action string, skipLogPaths ...telemetry.LoggerSkipPath) error
- func GetAllowedMethods(ctx context.Context, authorizer Authorizer) (*pb.ServiceAccessInfo, error)
- func GetCallerScope(ctx context.Context, authorizer Authorizer) (*pb.CallerScope, error)
- func Handler(delegate http.Handler) http.Handler
- func HasScope(granted []string, scope string) bool
- func HasScopes(granted []string, required []string) bool
- func IsKnownScope(scope string) bool
- func IsOrgRole(role pb.Role_Enum) bool
- func IsProjectRole(role pb.Role_Enum) bool
- func NewAuthUnaryBackendInterceptor(authorizer Authorizer) grpc.UnaryServerInterceptor
- func NewAuthUnaryInterceptor(authorizer Authorizer, skipLogPaths []telemetry.LoggerSkipPath) grpc.UnaryServerInterceptor
- func NewTrustyCtx(ctx context.Context, idnCtx identity.Context) context.Context
- func ParseRole(name string) pb.Role_Enum
- func ParseScopes(values []string) []string
- func ProjectFromRequest(req any) (xdb.ID, error)
- func RoleSourceClaim(source pb.RoleSource_Enum) string
- type Authorizer
- type Grants
- func GrantsFromMemberships(rows model.MembershipInfoSlice, orgID, userID xdb.ID) *Grants
- func (g *Grants) CanGrantOrgRole(role pb.Role_Enum) bool
- func (g *Grants) CanGrantProjectRole(projectID uint64, role pb.Role_Enum) bool
- func (g *Grants) CanListAllProjects() bool
- func (g *Grants) GrantedProjectIDs() []uint64
- func (g *Grants) HasProjectAccess(projectID uint64) bool
- func (g *Grants) HighestRole(projectID uint64, allowedRoles []string) pb.Role_Enum
- func (g *Grants) IsMember() bool
- func (g *Grants) OrgAccess() *pb.OrgAccess
- func (g *Grants) ResolvedOrgRole() (pb.Role_Enum, pb.RoleSource_Enum)
- func (g *Grants) Roles(projectID uint64) []pb.Role_Enum
- type GrantsProvider
- type OrgRequester
- type ProjectRequester
- type TrustyCtx
Constants
Token claims set by the auth service
const (
// ClaimOrg is the selected org ID (the tenant claim)
ClaimOrg = "org"
// ClaimOrgRole is the resolved org role: the explicit org-wide role,
// or Viewer derived from project grants. It is informational; permissions
// are always resolved from the grants in the DB.
ClaimOrgRole = "org_role"
// ClaimOrgRoleSource is "direct" for an explicit org-wide grant or
// "project" for a derived Viewer classification
ClaimOrgRoleSource = "org_role_source"
// ClaimScope lists the scopes granted to an API key or a scoped token.
// A method with (es.api.scopes) requires every listed scope to be
// granted. "*" grants everything; "certs:*" grants every certs scope.
ClaimScope = "scope"
// ClaimProject is the project an API key is restricted to, if any
ClaimProject = "project"
)
const (
// RoleSourceDirect marks an explicit org-wide grant
RoleSourceDirect = "direct"
// RoleSourceProject marks a derived Viewer classification from project grants
RoleSourceProject = "project"
)
Scopes are the API scopes (permissions) that can be granted to API keys. A method declares the scopes it requires with (es.api.scopes).
const (
ScopeOrgRead = "org:read"
ScopeProjectRead = "project:read"
ScopeCARead = "ca:read"
ScopeCAWrite = "ca:write"
ScopeCertsRead = "certs:read"
ScopeCertsIssue = "certs:issue"
ScopeCertsRevoke = "certs:revoke"
ScopeAll = "*"
)
PeerRoleName is the role of a trustyca instance that calls the backend listener for its callers: the CA service of the WFE forwards every call of its tenants with the context of the end user (DESIGN.md section 2.1). It is the only role whose forwarded context the backend accepts.
const PeerRoleName = "trustyca-peer"
ServiceRolePrefix marks trusted service identities (mTLS peers), which pass tenant scope explicitly and are not subject to membership checks TODO: add a config option for the service role prefix
const ServiceRolePrefix = "trustyca-"
Variables
var (
// ErrInsufficientRole is returned when none of the caller's roles at the
// requested scope can assume an allowed role
ErrInsufficientRole = errors.New("insufficient role")
// ErrAccessDenied is returned when the project does not belong to the
// org or is inactive, so that callers do not leak project existence
ErrAccessDenied = errors.New("access denied")
// ErrOrgNotSelected is returned when the token has no selected org
ErrOrgNotSelected = errors.New("org not selected")
)
CanAssumeRoles specifies which roles a caller role may satisfy when a method declares (es.api.allowed_roles). The listed roles are the minimum roles allowed; a caller passes when its own role can assume one of them. For example, with allowed_roles "User" a Viewer is denied and a Security caller is allowed, because Security may assume User.
var CanAssumeRoles = map[pb.Role_Enum][]pb.Role_Enum{
pb.Role_APIKey: {pb.Role_APIKey},
pb.Role_Viewer: {pb.Role_Viewer},
pb.Role_User: {pb.Role_User, pb.Role_Viewer},
pb.Role_Billing: {pb.Role_Billing, pb.Role_Viewer},
pb.Role_Support: {pb.Role_Support, pb.Role_User, pb.Role_Viewer},
pb.Role_Security: {pb.Role_Security, pb.Role_User, pb.Role_Viewer},
pb.Role_Admin: {pb.Role_Admin, pb.Role_Security, pb.Role_Support, pb.Role_User, pb.Role_Billing, pb.Role_Viewer},
pb.Role_Owner: {pb.Role_Owner, pb.Role_Admin, pb.Role_Security, pb.Role_Support, pb.Role_User, pb.Role_Billing, pb.Role_Viewer},
}
DefaultAPIKeyScopes are granted to an API key created without scopes
var DefaultAPIKeyScopes = []string{ScopeOrgRead, ScopeProjectRead, ScopeCARead}
KnownScopes lists the scopes an API key may be created with
var KnownScopes = []string{
ScopeOrgRead, ScopeProjectRead, ScopeCARead, ScopeCAWrite,
ScopeCertsRead, ScopeCertsIssue, ScopeCertsRevoke,
}
OrgRoles are the roles that can be granted org-wide
var OrgRoles = []pb.Role_Enum{
pb.Role_Viewer,
pb.Role_User,
pb.Role_Support,
pb.Role_Billing,
pb.Role_Security,
pb.Role_Admin,
pb.Role_Owner,
}
ProjectRoles are the roles that can be granted in a project. Owner and Billing are org-wide concepts and cannot be granted per project.
var ProjectRoles = []pb.Role_Enum{
pb.Role_Viewer,
pb.Role_User,
pb.Role_Support,
pb.Role_Security,
pb.Role_Admin,
}
RoleEnumValue maps role names, in the proto and lowercase spelling, to roles
var RoleEnumValue = map[string]pb.Role_Enum{
"apikey": pb.Role_APIKey,
"APIKey": pb.Role_APIKey,
"viewer": pb.Role_Viewer,
"Viewer": pb.Role_Viewer,
"user": pb.Role_User,
"User": pb.Role_User,
"billing": pb.Role_Billing,
"Billing": pb.Role_Billing,
"security": pb.Role_Security,
"Security": pb.Role_Security,
"support": pb.Role_Support,
"Support": pb.Role_Support,
"admin": pb.Role_Admin,
"Admin": pb.Role_Admin,
"owner": pb.Role_Owner,
"Owner": pb.Role_Owner,
}
func AllowsRole
func AllowsRole(allowedRoles []string, role pb.Role_Enum) bool
AllowsRole returns true if the allowed roles list contains the role itself
func CanAssumeRole
func CanAssumeRole(callerRole pb.Role_Enum, allowedRoles []string) bool
CanAssumeRole returns true if a caller with the role may assume one of the allowed roles
func CheckAccess
func CheckAccess(ctx context.Context, authorizer Authorizer, req any, action string, skipLogPaths ...telemetry.LoggerSkipPath) error
CheckAccess authorizes the action for the caller.
Two method options drive the check:
- (es.api.allowed_roles) lists the minimum roles allowed to call the method at org scope, or at project scope when the request carries ProjectID. A caller passes when one of its roles at that scope can assume an allowed role (CanAssumeRoles). Methods without allowed roles require an authenticated caller only.
- (es.api.scopes) lists the scopes an API key, or a token with a scope claim, must hold in addition. API keys are allowed only when the allowed roles include APIKey; they are checked against the token scopes, never against memberships.
Admin (privpb) and status services are restricted to trustyca-* service roles; identity and session methods (pb.Auth) are gated by the server authz config only.
func GetAllowedMethods
func GetAllowedMethods(ctx context.Context, authorizer Authorizer) (*pb.ServiceAccessInfo, error)
GetAllowedMethods returns the methods the caller may call in the org selected in the token, grouped by service. Roles are judged at org scope; a project grant may allow more methods within its project.
func GetCallerScope
func GetCallerScope(ctx context.Context, authorizer Authorizer) (*pb.CallerScope, error)
GetCallerScope returns the caller's resolved scope in the org selected in the token, and the access rules of every public method with the verdict at org scope
func Handler
func Handler(delegate http.Handler) http.Handler
Handler returns http.Handler that extracts Trusty context
func HasScope
func HasScope(granted []string, scope string) bool
HasScope returns true if the granted scopes cover the scope, exactly, through "*", or through a prefix wildcard such as "certs:*"
func HasScopes
func HasScopes(granted []string, required []string) bool
HasScopes returns true if the granted scopes cover every required scope. A method without required scopes is covered by any grant.
func IsKnownScope
func IsKnownScope(scope string) bool
IsKnownScope returns true if the scope may be granted to an API key
func IsOrgRole
func IsOrgRole(role pb.Role_Enum) bool
IsOrgRole returns true if the role can be granted org-wide
func IsProjectRole
func IsProjectRole(role pb.Role_Enum) bool
IsProjectRole returns true if the role can be granted in a project
func NewAuthUnaryBackendInterceptor
func NewAuthUnaryBackendInterceptor(authorizer Authorizer) grpc.UnaryServerInterceptor
NewAuthUnaryBackendInterceptor returns grpc.UnaryServerInterceptor that sets the TrustyCtx of a call of the backend listener. A caller acts as the identity the listener authenticated, so that a service caller over mTLS (RA, AIA, the operator) acts under its own role. The WFE (PeerRoleName) forwards the calls of its callers with their context in the x-trustyca-context metadata: the call then runs as that caller, after CheckAccess authorizes it again for the method, a method of the backend service with the roles and scopes of the pb.CA method of the same name. A forwarded context of another role is ignored, and one that does not parse fails the call. The backend runs no CheckAccess for its service callers: the server authz config restricts its methods to service roles.
func NewAuthUnaryInterceptor
func NewAuthUnaryInterceptor(authorizer Authorizer, skipLogPaths []telemetry.LoggerSkipPath) grpc.UnaryServerInterceptor
NewAuthUnaryInterceptor returns grpc.UnaryServerInterceptor that checks access to the method
func NewTrustyCtx
func NewTrustyCtx(ctx context.Context, idnCtx identity.Context) context.Context
NewTrustyCtx returns new context.Context with TrustyCtx
func ParseRole
func ParseRole(name string) pb.Role_Enum
ParseRole parses a role name case-insensitively; None when unknown
func ParseScopes
func ParseScopes(values []string) []string
ParseScopes splits the (es.api.scopes) option values, which may be comma separated, into scope names
func ProjectFromRequest
func ProjectFromRequest(req any) (xdb.ID, error)
ProjectFromRequest returns the ProjectID carried by the request, zero when the request has none
func RoleSourceClaim
func RoleSourceClaim(source pb.RoleSource_Enum) string
RoleSourceClaim returns the token claim value for the role source
type Authorizer
Authorizer resolves the caller's explicit grants and checks roles.
Grants are cached per user with a bounded TTL; membership mutations must call InvalidateUser after commit. Sensitive operations that require immediate revocation should bypass the cache with an authoritative check.
type Authorizer interface {
// Grants returns the explicit grants of the user in the org.
// A user without grants gets empty Grants, not an error.
Grants(ctx context.Context, orgID, userID xdb.ID) (*Grants, error)
// Project returns the active project of the org.
// It returns ErrAccessDenied when the project belongs to another org or
// is inactive.
Project(ctx context.Context, orgID, projectID xdb.ID) (*model.Project, error)
// CheckRole returns the caller's role at the scope that can assume one of
// the allowed roles: the org-wide role at org scope (projectID 0), the
// org-wide or the project role at project scope. It returns
// ErrInsufficientRole when no role can, and ErrAccessDenied when the
// project is not an active project of the org.
CheckRole(ctx context.Context, orgID, projectID, userID xdb.ID, allowedRoles ...string) (pb.Role_Enum, *Grants, error)
// InvalidateUser invalidates the cached grants of the user
InvalidateUser(ctx context.Context, userID string)
// InvalidateProject invalidates the cached project
InvalidateProject(ctx context.Context, projectID string)
}
func NewAuthorizer
func NewAuthorizer(provider GrantsProvider) Authorizer
NewAuthorizer returns Authorizer backed by the grants provider
type Grants
Grants are the explicit grants of a user in one org, as stored in the membership table: an optional org-wide role and a role per project.
Grants are additive. At org scope the caller acts with the org-wide role. At project scope the caller acts with the org-wide role, inherited by every project of the org, and with the project role; a method is allowed when either role can assume one of its allowed roles. A user with project grants only is a derived org Viewer: it may select the org and read its summary, but inherits nothing in other projects.
type Grants struct {
OrgID xdb.ID
UserID xdb.ID
// OrgRole is the explicit org-wide role, None when absent
OrgRole pb.Role_Enum
// ProjectRoles maps project ID to the explicit project role
ProjectRoles map[uint64]pb.Role_Enum
}
func GrantsFromMemberships
func GrantsFromMemberships(rows model.MembershipInfoSlice, orgID, userID xdb.ID) *Grants
GrantsFromMemberships builds the grants of the user in the org from membership rows. Rows of other orgs and users are ignored.
func (*Grants) CanGrantOrgRole
func (g *Grants) CanGrantOrgRole(role pb.Role_Enum) bool
CanGrantOrgRole returns true if the user may grant (or revoke) the role org-wide. An org Admin may grant any org role except Owner; only an Owner may grant Owner. Project grants never allow org-wide grants.
func (*Grants) CanGrantProjectRole
func (g *Grants) CanGrantProjectRole(projectID uint64, role pb.Role_Enum) bool
CanGrantProjectRole returns true if the user may grant (or revoke) the role in the project: the role must be a project role and the user must be an Admin in the project, org-wide or explicitly
func (*Grants) CanListAllProjects
func (g *Grants) CanListAllProjects() bool
CanListAllProjects returns true if the user may list every project of the org: any explicit org-wide role. Project-only members list their projects.
func (*Grants) GrantedProjectIDs
func (g *Grants) GrantedProjectIDs() []uint64
GrantedProjectIDs returns the IDs of the projects with an explicit grant, sorted
func (*Grants) HasProjectAccess
func (g *Grants) HasProjectAccess(projectID uint64) bool
HasProjectAccess returns true if the user has any role at the project
func (*Grants) HighestRole
func (g *Grants) HighestRole(projectID uint64, allowedRoles []string) pb.Role_Enum
HighestRole returns the user's role at the scope that can assume one of the allowed roles, preferring the org-wide role; None when no role can. An empty allowed list accepts any role at the scope.
func (*Grants) IsMember
func (g *Grants) IsMember() bool
IsMember returns true if the user has any grant in the org
func (*Grants) OrgAccess
func (g *Grants) OrgAccess() *pb.OrgAccess
OrgAccess returns the resolved org access for the discovery API
func (*Grants) ResolvedOrgRole
func (g *Grants) ResolvedOrgRole() (pb.Role_Enum, pb.RoleSource_Enum)
ResolvedOrgRole returns the org role and how it was resolved: the explicit org-wide role (Direct), or Viewer when the user has project grants only (Project). None when the user is not a member.
func (*Grants) Roles
func (g *Grants) Roles(projectID uint64) []pb.Role_Enum
Roles returns the roles the user acts with at the scope: at org scope (projectID 0) the resolved org role; at project scope the explicit org-wide role and the project role. The derived org Viewer is not inherited by projects.
type GrantsProvider
GrantsProvider provides memberships and projects to the authorizer. It is plain CRUD: the DB layer is not aware of authorization.
type GrantsProvider interface {
// ListMemberships lists memberships
ListMemberships(ctx context.Context, req *query.ListMembershipsRequest) (model.MembershipInfoSlice, error)
// GetProject returns Project by ID
GetProject(ctx context.Context, id uint64) (*model.Project, error)
}
type OrgRequester
OrgRequester specifies if request contains an explicit OrgID. Tenant requests take the org from the token; an explicit OrgID is only accepted from trusted service identities, or when it matches the token.
type OrgRequester interface {
GetOrgID() string
}
type ProjectRequester
ProjectRequester specifies if request contains ProjectID. An empty ProjectID means the request is Org scope.
type ProjectRequester interface {
GetProjectID() string
}
type TrustyCtx
TrustyCtx provides trustyca context
type TrustyCtx interface {
// OrgID returns the org selected in the token, zero if none
OrgID() xdb.ID
UserID() xdb.ID
Name() string
Email() string
// OrgRole returns the resolved role in the selected org from the token
// (viewer, user, admin, owner), or APIKey for an API key token.
// Permissions of users are resolved from grants; API keys are checked
// against Scopes.
OrgRole() pb.Role_Enum
// ProjectID returns the project an API key is restricted to, zero if none
ProjectID() xdb.ID
// Scopes returns the scopes granted to an API key or a scoped token
Scopes() []string
// IsAPIKey returns true for an API key token
IsAPIKey() bool
// AppRole returns current user role in App service from the token context (trusty-admin, user, guest)
AppRole() string
// Target of the request, e.g. HTTP path or gRPC method
Target() string
UserAgent() string
AuthMethod() identity.AuthMethod
}
func FromContext
func FromContext(ctx context.Context) TrustyCtx
FromContext extracts the TrustyCtx stored inside a go context. Returns empty context if no such value exists.
func FromRequest
func FromRequest(r *http.Request) TrustyCtx
FromRequest returns the full context associcated with this http request.
Generated by gomarkdoc