ToolhiveAuthorizationPolicy

ToolhiveAuthorizationPolicy attaches one or more ClusterPlatformRole bindings to a specific MCP target: an MCPServer or MCPRemoteProxy. Bindings can be narrowed by rule restrictions or tool-hint filters, and hard deny rules compile to Cedar forbid and override every grant.

API: toolhive.enterprise.stacklok.com/v1alpha1 · Scope: Namespaced · Short names: tap, authzpolicy

Example

toolhiveauthorizationpolicy.yaml

apiVersion: toolhive.enterprise.stacklok.com/v1alpha1
kind: ToolhiveAuthorizationPolicy
metadata:
  name: my-toolhiveauthorizationpolicy
  namespace: default
spec:
  targetRef:
    name: <string>

Schema

spec

ToolhiveAuthorizationPolicySpec defines the desired state of ToolhiveAuthorizationPolicy.

Field	Type	Description
bindings	object[]	Bindings is the list of role-to-principal bindings for this policy.
deny	object[]	Deny is the list of explicit deny rules. Each rule compiles to a Cedar forbid statement. In Cedar's evaluation model, forbid unconditionally overrides permit regardless of declaration order — a matching deny vetoes any permit that would otherwise grant access.
targetRefrequired	object	TargetRef identifies the MCP server this policy applies to.

spec.bindings[]

Bindings is the list of role-to-principal bindings for this policy.

Field	Type	Description
from	object[]	From optionally narrows this binding to a subset of principals. When omitted, the binding applies to every principal granted this role via the cluster-scoped binding CRD.
roleRefrequired	object	RoleRef references the ClusterPlatformRole to bind.
ruleRestrictions	object[]	RuleRestrictions optionally narrows which MCP resources this binding applies to. Each item scopes to a specific resource type; items are unioned. When omitted, the binding applies to all resources permitted by the role.
toolHintFilter	object	ToolHintFilter optionally gates call_tool on MCP tool annotation hints. Each non-nil filter field adds a Cedar when condition; multiple fields are ANDed.

↑ Back to spec

spec.bindings.from[]

From optionally narrows this binding to a subset of principals. When omitted, the binding applies to every principal granted this role via the cluster-scoped binding CRD.

Field	Type	Description
groups	string[]	Groups is the list of OIDC groups a principal must belong to.
roles	string[]	Roles is the list of OIDC roles a principal must have.

↑ Back to spec.bindings

spec.bindings.roleRef

RoleRef references the ClusterPlatformRole to bind.

Field	Type	Description
kindrequired	string	enum: ClusterPlatformRole
namerequired	string	minLength 1

↑ Back to spec.bindings

spec.bindings.ruleRestrictions[]

RuleRestrictions optionally narrows which MCP resources this binding applies to. Each item scopes to a specific resource type; items are unioned. When omitted, the binding applies to all resources permitted by the role.

Field	Type	Description
prompts	string[]	Prompts is the list of MCP prompt names to restrict to.
resources	string[]	Resources is the list of MCP resource URIs to restrict to.
tools	string[]	Tools is the list of MCP tool names to restrict to.

↑ Back to spec.bindings

spec.bindings.toolHintFilter

ToolHintFilter optionally gates call_tool on MCP tool annotation hints. Each non-nil filter field adds a Cedar when condition; multiple fields are ANDed.

Field	Type	Description
destructiveHint	boolean	DestructiveHint restricts call_tool to tools with destructiveHint matching this value.
readOnlyHint	boolean	ReadOnlyHint restricts call_tool to tools with readOnlyHint matching this value.

↑ Back to spec.bindings

spec.deny[]

Deny is the list of explicit deny rules. Each rule compiles to a Cedar forbid statement. In Cedar's evaluation model, forbid unconditionally overrides permit regardless of declaration order — a matching deny vetoes any permit that would otherwise grant access.

Field	Type	Description
actionsrequired	string[]	Actions is the list of MCP actions to deny.
prompts	string[]	Prompts optionally scopes the deny rule to specific MCP prompts.
resources	string[]	Resources optionally scopes the deny rule to specific MCP resource URIs.
tools	string[]	Tools optionally scopes the deny rule to specific MCP tools. When omitted alongside Prompts and Resources, the deny applies to all resources on the server.

↑ Back to spec

spec.targetRef

TargetRef identifies the MCP server this policy applies to.

Field	Type	Description
apiGroup	string	APIGroup is the API group of the target resource. Defaults to the OSS toolhive group; carried explicitly so future kinds can be added without a breaking change. default "toolhive.stacklok.dev"
kind	string	Kind is the kind of the target resource. Defaults to MCPServer. default "MCPServer" · enum: MCPServer | MCPRemoteProxy
namerequired	string	Name is the name of the target resource.

↑ Back to spec

status

ToolhiveAuthorizationPolicyStatus defines the observed state of ToolhiveAuthorizationPolicy.

Field	Type	Description
bindingCount	integer	BindingCount is the number of role bindings in the policy spec. Populated by the controller during reconciliation. format int32
compiledConfigMap	string	CompiledConfigMap is the name of the ConfigMap that holds the compiled policy.
conditions	object[]	Conditions represent the latest available observations of the policy's state.
denyCount	integer	DenyCount is the number of deny rules in the policy spec. Populated by the controller during reconciliation. format int32
observedGeneration	integer	ObservedGeneration is the metadata.generation last reconciled. format int64

status.conditions[]

Conditions represent the latest available observations of the policy's state.

Field	Type	Description
lastTransitionTimerequired	string	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. format date-time
messagerequired	string	message is a human readable message indicating details about the transition. This may be an empty string. maxLength 32768
observedGeneration	integer	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. format int64 · min 0
reasonrequired	string	reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. pattern ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ · minLength 1 · maxLength 1024
statusrequired	string	status of the condition, one of True, False, Unknown. enum: True | False | Unknown
typerequired	string	type of condition in CamelCase or in foo.example.com/CamelCase. pattern ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ · maxLength 316

↑ Back to status

Related resources

References:

• ClusterPlatformRole - via spec.bindings[].roleRef