Command line

The odudu command is both the server and the commands an operator runs against it. With no command it starts the server; the commands below do one thing and exit. They read the same environment as the server, described under configuration.

Usage

Usage: odudu <command> [options]

Run with no command to start the server.

Commands:
  --version         Print the version of this build, or dev outside a release
                    image.
  client-origins    Rebuild the stored client origins after upgrading past the
                    migration adding them.
  console           Provision the admin console for every tenant, generate its
                    key or sign in as it.
  help              Print the commands, or the options of one command. Also
                    --help and -h.
  init              Create the database roles, migrate, create the system tenant
                    and the first administrator, and write quickstart.env. Safe
                    to run again.
  reap              Delete expired and retention-bound rows in every tenant and
                    print the counts as JSON.
  seed              Create tenants, clients, users, roles, groups and scopes.
                    Without a subcommand it creates a client in one call.
  send-logouts      Deliver the queued back-channel logout tokens once and print
                    the outcome as JSON.
  send-mail         Deliver the queued emails once and print the outcome as
                    JSON.

Run `odudu help <command>` for the options of one command,
and `odudu --version` to print the version.

--version

Print the version of this build, or dev outside a release image.

odudu --version

Example:

odudu --version

client-origins

Rebuild the stored client origins after upgrading past the migration adding them.

odudu client-origins <command> [options]

Example:

odudu client-origins rebuild

rebuild

Rewrite every client origin from its web origins and redirect URIs.

odudu client-origins rebuild

Example:

odudu client-origins rebuild

console

Provision the admin console for every tenant, generate its key or sign in as it.

odudu console <command> [options]

Example:

odudu console provision

assertion

Print a one-minute client assertion that authenticates the console client.

odudu console assertion [options]

--tenant <value> (required): Name of the tenant whose token endpoint it is for.

Example:

odudu console assertion --tenant acme

keygen

Print a new ODUDU_CONSOLE_CLIENT_KEY line for the environment.

odudu console keygen

Example:

odudu console keygen

provision

odudu console provision

Example:

odudu console provision

help

Print the commands, or the options of one command. Also --help and -h.

odudu help

Example:

odudu help seed client

init

Create the database roles, migrate, create the system tenant and the first administrator, and write quickstart.env. Safe to run again.

odudu init [options]

--admin-email <value>: Email address of the first administrator, who signs in with it. Defaults to ODUDU_ADMIN_EMAIL, then admin@odudu.local when there is no terminal to ask on or ODUDU_ADMIN_PASSWORD is set.
--state-dir <value>: Directory that holds quickstart.env. Defaults to /var/lib/odudu.
--add-admin: Add an administrator when the system tenant already has one; without it a different --admin-email is refused.
--public-base-url <value>: Address the server is reached at, loopback only. Defaults to ODUDU_PUBLIC_BASE_URL, then http://localhost:3000.

Example:

odudu init --admin-email ada@example.com

reap

Delete expired and retention-bound rows in every tenant and print the counts as JSON.

odudu reap

Example:

odudu reap

seed

Create tenants, clients, users, roles, groups and scopes. Without a subcommand it creates a client in one call.

odudu seed <command> [options]

--tenant <value> (required): Name of the tenant to create the client in.
--client <value> (required): The client_id to create.
--client-secret <value>: Register a confidential client with this secret.
--token-endpoint-auth-method <value>: client_secret_basic or client_secret_post, for a confidential client.
--redirect-uri <value>: A redirect URI the client may use. (repeatable)
--user <value>: Username of a user to create with the client.
--password <value>: The password of that user.
--email <value>: The email address of that user.
--send-verification-email: Queue a verification email for that user.
--issuer-base <value>: Base URL to print the issuer under, in place of the default.

Example:

odudu seed tenant --name acme

admin

Create an administrator in the system tenant and print a one-time password.

odudu seed admin [options]

--username <value> (required): Username of the system-tenant administrator.

Example:

odudu seed admin --username root

assign-scope

Assign a client scope to a client as default or optional.

odudu seed assign-scope [options]

--tenant <value> (required): Name of the tenant the command acts in.
--client-id <value> (required): The client_id of the client the command acts on.
--scope <value> (required): Name of the client scope to assign.
--assignment <value> (required): default or optional.

Example:

odudu seed assign-scope --tenant acme \
    --client-id web --scope reports --assignment default

client

odudu seed client [options]

--tenant <value> (required): Name of the tenant the command acts in.
--client-id <value> (required): The client_id to create. The command fails if that client exists; change an existing client in the console or the admin API.
--public: Register a public client; accepts --public or --client-secret, not both.
--client-secret <value>: Register a confidential client with this secret instead.
--token-endpoint-auth-method <value>: client_secret_basic or client_secret_post, for a confidential client.
--redirect-uri <value>: A redirect URI the client may use. (repeatable)
--post-logout-redirect-uri <value>: A URI the client may send users to after logout. (repeatable)
--web-origin <value>: A browser origin allowed to call the endpoints. (repeatable)
--grant-type <value>: A grant type the client may use. (repeatable)
--consent-required: Ask people to allow access the first time they sign in.
--client-credentials-scope <value>: A scope a service may ask for with the client_credentials grant; a service gets none without it. (repeatable)

Example:

odudu seed client --tenant acme \
    --client-id web --public --redirect-uri https://app.example/cb

grant-role

Grant a role to a user.

odudu seed grant-role [options]

--tenant <value> (required): Name of the tenant the command acts in.
--username <value> (required): Username of the user the command acts on.
--role <value> (required): Role name, qualified by its client for a client role.

Example:

odudu seed grant-role --tenant acme --username ada --role editor

group

Create a group, optionally under a parent group.

odudu seed group [options]

--tenant <value> (required): Name of the tenant the command acts in.
--name <value> (required): Name of the group to create.
--parent <value>: Path of the parent group; omit for a top-level group.

Example:

odudu seed group --tenant acme --name staff

join-group

Add a user to a group.

odudu seed join-group [options]

--tenant <value> (required): Name of the tenant the command acts in.
--username <value> (required): Username of the user the command acts on.
--group <value> (required): Path of the group to join.

Example:

odudu seed join-group --tenant acme --username ada --group /staff

map-group-role

Give every member of a group a role.

odudu seed map-group-role [options]

--tenant <value> (required): Name of the tenant the command acts in.
--group <value> (required): Path of the group that receives the role.
--role <value> (required): Role name, qualified by its client for a client role.

Example:

odudu seed map-group-role --tenant acme --group /staff --role editor

map-role

Make a client scope carry a role.

odudu seed map-role [options]

--tenant <value> (required): Name of the tenant the command acts in.
--scope <value> (required): Name of the client scope whose tokens carry the role.
--role <value> (required): Role name, qualified by its client for a client role.

Example:

odudu seed map-role --tenant acme --scope reports --role editor

profile

Set the standard profile claims of a user.

odudu seed profile [options]

--tenant <value> (required): Name of the tenant the command acts in.
--username <value> (required): Username of the user the command acts on.
--name <value>: Full name of the user.
--given-name <value>: Given name of the user.
--family-name <value>: Family name of the user.
--middle-name <value>: Middle name of the user.
--nickname <value>: Nickname of the user.
--preferred-username <value>: The preferred_username claim of the user.
--profile <value>: URL of the profile page of the user.
--picture <value>: URL of the picture of the user.
--website <value>: URL of the website of the user.
--gender <value>: Gender of the user.
--birthdate <value>: Birthdate of the user, as YYYY-MM-DD.
--zoneinfo <value>: Time zone of the user, such as Europe/Berlin.
--locale <value>: Locale of the user, such as de-DE.
--phone-number <value>: Phone number of the user.
--email-verified: Record the email address as verified; the user needs one.
--phone-number-verified: Record the phone number as verified.
--address-formatted <value>: The whole postal address as one string.
--address-street <value>: Street part of the postal address.
--address-locality <value>: City part of the postal address.
--address-region <value>: State or region part of the postal address.
--address-postal-code <value>: Postal code part of the postal address.
--address-country <value>: Country part of the postal address.

Example:

odudu seed profile --tenant acme --username ada --given-name Ada

registration-token

Mint an initial access token for dynamic client registration.

odudu seed registration-token [options]

--tenant <value> (required): Name of the tenant the command acts in.
--uses <value> (required): How many registrations the token may authorise.
--ttl <value> (required): How long the token is valid, in seconds.

Example:

odudu seed registration-token --tenant acme --uses 1 --ttl 3600

restore-scopes

Create the built-in client scopes a tenant has lost, with their shipped settings.

odudu seed restore-scopes [options]

--tenant <value> (required): Name of the tenant the command acts in.

Example:

odudu seed restore-scopes --tenant acme

role

Create a role, tenant-wide or owned by a client.

odudu seed role [options]

--tenant <value> (required): Name of the tenant the command acts in.
--name <value> (required): Name of the role to create.
--client-id <value>: Make this a client role owned by that client.

Example:

odudu seed role --tenant acme --name editor

scope

Create or update a client scope.

odudu seed scope [options]

--tenant <value> (required): Name of the tenant the command acts in.
--name <value> (required): Name of the client scope to create. The command fails if it exists.
--description <value>: A description of the scope.
--include-in-id-token <value>: true or false: put the scope claims in the ID token.
--include-in-access-token <value>: true or false: put the scope claims in the access token.

Example:

odudu seed scope --tenant acme --name reports

tenant

Create a tenant with its signing key, or change its settings.

odudu seed tenant [options]

--name <value> (required): Name of the tenant to create, or to update when it exists.
--set <value>: A tenant setting as name=value. (repeatable)

Example:

odudu seed tenant --name acme --set registration_allowed=true

user

Create a user with a password.

odudu seed user [options]

--tenant <value> (required): Name of the tenant the command acts in.
--username <value> (required): Username of the user to create.
--password <value> (required): The initial password; it must satisfy the tenant policy.
--email <value>: The email address of the user.
--email-verified: Record the email address as verified; needs --email.
--require-password-change: Make the user choose a new password at first login.

Example:

odudu seed user --tenant acme \
    --username ada --password "a long passphrase"

send-logouts

Deliver the queued back-channel logout tokens once and print the outcome as JSON.

odudu send-logouts

Example:

odudu send-logouts

send-mail

Deliver the queued emails once and print the outcome as JSON.

odudu send-mail

Example:

odudu send-mail

Usage​

--version​

client-origins​

rebuild​

console​

assertion​

keygen​

provision​

help​

init​

reap​

seed​

admin​

assign-scope​

client​

grant-role​

group​

join-group​

map-group-role​

map-role​

profile​

registration-token​

restore-scopes​

role​

scope​

tenant​

user​

send-logouts​

send-mail​

Usage

--version

client-origins

rebuild

console

assertion

keygen

provision

help

init

reap

seed

admin

assign-scope

client

grant-role

group

join-group

map-group-role

map-role

profile

registration-token

restore-scopes

role

scope

tenant

user

send-logouts

send-mail