Documentation
¶
Overview ¶
Package cedar provides authorization utilities using Cedar policies.
Package cedar provides authorization utilities using Cedar policies.
Index ¶
- Constants
- Variables
- func InjectUpstreamProvider(src *authorizers.Config, providerName string) (*authorizers.Config, error)
- func NewCedarAuthorizer(options ConfigOptions) (authorizers.Authorizer, error)
- type Authorizer
- func (a *Authorizer) AddEntity(entity cedar.Entity)
- func (a *Authorizer) AuthorizeWithJWTClaims(ctx context.Context, feature authorizers.MCPFeature, ...) (bool, error)
- func (a *Authorizer) GetEntity(uid cedar.EntityUID) (cedar.Entity, bool)
- func (a *Authorizer) GetEntityFactory() *EntityFactory
- func (a *Authorizer) IsAuthorized(principal, action, resource string, contextMap map[string]interface{}, ...) (bool, error)
- func (a *Authorizer) RemoveEntity(uid cedar.EntityUID)
- func (a *Authorizer) UpdateEntities(entitiesJSON string) error
- func (a *Authorizer) UpdatePolicies(policies []string) error
- type ClientIDContextKey
- type Config
- type ConfigOptions
- type EntityFactory
- func (*EntityFactory) CreateActionEntity(actionType, actionID string, attributes map[string]interface{}) (cedar.EntityUID, cedar.Entity)
- func (f *EntityFactory) CreateEntitiesForRequest(principal, action, resource string, claimsMap map[string]interface{}, ...) (cedar.EntityMap, error)
- func (*EntityFactory) CreatePrincipalEntity(principalType, principalID string, attributes map[string]interface{}, ...) (cedar.EntityUID, cedar.Entity, []cedar.Entity)
- func (*EntityFactory) CreateResourceEntity(resourceType, resourceID string, attributes map[string]interface{}) (cedar.EntityUID, cedar.Entity)
- type Factory
Constants ¶
const ConfigType = "cedarv1"
ConfigType is the configuration type identifier for Cedar authorization.
const EntityTypeTHVGroup cedar.EntityType = "THVGroup"
EntityTypeTHVGroup is the Cedar entity type representing group membership. Principals are added as children of THVGroup entities so that Cedar's `in` operator can evaluate group-based policies (e.g. `principal in THVGroup::"engineering"`).
Variables ¶
var ( ErrNoPolicies = errors.New("no policies loaded") ErrInvalidPolicy = errors.New("invalid policy") ErrMissingPrincipal = errors.New("missing principal") ErrMissingAction = errors.New("missing action") ErrMissingResource = errors.New("missing resource") ErrFailedToLoadEntities = errors.New("failed to load entities") )
Common errors for Cedar authorization
Functions ¶
func InjectUpstreamProvider ¶ added in v0.15.0
func InjectUpstreamProvider(src *authorizers.Config, providerName string) (*authorizers.Config, error)
InjectUpstreamProvider returns a new authorizers.Config that is identical to src except that the Cedar options' PrimaryUpstreamProvider field is set to providerName. Any existing PrimaryUpstreamProvider value is overwritten; if the Cedar config file already contains a non-empty PrimaryUpstreamProvider that differs from providerName, the file value is silently replaced. This is intentional: the embedded auth server config is the authoritative source of the upstream provider name at runtime. This is used by the runner middleware when the embedded auth server is active to wire the upstream provider into Cedar evaluation.
If src is not a Cedar config, providerName is empty, or src is nil, src is returned unchanged with a nil error. This makes the function safe to call unconditionally whenever the embedded auth server is active.
func NewCedarAuthorizer ¶
func NewCedarAuthorizer(options ConfigOptions) (authorizers.Authorizer, error)
NewCedarAuthorizer creates a new Cedar authorizer.
Types ¶
type Authorizer ¶
type Authorizer struct {
// contains filtered or unexported fields
}
Authorizer authorizes MCP operations using Cedar policies.
func (*Authorizer) AddEntity ¶
func (a *Authorizer) AddEntity(entity cedar.Entity)
AddEntity adds or updates an entity in the authorizer's entity store.
func (*Authorizer) AuthorizeWithJWTClaims ¶
func (a *Authorizer) AuthorizeWithJWTClaims( ctx context.Context, feature authorizers.MCPFeature, operation authorizers.MCPOperation, resourceID string, arguments map[string]interface{}, ) (bool, error)
AuthorizeWithJWTClaims demonstrates how to use JWT claims with the Cedar authorization middleware. This method: 1. Extracts JWT claims from the context 2. Extracts the client ID from the claims 3. Includes the JWT claims in the Cedar context 4. Creates entities with appropriate attributes 5. Authorizes the operation using the client ID and claims
func (*Authorizer) GetEntityFactory ¶
func (a *Authorizer) GetEntityFactory() *EntityFactory
GetEntityFactory returns the entity factory associated with this authorizer.
func (*Authorizer) IsAuthorized ¶
func (a *Authorizer) IsAuthorized( principal, action, resource string, contextMap map[string]interface{}, entities ...cedar.EntityMap, ) (bool, error)
IsAuthorized checks if a request is authorized. This is the core authorization method that all other authorization methods use. It takes: - principal: The entity making the request (e.g., "Client::vscode_extension_123") - action: The operation being performed (e.g., "Action::call_tool") - resource: The object being accessed (e.g., "Tool::weather") - context: Additional information about the request
Note: group-based Cedar policies (e.g. "principal in THVGroup::\"eng\"") only work when entities are constructed via AuthorizeWithJWTClaims, which calls CreateEntitiesForRequest with the extracted groups slice and adds THVGroup parent entities. Callers that bypass AuthorizeWithJWTClaims and pass their own entity map must include THVGroup entities manually for group policies to evaluate correctly. - entities: Optional Cedar entity map with attributes
func (*Authorizer) RemoveEntity ¶
func (a *Authorizer) RemoveEntity(uid cedar.EntityUID)
RemoveEntity removes an entity from the authorizer's entity store.
func (*Authorizer) UpdateEntities ¶
func (a *Authorizer) UpdateEntities(entitiesJSON string) error
UpdateEntities updates the Cedar entities.
func (*Authorizer) UpdatePolicies ¶
func (a *Authorizer) UpdatePolicies(policies []string) error
UpdatePolicies updates the Cedar policies.
type ClientIDContextKey ¶
type ClientIDContextKey struct{}
ClientIDContextKey is the key used to store client ID in the context.
type Config ¶
type Config struct {
Version string `json:"version"`
Type string `json:"type"`
Options *ConfigOptions `json:"cedar"`
}
Config represents the complete authorization configuration file structure for Cedar authorization. This includes the common version/type fields plus the Cedar-specific "cedar" field. This maintains backwards compatibility with the v1.0 configuration schema.
func ExtractConfig ¶
func ExtractConfig(authzConfig *authorizers.Config) (*Config, error)
ExtractConfig extracts the Cedar configuration from an authorizers.Config. This is useful for tests and other code that needs to inspect the Cedar configuration after it has been loaded into the generic Config structure. To access the Cedar-specific options (policies, entities), use the returned Config's Cedar field.
type ConfigOptions ¶
type ConfigOptions struct {
// Policies is a list of Cedar policy strings
Policies []string `json:"policies" yaml:"policies"`
// EntitiesJSON is the JSON string representing Cedar entities
EntitiesJSON string `json:"entities_json" yaml:"entities_json"`
// PrimaryUpstreamProvider names the upstream IDP provider whose access
// token should be used as the source of JWT claims for Cedar evaluation.
// When empty, claims from the ToolHive-issued token are used (current behaviour).
// Must match an entry in identity.UpstreamTokens (e.g. "default", "github").
PrimaryUpstreamProvider string `json:"primary_upstream_provider,omitempty" yaml:"primary_upstream_provider,omitempty"`
// GroupClaimName is the JWT claim key that contains group membership for the
// principal. When set, it takes priority over the well-known defaults
// ("groups", "roles", "cognito:groups"). Use this for IDPs that place groups
// under a URI-style claim (e.g. "https://example.com/groups" in Auth0/Okta).
// When empty, only the well-known claim names are checked.
GroupClaimName string `json:"group_claim_name,omitempty" yaml:"group_claim_name,omitempty"`
}
ConfigOptions represents the Cedar-specific authorization configuration options.
type EntityFactory ¶
type EntityFactory struct{}
EntityFactory creates Cedar entities for authorization.
func NewEntityFactory ¶
func NewEntityFactory() *EntityFactory
NewEntityFactory creates a new entity factory.
func (*EntityFactory) CreateActionEntity ¶
func (*EntityFactory) CreateActionEntity( actionType, actionID string, attributes map[string]interface{}, ) (cedar.EntityUID, cedar.Entity)
CreateActionEntity creates an action entity with the given ID and attributes.
func (*EntityFactory) CreateEntitiesForRequest ¶
func (f *EntityFactory) CreateEntitiesForRequest( principal, action, resource string, claimsMap map[string]interface{}, attributes map[string]interface{}, groups []string, ) (cedar.EntityMap, error)
CreateEntitiesForRequest creates entities for a specific authorization request. groups is an optional slice of group names; when non-empty, group parent entities are created and the principal entity's Parents set is populated accordingly so that Cedar's in operator works for group-membership policies.
func (*EntityFactory) CreatePrincipalEntity ¶
func (*EntityFactory) CreatePrincipalEntity( principalType, principalID string, attributes map[string]interface{}, groups []string, ) (cedar.EntityUID, cedar.Entity, []cedar.Entity)
CreatePrincipalEntity creates a principal entity with the given ID, attributes, and group memberships. Each group is added as a parent entity so that Cedar's in operator works for group-based policies (e.g. principal in THVGroup::"engineering"). Returns the principal UID, the principal entity, and a slice of group entities (one per group) that must also be added to the entity map.
func (*EntityFactory) CreateResourceEntity ¶
func (*EntityFactory) CreateResourceEntity( resourceType, resourceID string, attributes map[string]interface{}, ) (cedar.EntityUID, cedar.Entity)
CreateResourceEntity creates a resource entity with the given ID and attributes.
type Factory ¶
type Factory struct{}
Factory implements the authorizers.AuthorizerFactory interface for Cedar.
func (*Factory) CreateAuthorizer ¶
func (*Factory) CreateAuthorizer(rawConfig json.RawMessage, _ string) (authorizers.Authorizer, error)
CreateAuthorizer creates a Cedar Authorizer from the configuration. It receives the full raw config and extracts the Cedar-specific portion.
func (*Factory) ValidateConfig ¶
func (*Factory) ValidateConfig(rawConfig json.RawMessage) error
ValidateConfig validates the Cedar-specific configuration. It receives the full raw config and extracts the Cedar-specific portion.
Source Files