Files
ca/Documentation/api/internal_authctx.md
dissoupovandGitHub 27e411997c Added integration tests (#16)
* Refactor Backend service

* Added integration tests
2026-10-23 18:02:39 -05:00

26 KiB

authctx

import "github.com/effective-security/trustyca/internal/authctx"

Index

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"
)

Role source claim values

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