init¶

init performs the one-time bootstrap of {{ product_name }}. It registers the global administrator OIDC resource-server configuration that every later administrator login validates against. This is the first command you run against a fresh deployment, before any host profile or interactive login exists.

Unlike every server-touching admin command, init does not require a prior profile authn login. It runs pre-OIDC: the request is authenticated by a JWT signed with the HMAC HS256 shared initialization secret that matches alpine.services.alpine-admin.initialization.secret in the server alpine.conf. No interactive OIDC login happens here. init only builds the administrator identity-provider validation settings (issuer, audience, discovery, fallbacks, timeouts) and hands them to the one-shot admin-init service.

Syntax¶

bin/admin.sh init [options]

Required options¶

These identify the administrator OpenID provider and are always required.

The administrator tenant identity (urn:alpine:tenant:admin) is set automatically; you do not pass a tenant option.

Conditionally required options¶

These combinations are enforced in code and fail fast at parse time.

Optional options¶

Standard CLI options are documented in Global options.

Example (discovery-based local JWT validation)¶

bin/admin.sh init \
  --oidc-issuer-claim https://login.example.com/realms/alpine \
  --oidc-audience-claim alpine-admin \
  --init-secret \
  -f json

Example (no discovery, explicit JWKS endpoint)¶

bin/admin.sh init \
  --oidc-issuer-claim https://login.example.com/realms/alpine \
  --oidc-audience-claim alpine-admin \
  --no-oidc-use-discovery \
  --oidc-jwks-url-override https://login.example.com/realms/alpine/protocol/openid-connect/certs \
  --oidc-clock-skew-seconds 60 \
  --oidc-connect-timeout-ms 2000 \
  --oidc-read-timeout-ms 2000 \
  -f yaml

Example (opaque token introspection)¶

bin/admin.sh init \
  --oidc-issuer-claim https://login.example.com/realms/alpine \
  --oidc-audience-claim alpine-admin \
  --oidc-token-mode OIDC_TOKEN_MODE_OPAQUE_INTROSPECT \
  --oidc-allow-introspection-fallback \
  --oidc-introspection-client-id alpine-admin \
  --oidc-introspection-client-secret \
  --oidc-introspection-url-override https://login.example.com/realms/alpine/protocol/openid-connect/token/introspect \
  --init-secret \
  -f json

Next steps¶

After init reports success, the administrator can connect and log in:

1. Create a host profile with profile hosts create.
2. Authenticate against that profile with profile authn login.

Host connection profiles — including their embedded OIDC logins (with PIN-sealed tokens) — are stored under ${HOME}/.config/alpinepki/hosts/.

Authorizing the bootstrap administrator¶

init registers only how administrator tokens are validated (issuer, audience, signature, token mode). It does not grant access on its own. Authorization is resolved from claims carried inside the OIDC access token that your identity provider issues to the administrator. For the first administrator to have full control, that token must resolve to the seeded bootstrap administrator role — the global, tenant-less platform-super-admin template role, which holds the complete set of ADMIN-scope permissions.

The administrator's token must therefore carry both of these claims:

The value in urn::alpine:roles is a JSON array of role references. Each reference is matched against the seeded role by template key (platform-super-admin), then role UUID (rol-…), then role name. Use the immutable template key platform-super-admin: it is stable across environments, unlike the generated UUID. Additional group/role references may appear in the same array.

Example administrator token claims (decoded):

{
  "iss": "https://login.example.com/realms/alpine",
  "aud": "alpine-admin",
  "sub": "ops-admin",
  "urn::alpine:tenantId": "urn:alpine:tenant:admin",
  "urn::alpine:roles": ["platform-super-admin"]
}

At your identity provider, map the bootstrap administrator so the issued token emits urn:alpine:tenant:admin in urn::alpine:tenantId and platform-super-admin in urn::alpine:roles (for example, via a group-to-claim mapping or a protocol/claim mapper).

Related¶

• Admin CLI overview
• Command map
• Global options

FAQ¶