Import from a file

--from config imports a realm from a FerrisKey-native description file. The format comes from the extension: .yaml, .yml, or .toml. No external system is involved.

ferris-ctl realm import --from config --file realm.yaml

Preview without writing anything:

ferris-ctl realm import --from config --file realm.yaml --dry-run -o yaml

Format

A description carries a name, plus optional settings, roles, clients, and users sections. The ferriskey-cli repository ships a starting point at examples/realm.yaml.

name: acme

settings:
  access_token_lifetime: 300
  refresh_token_lifetime: 1800
  user_registration_enabled: true
  forgot_password_enabled: true

roles:
  - name: admin
    description: Realm administrators
    permissions:
      - manage_realm
      - manage_users
  - name: viewer
    description: Read-only access
    permissions:
      - view_users
      - view_clients

clients:
  - client_id: web-app
    name: Web Application
    client_type: public
    public_client: true
    redirect_uris:
      - https://app.acme.test/callback
      - https://app.acme.test/*
  - client_id: backend
    name: Backend Service
    client_type: confidential
    service_account_enabled: true
    direct_access_grants_enabled: true
    roles:
      - name: service-reader
        description: Service-scoped read role

users:
  - username: alice
    email: alice@acme.test
    firstname: Alice
    lastname: Doe
    email_verified: true
    roles:
      - admin
  - username: bob
    email: bob@acme.test
    roles:
      - viewer

The same keys work in TOML. Sections that hold a list become arrays of tables:

name = "acme"

[settings]
access_token_lifetime = 300
user_registration_enabled = true

[[roles]]
name = "admin"
description = "Realm administrators"
permissions = ["manage_realm"]

[[clients]]
client_id = "web-app"
client_type = "public"
public_client = true
redirect_uris = ["https://app.acme.test/callback"]

[[clients.roles]]
name = "reader"

[[users]]
username = "alice"
email = "alice@acme.test"
roles = ["admin", "web-app:reader"]

Settings

Every setting is optional. Anything you leave out keeps the FerrisKey default. Settings are sent again on every run, so they overwrite the realm’s current values each time.

Roles

Permissions use the names from the permissions reference, so manage_realm, not ManageRealm and not realm:manage.

The identity that runs the import can only grant permissions it holds. Without manage_realm, a role that lists a permission the identity lacks, or a name FerrisKey does not know, is refused with 403 cannot grant a permission you do not hold, and the import stops. With manage_realm, a name FerrisKey does not recognize is accepted and dropped, so the role is created with fewer permissions than the file lists.

Clients

A client that already exists is not modified, apart from require_pkce and the lifetimes, which are sent again on every run. Redirect URIs, web origins, and roles missing from it are added. The report lists the secret of each confidential client; see the import report.

Users

A plain name in roles refers to a realm role. Prefix it with a client id to pick a role scoped to that client:

users:
  - username: alice
    roles:
      - admin              # realm role
      - backend:service-reader   # role of the "backend" client

A client_id:role that no client in the file defines and that the client does not already hold stops the import. A plain name that matches no realm role only produces a warning, and that assignment is skipped.

Passwords

Without a credential, a user arrives with no password. Set one afterwards with ferris-ctl user set-password, from the admin console, or through a recovery flow. To carry an existing password over, give the user the hash it already has:

users:
  - username: alice
    credential:
      algorithm: bcrypt
      secret_data: "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy"
      hash_iterations: 10

The import stores the hash as is and never marks it temporary. FerrisKey re-encodes it as Argon2id the first time the user signs in; Export & Import explains how. A user who already has a password keeps it. A refused hash adds a warning and counts in passwords_failed, and the import carries on.

A file that holds password hashes is as sensitive as the password store it came from. Keep it out of version control. The --dry-run output redacts the hashes, the file does not.

Fixed ids

With id, the user is created with that UUID, which keeps every identifier that points at the user valid. The import stops with an error if the server creates the user under a different id, or if the id already belongs to another user.