Skip to main content

The identity, session, tenant model

Available

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

StackNGO separates who you are (your identity, verified at sign-in) from what you can do in a tenant (a session, decided by the tenant's policies). Understanding this split explains every 401, 403 or 409 message you will encounter.

In practice, it all comes down to three commands:

sng sso login                 # 1. identity: sign-in in the browser
sng tenant use acme           # 2. session on the tenant acme (1 h, renewed by sng)
sng secret list               # 3. an action, decided by the policies of acme

Prerequisites​

  • The sng CLI installed (Get started).
  • An account on https://auth.dev.stackngo.app (the StackNGO sign-in page).
  • A tenant where a policy has been attached to you (the creator of a tenant gets one automatically, see Policies).

The three steps​

1. The identity​

sng sso login opens your browser on the StackNGO sign-in page and stores your identity in ~/.config/stackngo/config.yaml. It proves who you are; it gives access to no tenant.

There are four forms of identity; yours is the first:

IdentityPrincipal to which policies are attachedHome tenant
User (sign-in in the browser)your user, and your org/name rolesnone
Machine application (client_credentials, declared by an IAMApplication)app:<name>none in this version (see Machines)
Application deployed on the platform—its tenant (not available yet)
CI job (GitLab or GitHub, declared by an IAMOIDCTrust)oidc:<tenant>/<trust>the trust's tenant

The last three are detailed in Machine identities and Secretless CI.

2. The tenant session​

sng tenant use acme exchanges your identity for a session of the tenant acme (POST /v1/iam/session). For a user to obtain it, a policy of the target tenant must grant them the action iam:AssumeRole on the resource tenant/acme. The managed policy assume-role does exactly that.

The session carries your identity, your roles and the tenant. It lasts 1 hour: the CLI opens a new one automatically when it expires. All tenant commands (sng apply, sng secret …, sng tenant policy …) use this session.

$ sng tenant use acme
current tenant: acme

A tenant you have just created responds 409 policies_pending for a few minutes: its default policies are not in force yet. sng tenant use waits and retries on its own (up to 6 minutes):

$ sng tenant use acme
waiting for the tenant default policies...
current tenant: acme

3. The action​

Each call carries an action (ssm:read, deploy:write…) and a resource (secret/db-password, app/api…). StackNGO looks through the policies attached to your identity in the session's tenant and decides:

  1. a matching Deny → denial, whatever there is elsewhere;
  2. otherwise a matching Allow → allowed;
  3. otherwise → denial (nothing is allowed by default).

The action catalog gives the action and resource of each command.

Switch tenants: assume​

You have a session on acme and need to act on acme-staging? Two ways:

  • sng tenant use acme-staging: starts again from your identity (the normal case for a person);
  • sng tenant assume acme-staging: exchanges the current session for a session on the other tenant (POST /v1/iam/session/assume). This is the way for scripts and machines, which only have a session to present.

In both cases, a policy of acme-staging must grant iam:AssumeRole on tenant/acme-staging. The session obtained by assume keeps track of the home tenant and never expires after the session it comes from: chaining assume calls does not extend access.

$ sng tenant assume acme-staging
current tenant: acme-staging (assumed from acme)

Overview​

The tenant boundary​

Like an account at a cloud provider, a tenant is a boundary: a policy only applies to the resources of its tenant, whatever its content. Even the admin policy (* on *) of acme gives nothing on acme-staging.

  • A request on a resource of another tenant is denied, whatever your policies (reason cross_tenant).
  • On the /v1/tenants/<tenant>/… routes, the tenant in the path must be that of the session, otherwise 403.
  • The tenant of a request comes only from the session. No header, no parameter lets you designate another one; the old X-Tenant-Token header is rejected (400).

To act on another tenant, you therefore need a session of that other tenant: sng tenant use or sng tenant assume.

What you can expect​

  • Deny by default: if a permission cannot be checked, the API responds 503 authorization service unavailable, never an allow. Try again a few moments later.
  • Delays: a granted or revoked right takes effect within a few minutes; removing a role takes effect when the session expires (1 h at most).

Messages you will encounter​

sng messageCauseWhat to do
not authenticated: run sng sso loginno stored identity, or expiredsng sso login
tenant session required: run sng tenant use NAMEtenant command without a sessionsng tenant use <tenant>
session expired: run sng tenant use NAME1 h session expired and renewal impossiblesng tenant use <tenant>
forbidden: no iam:AssumeRole on tenant/acme …no policy of acme grants you iam:AssumeRoleask an admin: sng tenant policy attach readonly -t acme --user vous --with-assume
forbidden (no policy of this tenant allows it…)action denied by the policiessng tenant policy list, then attach a suitable policy
policies_pendingnew tenant, more than 6 min of waitingretry sng tenant use
authorization service unavailable: retry laterpermission impossible to check for nowretry later

Going further​

  • The variables STNG_ACCESS_TOKEN, STNG_TENANT_TOKEN and STNG_TENANT replace the identity, session and tenant stored in ~/.config/stackngo/config.yaml: useful in CI.
  • Call details (bodies, codes) are in API authentication.
  • Isolation guarantees are summarized in Security and privacy.

See also​