identity

identity

When to use this skill

• User asks to create a user, service account, role, role binding, or API key.
• User asks "who has access to X", "how do I grant Y", or mentions RBAC.
• User mentions an OIDC provider (Okta, Auth0, Azure AD) or identity pool (federated login).
• User wants to rotate, revoke, or expire an API key.
• User needs to store a secret for use by a function/connector.

Execution base

Prefer StreamNative Cloud remote MCP when available: use sncloud_identity_read / sncloud_identity_write for supported identity resources; use sncloud_resource_catalog / sncloud_resource_schema before writes. See ../cloud-core/references/remote-mcp.md. Use snctl fallback for APIKey, Secret, and service-account key export/activation because current remote MCP surface does not manage them.

Prerequisites check

Remote MCP route: start with sncloud_context_whoami, then catalog/schema for identity domain. snctl route: standard checks (see cloud-core). Identity mutations require admin-tier permissions in the target org — if calls 403, the acting principal itself needs a ServiceAccountBinding to an admin ClusterRole.

Mental model

Two kinds of principals:

• User — a human, authenticated via OIDC (native StreamNative login, or federated via OIDCProvider + IdentityPool).
• ServiceAccount — a non-human principal; authenticates via a downloaded JSON key or an APIKey.

Authorization comes in two layers:

• Control-plane (cloud-level) grants: ServiceAccountBinding → ClusterRole (admin, editor, viewer). Governs what the SA can do via snctl (create clusters, etc.).
• Data-plane (Pulsar-level) grants: Role + RoleBinding. Scoped to a Pulsar tenant/namespace; governs produce/consume/functions/sinks/sources.

Secret is a separate kind (standard Kubernetes Secret) for storing credentials consumed by workspace functions and connectors.

Primary workflows

For remote MCP writes, compose JSON-string manifests and call sncloud_identity_write with operation=apply, dry_run=true; only repeat with dry_run=false after validation. Use sncloud_identity_read for list/get. Do not use remote MCP for APIKey or Secret lifecycle; use snctl workflows below.

W1. Create a service account and grant it admin on the org

snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/serviceaccount.yaml
snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/serviceaccount-binding.yaml
# Export its private key (for activation elsewhere — see cloud-core)
snctl auth export-service-account my-sa -n my-org -O my-org --key-file ./my-sa.json

W2. Create an API key for automation

# Create SA first (W1), then:
snctl create apikey my-key --service-account-name my-sa --expiration-time 30d -O my-org
# Or with an absolute expiration
snctl create apikey my-key --service-account-name my-sa --expiration-time "2026-06-01T00:00:00Z" -O my-org
# Revoke
snctl revoke apikey my-key -O my-org

W3. Grant Pulsar-level permissions via Role + RoleBinding

snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/role.yaml
snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/rolebinding.yaml
snctl get role,rolebinding -n my-org -o yaml

W4. Invite a human user

User.metadata.name must be the invite email address.

snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/user.yaml
# An invite email is sent to spec.email; the user accepts via the Console
snctl get user [email protected] --organization my-org

W5. Federated login with an external OIDC provider

snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/oidcprovider.yaml
snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/identitypool.yaml
# After this, users in the pool can log in via their corporate IdP

W6. Store a secret for a workspace function/connector

snctl apply -f ${CLAUDE_PLUGIN_ROOT}/skills/identity/assets/manifests/secret.yaml
snctl get secret my-secret -n my-org -o yaml

W7. List / describe / delete

snctl get serviceaccount,user,role,rolebinding,apikey,secret -n my-org
snctl describe serviceaccount my-sa -n my-org
snctl delete apikey my-key -O my-org
snctl delete rolebinding my-rolebinding -n my-org
snctl delete role my-role -n my-org
snctl delete serviceaccountbinding my-sa-binding -n my-org
snctl delete serviceaccount my-sa -n my-org

Reference index

• references/rbac-model.md — roles vs cluster roles, scope semantics.
• references/service-accounts.md — SA lifecycle, key rotation.
• references/api-keys.md — expiration formats, revocation.
• references/oidc-identity-pools.md — federated login setup.
• references/secrets.md — secret types, how to reference from functions/connectors.

Pitfalls and gotchas

• Remote MCP identity surface does not manage APIKey or StreamNative Cloud Secret; keep those snctl-only.
• Remote MCP sncloud_identity_write manifest is JSON string, not YAML/object. Omit status and read-only metadata copied from read output.
• Secret objects are NOT encrypted at rest in the exported YAML; treat them as sensitive and NEVER commit real values.
• API key creation with --expiration-time 0 means "never expires" — strongly discouraged; prefer a TTL like 30d or 90d.
• Exported service-account JSON keys contain a private key; rotate periodically — the preferred rotation path is to create a new SA, migrate consumers, and delete the old one.
• ServiceAccountBinding grants CONTROL-plane permissions (what the SA can do via snctl); RoleBinding grants DATA-plane permissions (what the SA can do on Pulsar topics). These are independent and both may be needed.
• Deleting a User does NOT invalidate their active sessions immediately; use the Console to force-sign-out.
• IdentityPool claim mappings must match the upstream IdP's actual claims — verify by decoding a sample JWT from the IdP (jwt.io).
• ClusterRole is a pre-defined set (typically admin, editor, viewer); you do NOT create custom cluster roles via snctl.
• Pulsar permission verbs are limited: produce, consume, functions, sinks, sources. Anything else is rejected.