Machine identities

Available

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

A machine has no browser: it proves its identity another way, then obtains a tenant session like you. It can do nothing there until a policy is attached to it.

Identity	For whom	What it presents	Principal to attach
Machine application	a server, a script, one of your applications	a client ID and a client secret (`client_credentials`)	`--app <name>`
CI job	GitLab CI, GitHub Actions	its own job identity, without a secret, via an `IAMOIDCTrust`	`--oidc-trust <name>`

Applications deployed on the platform

An application running on the platform will be able to obtain a session of its tenant without any secret. This path is not available yet from an App manifest: in the meantime, give it a machine application and pass it its credentials as a secret.

Prerequisites

A session on the tenant: sng tenant use acme.
policy:admin to attach (policy admin).

Option A: a machine application (`client_credentials`)

1. Declare the application

ci-deployer.yml
apiVersion: iam.stackngo.io/v1alpha1
kind: IAMApplication
metadata:
  name: ci-deployer
spec:
  displayName: Déployeur externe
  grantTypes: [client_credentials]
  token:
    expireInHours: 1

sng apply ci-deployer.yml

2. Find its name and its credentials

sng kind get IAMApplication ci-deployer --json      # status.provider.name = sng-<fingerprint>-app-ci-deployer
sng iam app credentials ci-deployer            # clientId, clientSecret, issuer

status.provider.name gives the full name of the application (to pass to sng tenant policy attach --app); credentials displays its clientId and its clientSecret (action auth:ReadCredentials, policy admin). For one of your App resources, the same credentials are available under the name ci-deployer-oidc (keys clientId, clientSecret, issuer), to reference like a secret in env:

env:
  CLIENT_ID: { secret: ci-deployer-oidc, key: clientId }
  CLIENT_SECRET: { secret: ci-deployer-oidc, key: clientSecret }

3. Attach a policy

sng tenant policy attach readwrite --app sng-1a2b3c4d-5e6f7a8b-app-ci-deployer --with-assume

--with-assume is required: in this version, a machine application has no home tenant. It must receive assume-role and specify the tenant when opening its session.

4. Obtain a session from the machine

# 1. identity with the sign-in service
ACCESS=$(curl -s -X POST https://auth.dev.stackngo.app/api/login/oauth/access_token \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" \
  | jq -r .access_token)
# 2. session on the tenant
SESSION=$(curl -s -X POST https://api.dev.stackngo.fr/v1/iam/session \
  -H "Authorization: Bearer $ACCESS" -H "Content-Type: application/json" \
  -d '{"tenant":"acme"}' | jq -r .access_token)
# 3. a call
curl -s https://api.dev.stackngo.fr/v1/secrets -H "Authorization: Bearer $SESSION"

With the CLI, the first two steps take two commands:

sng sso login --client-credentials --client-id "$CLIENT_ID" --client-secret "$CLIENT_SECRET"
sng tenant use acme
sng secret list

--client-id and --client-secret can also come from STNG_OAUTH_CLIENT_ID and STNG_OAUTH_CLIENT_SECRET, so that nothing is left in the command history.

Option B: a CI job (OIDC, without a secret)

GitLab CI and GitHub Actions give an identity to each job. An IAMOIDCTrust tells StackNGO to accept it; no secret is stored in the CI. The complete guide is Secretless CI (OIDC); the principal to attach is --oidc-trust <name>.

Verification

sng tenant policy principals readwrite

STATE      KIND  ID
applied    app   sng-1a2b3c4d-5e6f7a8b-app-ci-deployer
requested  app   sng-1a2b3c4d-5e6f7a8b-app-ci-deployer

And from the machine, a call that succeeds: GET /v1/secrets responds 200; without a policy, 403 forbidden.

What you can expect

A machine session lasts 1 h at most: replay POST /v1/iam/session on expiration (401).
To act on another tenant from a session: POST /v1/iam/session/assume with {"tenant": "autre"}, if a policy of the other tenant grants iam:AssumeRole to your application.
The image registry and the secrets service accept the same session (Authorization: Bearer), with the registry:* and ssm:* actions of the catalog.

Common errors

Symptom	Cause	Fix
`401 invalid identity token` on `POST /v1/iam/session`	identity expired or badly copied	request an identity again (step 4.1)
`400 tenant required`	`tenant` missing from the body	add `{"tenant": "acme"}`
`403 forbidden: no iam:AssumeRole on tenant/acme`	`assume-role` not attached to the application	`sng tenant policy attach assume-role --app …`
`403 forbidden` on a tenant route	session obtained but no policy	`sng tenant policy attach … --app …`

Prerequisites​

Option A: a machine application (client_credentials)​

1. Declare the application​

2. Find its name and its credentials​

3. Attach a policy​

4. Obtain a session from the machine​

Option B: a CI job (OIDC, without a secret)​

Verification​

What you can expect​

Common errors​

See also​