Skip to content

xtr_security_oauth2_server.command

The console commands: administer clients, sweep what expired, mint the key pair.

ClearExpiredTokensCommand

ClearExpiredTokensCommand(access_token_manager: AccessTokenManagerInterface, refresh_token_manager: RefreshTokenManagerInterface, authorization_code_manager: AuthorizationCodeManagerInterface, device_code_manager: DeviceCodeManagerInterface, enable_device_code_grant: bool)

Forgets every credential this server issued whose lifetime has run out.

Nothing is decided by this: an expired credential is already refused wherever it is presented, so sweeping is housekeeping — it keeps the store from growing without bound, and it is the reason this is the one command a deployment runs on a schedule rather than by hand.

Naming no store sweeps all of them, which is what a scheduled run wants. The device codes are left out of that sweep when the device flow is turned off, since there are none; naming --device-codes sweeps them anyway, which is how a deployment clears up after turning the flow off.

Sweep the four stores, knowing whether the device flow runs at all.

Parameters:

  • access_token_manager (AccessTokenManagerInterface) –

    Where the issued access tokens live.

  • refresh_token_manager (RefreshTokenManagerInterface) –

    Where the issued refresh tokens live.

  • authorization_code_manager (AuthorizationCodeManagerInterface) –

    Where the issued authorization codes live.

  • device_code_manager (DeviceCodeManagerInterface) –

    Where the issued device codes live.

  • enable_device_code_grant (bool) –

    Whether this deployment runs the flow for a device with no browser, which is what decides whether a sweep naming no store sweeps device codes too.

CreateClientCommand

CreateClientCommand(client_manager: ClientManagerInterface, password_hasher: Annotated[PasswordHasherInterface, Target(SERVICE_QUALIFIER)], client_class: type[AbstractClient])

Registers a client, and shows the one plaintext of its secret there will be.

What is stored is the hash of the secret, made with this package's own password hasher — so the secret itself exists only in the table this prints and in whatever the operator copies it into. Nothing can show it again: a client that lost its secret is given a new one, it is not reminded of the old one.

A client is confidential unless --public says otherwise, and a public one holds no secret at all, so naming both is refused rather than quietly dropping one of them.

An identifier already registered is refused rather than registered over: whatever the store would make of a second registration under one — replace the client, or refuse the write — the client known by that identifier would be left authenticating with a secret nobody was shown.

Register clients of client_class through client_manager.

Parameters:

  • client_manager (ClientManagerInterface) –

    Where the registration is written.

  • password_hasher (Annotated[PasswordHasherInterface, Target(SERVICE_QUALIFIER)]) –

    What the secret is hashed with before it is written; this package's own, never the one an application hashes its users' passwords with.

  • client_class (type[AbstractClient]) –

    The class a registration is, which the deployment chose under client.classname.

DeleteClientCommand

DeleteClientCommand(client_manager: ClientManagerInterface)

Forgets a client's registration, so nothing it holds can authenticate again.

The client is read first and reported when there is none, rather than answering as if a registration that never existed had been withdrawn: a mistyped identifier is the likeliest reason for either, and an operator withdrawing a client needs to know which it was.

Read and withdraw the registrations through client_manager.

GenerateKeyPairCommand

GenerateKeyPairCommand(private_key: str, public_key: str, passphrase: str, algorithm: str)

Mints a signing key pair and writes it where this deployment reads it.

The paths are not this command's to choose: it writes the file authorization_server.private_key names, and the file resource_server.public_key names when the deployment named one — a verifying key is otherwise derived from the private one, so there is nothing to write for it.

A key file in place is never replaced by accident: --overwrite is what allows it and confirms it, --skip-if-exists leaves it alone, and --dry-run writes nothing at all, so the pair can be read off the terminal and put into a secret store instead.

Mint for algorithm and write where private_key and public_key point.

Parameters:

  • private_key (str) –

    What authorization_server.private_key holds — the path of the file the signing key is read from, or the key text itself, in which case there is no file to write.

  • public_key (str) –

    What resource_server.public_key holds, or empty when the verifying key is derived from the signing one.

  • passphrase (str) –

    What the private key is encrypted with as it is written, or empty for none.

  • algorithm (str) –

    The algorithm this deployment signs with, which is what a run naming none mints for.

ListClientsCommand

ListClientsCommand(client_manager: ClientManagerInterface)

Shows the registered clients, with their secrets masked.

A secret is never shown, not even as the hash that is stored: a listing is read over somebody's shoulder and copied into tickets, and the hash is of no use to an operator while being of considerable use to anybody guessing offline. A client that lost its secret is registered again.

--columns narrows what is shown and --scope, --grant-type and --redirect-uri narrow which clients are: a client has to hold everything named, so naming two scopes lists the clients holding both.

Read the registrations through client_manager.

UpdateClientCommand

UpdateClientCommand(client_manager: ClientManagerInterface)

Adds to and removes from a client's registration, and turns it on or off.

Every list is amended rather than replaced — a redirect URI is added or taken away, never the whole set rewritten — because a registration is administered one change at a time and a replacement would silently drop whatever the caller did not happen to name.

The secret is not among the fields: a stored secret is a hash, so there is nothing here that could change it to something an operator knows. A client that needs a new secret is registered again.

Taking the last scope away does not leave the client scope-less where a deployment configured default scopes: an amendment is saved through the client manager, which announces it, and the listener this package ships reads a scope-less client as one registered with no scopes and hands it those defaults. The run reports the client amended, because it was — just not left as the options read. A deployment wanting scope-less clients configures no default scopes.

Read and write the registrations through client_manager.