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 ¶
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 ¶
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_keyholds — 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_keyholds, 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 ¶
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 ¶
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.