IAMPolicyBinding

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

apiVersion	iam.stackngo.io/v1alpha1
kind	IAMPolicyBinding
Applied by	sng tenant policy attach / detach (or POST /v1/iam/policies/{name}/attach, PUT /v1/iam/bindings/{name}), not by sng apply
Related commands	sng tenant policy attach · detach · principals, sng tenant policy delete

What it is for

An IAMPolicyBinding says who a tenant IAMPolicy applies to: users, SSO roles, machine applications, CI OIDC trusts. Each policy has at most one binding written by the API, named bind-<policy>. You do not write it: sng tenant policy attach and detach maintain it, and sng tenant policy principals reads it. It is also how you add someone to a tenant (attach assume-role).

Minimal example

sng tenant policy attach readonly --user bob --with-assume

produces, in the tenant's desired state:

bind-readonly.yml (written by the API)

apiVersion: iam.stackngo.io/v1alpha1
kind: IAMPolicyBinding
metadata:
  name: bind-readonly
spec:
  policyRef:
    name: readonly
  subjects:
    users: [bob]

(and an equivalent bind-assume-role for --with-assume).

Complete annotated example

bind-ops-read.yml (written by the API, read-only)

apiVersion: iam.stackngo.io/v1alpha1
kind: IAMPolicyBinding
metadata:
  name: bind-ops-read                  # always bind-<policy>
spec:
  policyRef:
    name: ops-read                     # IAMPolicy in the same tenant (or a managed policy)
  subjects:                            # at least one subject; at most 256 per list; no wildcard
    users:                             # --user: name, org/name, or email; resolved to a sub
      - bob
      - alice@acme.example
    roles:                             # --role: platform SSO role, org/name
      - stackngo/sre
    applications:                      # --app: SSO name of an IAMApplication (status.provider.name)
      - sng-1a2b3c4d-5e6f7a8b-app-ci-deployer
    oidcTrusts: [gitlab-deploy]        # --oidc-trust: IAMOIDCTrust of the tenant (Beta)

CLI equivalent:

sng tenant policy attach ops-read \
  --user bob --user alice@acme.example --role stackngo/sre \
  --app sng-1a2b3c4d-5e6f7a8b-app-ci-deployer \
  --oidc-trust gitlab-deploy

Fields

Cross-field validation rules

No CEL rule. The API checks each subject as early as sng tenant policy attach (400 otherwise), and the CLI before it:

• users: a name, org/nom, or an email address (letters, digits, ., _, @, +, -).
• roles: the org/nom form is required.
• applications: an SSO application name.
• oidcTrusts: a trust name in the tenant (DNS label, without /).
• No empty value, no global *: a group of users is represented by a role.
• policyRef.name refers to an existing policy in the tenant or a managed policy; otherwise 404.

IAMPolicyBinding

IAMPolicyBinding attache une IAMPolicy de votre tenant à des sujets : utilisateurs, rôles, applications ou émetteurs OIDC de confiance.

Champ	Description	Défaut	Validation
apiVersion string	iam.stackngo.io/v1alpha1
kind string	IAMPolicyBinding
metadata ObjectMeta	Seul metadata.name est à renseigner (nom de la ressource dans votre tenant).
spec IAMPolicyBindingSpec
status IAMPolicyBindingStatus

IAMPolicyBindingSpec

Champ	Description	Défaut	Validation
policyRef ObjectReference	IAMPolicy à attacher, dans votre tenant.
subjects IAMPolicySubjects	Utilisateurs et rôles auxquels la policy s'applique.
deletionPolicy DeletionPolicy	Delete (défaut) : supprimer l'IAMPolicyBinding détache la policy de ses sujets. Orphan : les rattachements restent en vigueur.	Delete	Enum: [Delete Orphan] Optional: {}

IAMPolicyBindingStatus

Champ	Description	Défaut	Validation
observedGeneration integer	Dernière version du manifeste (metadata.generation) prise en compte par la plateforme.
provider ProviderStatus	Identité de la ressource dans le service d'authentification.
lastSyncedAt Time	Date de la dernière prise en compte réussie du manifeste.		Optional: {}
conditions Condition array	Conditions décrivant l'état actuel de la ressource (Ready…).
tenant string	Tenant auquel appartient le rattachement. Renseigné par la plateforme.
policy string	Policy à laquelle les principaux ci-dessous sont attachés.
appliedPrincipals string array	Principaux attachés par ce binding ("kind:id"), triés.
unresolvedUsers string array	Utilisateurs de spec.subjects.users sans compte (ou référence invalide), ignorés tant qu'ils ne sont pas résolus ; les autres sujets sont appliqués. Les 64 premiers, dans l'ordre de la spec.		MaxItems: 64 Optional: {}

ObjectReference

ObjectReference désigne une autre ressource IAM de votre tenant.

Champ	Description	Défaut	Validation
name string	Nom de la ressource désignée, dans votre tenant.		MaxLength: 253 MinLength: 1

IAMPolicySubjects

IAMPolicySubjects : sujets auxquels la policy s'applique. Aucun joker global n'est accepté ; pour viser un groupe d'utilisateurs, utilisez un rôle.

Champ	Description	Défaut	Validation
users string array	Utilisateurs de l'annuaire : nom (organisation de la plateforme), org/nom ou e-mail.		MaxItems: 256
roles string array	Rôles de l'annuaire, au format org/nom.		MaxItems: 256
applications string array	Applications machine externes, désignées par le nom affiché dans status.provider.name de leur IAMApplication.		MaxItems: 256
oidcTrusts string array	Noms d'IAMOIDCTrust du tenant du binding ; leurs sessions ont pour principal oidc:<tenant>/<nom>.		MaxItems: 256

DeletionPolicy

Type sous-jacent : string

DeletionPolicy indique ce que devient la ressource quand vous supprimez son manifeste : Block bloque la suppression tant que la ressource est encore utilisée, Orphan la conserve, Delete la supprime.

Règles de validation :

• Enum: [Block Orphan Delete]

Valeur	Description
Block	Non accepté pour un IAMPolicyBinding : utilisez Delete ou Orphan.
Orphan	Supprime le manifeste mais conserve la ressource créée.
Delete	Supprime la ressource avec le manifeste, sans vérifier son usage.

ProviderStatus

ProviderStatus identifie la ressource dans le service d'authentification.

Champ	Description	Défaut	Validation
owner string	Organisation propriétaire de l'objet dans l'annuaire d'identité. Renseigné par la plateforme.
name string	Nom de l'objet dans l'annuaire d'identité. Renseigné par la plateforme.
resourceID string	Identifiant de l'objet dans l'annuaire d'identité. Renseigné par la plateforme.

Status and conditions

You read it through the CLI:

sng tenant policy principals ops-read

STATE      KIND  ID
applied    user  7f3e2c1a-0b5d-4c1e-9a77-2d0c4e8f1b23
requested  user  bob

• applied: principals in effect, with resolved identifiers (user:<sub>, role:org/nom, app:<nom>, oidc:<tenant>/<trust>);
• requested: subjects as requested in the desired state.

On the object side: status.policy, status.tenant, status.appliedPrincipals (principals attached by this binding, kind:id), Ready condition.

Reason (Ready=False)	Meaning	Corrective action
WaitingForPolicy	the targeted policy is not applied yet	wait a few moments
InvalidReference	a subject could not be resolved (user unknown to the SSO, for example) or was rejected	sng tenant policy detach the faulty subject
UnsupportedConfiguration	the manifest breaks a subject rule	fix with detach / attach
ScopeUnresolved	the binding's tenant could not be determined	automatic retry; if it persists, contact support
ProviderUnavailable	identity service temporarily unreachable	automatic retry
InsufficientRBAC	platform-side incident	contact support

What happens when you attach, detach, or delete

Attach. sng tenant policy attach adds the subjects to the bind-<policy> binding (202, status: "pending"). A few moments later, the subjects move to applied: a user is recognized by their stable identifier (sub), even if renamed.

Detach. sng tenant policy detach removes the subjects; a binding without subjects is deleted. A subject keeps the permission as long as another binding of the same policy carries it: the attachments created with the tenant (the creator on admin and assume-role, the platform's own access) stay in place alongside yours.

Delete the policy. sng tenant policy delete also deletes bind-<policy>. Deleting an OIDC trust or a user leaves the binding in place, with no effect: a deleted user shows up as InvalidReference.

Common errors

Symptom	Cause	Fix
at least one --user, --role, … is required	no subject	add a subject flag
--role "sre": expected org/NAME	role without an organization	--role stackngo/sre
subjects must be explicit (no empty value, no global *)	wildcard or empty value	name each subject
404 not found	the targeted policy does not exist	sng tenant policy list
The user only stays in requested	processing in progress, or user unknown to the SSO (InvalidReference)	wait; check the spelling
A user attached to readonly cannot run sng tenant use	readonly does not include iam:assumerole	attach … --with-assume
--app attached with no effect	manifest name instead of the SSO name	status.provider.name of the IAMApplication

See also

• Guides: Attach a policy, Machines and technical accounts, Deploy without secrets (OIDC)
• CLI: sng tenant policy attach
• Other kinds: IAMPolicy, IAMOIDCTrust, IAMApplication