Okta to Scoped Agent Tokens
This guide shows how to connect your Okta identity provider to the Claw EA capability token system. The result: an agent's permissions are derived from the requesting user's Okta group membership, and every action carries a token scope hash that ties it to the exact permission set.
How It Works
The flow is: Okta OIDC token → clawscope (token issuer) → CST (Capability Scoped Token) → agent execution → receipts with token_scope_hash
- User authenticates via Okta and receives an OIDC token with group claims
- clawscope validates the OIDC token and maps groups to CST scopes
- CST is issued with: allowed tools, allowed models, egress endpoints, and optional policy pin
- Agent receives the CST and operates within its scope
- Every receipt includes the
token_scope_hash— auditors can verify scope was enforced
Step 1: Define the scope mapping
Map Okta groups to CST claim sets. Example:
{
"scope_mappings": [
{
"okta_group": "platform-engineers",
"cst_claims": {
"allowed_tools": ["github", "argo-cd", "terraform"],
"allowed_models": ["claude-sonnet-4-20250514", "gpt-4o"],
"egress_allowlist": ["api.github.com", "*.atlassian.net"],
"max_ttl_seconds": 3600
}
},
{
"okta_group": "security-analysts",
"cst_claims": {
"allowed_tools": ["splunk", "jira", "servicenow"],
"allowed_models": ["claude-sonnet-4-20250514"],
"egress_allowlist": ["*.splunkcloud.com"],
"max_ttl_seconds": 1800
}
}
]
}The scope mapping is the policy bridge between your identity provider and agent execution. It answers: "What can agents do on behalf of users in this group?"
Step 2: Pin policy to tokens
Optionally, bind a Work Policy Contract hash to the CST. This ensures the agent operates under a specific, immutable policy document.
{
"policy_pin": {
"policy_hash_b64u": "sha256-hash-of-wpc-json",
"policy_version": "deploy-approval-v3"
}
}When the agent presents this CST to clawproxy, the gateway verifies the policy pin matches the active policy. If it does not match, the request is denied. Fail-closed.
Step 3: Verify the audit trail
After execution, every gateway receipt will carry:
token_scope_hash_b64u— deterministic hash of the CST claimsbinding.run_id— ties the receipt to a specific runbinding.event_hash_b64u— ties the receipt to a specific event in the proof bundle
An auditor can verify: the user was in the expected Okta group, the CST had the correct scope, and the receipts prove the agent operated within that scope.