update docu

indigo-dc · Aug 27, 2024 · f1797d5 · f1797d5
1 parent 9454491
commit f1797d5
Show file tree

Hide file tree

Showing 4 changed files with 84 additions and 26 deletions.
diff --git a/gitbook/oidc-add/options.md b/gitbook/oidc-add/options.md
@@ -121,7 +121,7 @@ different `--pw-*` options.
 
 ### `--remove`
 
-The `--remove` option is used to unload an account configuration. After unloading an account, it is not longer available
+The `--remove` option is used to unload an account configuration. After unloading an account, it is no longer available
 for other applications. Therefore, it has to be loaded again before an access token can be obtained
 (either using oidc-add or through the autoload feature).
 
@@ -133,8 +133,8 @@ used for loading and unloading configurations. For more information refer to
 
 ### `--remove-all`
 
-With the `--remove-all` option all loaded account configuration can be removed from the agent with just one call. This
-might be preferred over restarting the agent, because that way the agent will still be available everywhere.
+With the `--remove-all` option all loaded account configuration can be unloaded from the agent with just one call.
+This might be preferred over restarting the agent, because that way the agent will still be available everywhere.
 
 ### `--lifetime`
 

diff --git a/gitbook/oidc-agent/options.md b/gitbook/oidc-agent/options.md
@@ -1,32 +1,35 @@
 ## Short Information About All Options
 
 <!-- @formatter:off -->
-| Option | Effect |
-| -- | -- |
-| [`--socket-path`](#socket-path) |Use this path for the UNIX-domain socket.|
-| [`--always-allow-idtoken`](#always-allow-idtoken) |Always allow id-token requests without manual approval by the user|
-| [`--confirm`](#confirm) |Requires user confirmation when an application requests an access token for any loaded|
-| [`--console`](#console) |Runs `oidc-agent` on the console, without daemonizing|
-| [`--debug`](#debug) | Sets the log level to DEBUG|
-| [`--json`](#json) |Print agent socket and pid as JSON instead of bash|
-| [`--kill`](#kill) |Kill the current agent (given by the OIDCD_PID environment variable)|
-| [`--no-autoload`](#no-autoload) |Disables the autoload feature: A token request cannot load the needed configuration|
-| [`--no-autoreauthenticate`](#no-autoreauthenticate) |Disables the automatic re-authentication feature|
-| [`--no-scheme`](#no-scheme) | `oidc-agent` will not use a custom uri scheme redirect [Only applies if authorization code flow is used]|
-| [`--no-webserver`](#no-webserver) | `oidc-agent` will not start a webserver [Only applies if authorization code flow is used]|
-| [`--quiet`](#quiet) |Disable informational messages to stdout|
-| [`--lifetime`](#lifetime) |Sets a default value in seconds for the maximum lifetime of account configurations [..]|
-| [`--log-stderr`](#log-stderr) |Additionally prints log messages to stderr|
-| [`--status`](#status) |Connects to the currently running agent and prints status information|
-| [`--with-group`](#with-group) |Applications running under another user can access the agent [..]|
+| Option                                              | Effect                                                                                                   |
+|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------|
+| [`--socket-path`](#socket-path)                     | Use this path for the UNIX-domain socket.                                                                |
+| [`--always-allow-idtoken`](#always-allow-idtoken)   | Always allow id-token requests without manual approval by the user                                       |
+| [`--confirm`](#confirm)                             | Requires user confirmation when an application requests an access token for any loaded                   |
+| [`--console`](#console)                             | Runs `oidc-agent` on the console, without daemonizing                                                    |
+| [`--debug`](#debug)                                 | Sets the log level to DEBUG                                                                              |
+| [`--json`](#json)                                   | Print agent socket and pid as JSON instead of bash                                                       |
+| [`--kill`](#kill)                                   | Kill the current agent (given by the OIDCD_PID environment variable)                                     |
+| [`--no-autoload`](#no-autoload)                     | Disables the autoload feature: A token request cannot load the needed configuration                      |
+| [`--no-autoreauthenticate`](#no-autoreauthenticate) | Disables the automatic re-authentication feature                                                         |
+| [`--no-scheme`](#no-scheme)                         | `oidc-agent` will not use a custom uri scheme redirect [Only applies if authorization code flow is used] |
+| [`--no-webserver`](#no-webserver)                   | `oidc-agent` will not start a webserver [Only applies if authorization code flow is used]                |
+| [`--pid-file`](#pid-file)                           | If set the agent's pid is written to this file                                                           |
+| [`--quiet`](#quiet)                                 | Disable informational messages to stdout                                                                 |
+| [`--restart-on-update`](#restart-on-update)         | Enables automatic restart of the agent if its binary changes                                             |
+| [`--lifetime`](#lifetime)                           | Sets a default value in seconds for the maximum lifetime of account configurations [..]                  |
+| [`--log-stderr`](#log-stderr)                       | Additionally prints log messages to stderr                                                               |
+| [`--status`](#status)                               | Connects to the currently running agent and prints status information                                    |
+| [`--with-group`](#with-group)                       | Applications running under another user can access the agent [..]                                        |
 <!-- @formatter:on -->
 
 ## Detailed explanation About All Options
 
 ### `--socket-path`
 
 By default `oidc-agent` creates the UNIX-domain socket at `$TMPDIR/oidc-XXXXXX/oidc-agent.<ppid>`, where `<ppid>` is the
-parent's process id and `XXXXXX` is a randomly generated. The `-a` or `--socket-path` or `--bin_address` option can be
+parent's process id and `XXXXXX` is a randomly generated. The `-a` or
+`--socket-path` or `--bind-address` option can be
 used to change the location where this UNIX-domain socket is created. Please note the following:
 
 - If the passed argument has no trailing slash, the last part is the socket's filename.
@@ -127,10 +130,32 @@ be completed. Either by using a redirect uri that follows the custom redirect ur
 scheme `edu.kit.data.oidc-agent:/<path>` - this will directly redirect to oidc-gen, or by copying the url the browser
 would normally redirect to and pass it to `oidc-gen --codeExchange`.
 
+### `--pid-file`
+
+On default the agent outputs commands that - when executed - set certain
+environment variables. The `$OIDCD_PID` variable then contains the agent's
+process id, which is used by `oidc-agent -k` to stop that agent.
+For `oidc-agent-service` and maybe other tools the mechanism of an
+environment variable might not be sufficient and a pid file might be preferred.
+
+Through the `--pid-file` option a file can be passed. If given the agent's
+pid is written to this file and other applications might use it.
+
 ### `--quiet`
 
 Silences informational messages. Currently only has effect on the generated bash echo when setting agent environments.
 
+### `--restart-on-update`
+
+If enabled, the agent automatically restart after a (package) update.
+The agent will observe it's binary using `inotify`. When the file is changed
+(via a move), the agent restarts.
+
+This option is included by default when the agent is started via `oidc-agent-service`.
+
+It does not work with a non-daemonized agent and is generally only useful when the agent is started
+with `oidc-agent-service` or the socket path is persisted in another way.
+
 ### `--lifetime`
 
 The `--lifetime` option can be used to set a default lifetime for all loaded account configurations. This way all

diff --git a/gitbook/oidc-token/general.md b/gitbook/oidc-token/general.md
@@ -1,15 +1,19 @@
 ## General Usage
+
 To obtain an access token for a specific account configuration you have to pass
 the shortname to oidc-token:
 `oidc-token <shortname>`
 This will print the access token to `stdout`.
-This enables serveral use cases:
-- print the token to `stdout` and copy paste it where you need it.
+This enables several use cases:
+
+- print the token to `stdout` and copy-paste it where you need it.
 - put the token in an environment variable: ``export OIDC_AT=`oidc-token shortname` ``.
-- pipe the token to a programm that reads a token from `stdin`: `oidc-token shortname | iReadATokenFromStdIn`.
-- use the `oidc-token` directly in the needed command: ``curl -H 'Authorization: Bearer `oidc-token shortname`' example.com``.
 - use the `-c` (or similar) option to put the token into an environment
   variable: ``eval `oidc-token -c <shortname>` ``
+- pipe the token to a programm that reads a token from `stdin`: `oidc-token shortname | iReadATokenFromStdIn`.
+- use the `oidc-token` directly in the needed
+  command: ``curl -H 'Authorization: Bearer `oidc-token shortname`' example.com``.
+    - use the `--auth-header` option to simplify api calls: ``curl -H "$(oidc-token shortname)" example.com``
 
 Instead of using `oidc-token <shortname>` you also can do
 `oidc-token <issuer_url>`. While usually using the shortname is shorter there are also use

diff --git a/gitbook/oidc-token/options.md b/gitbook/oidc-token/options.md
@@ -7,6 +7,8 @@
     * [`--expires-at`](#expires-at)
     * [`--issuer`](#issuer)
     * [`--token`](#token)
+* [`--auth-header`](#auth-header)
+* [`--bearer`](#bearer)
 * [`--force-new`](#force-new)
 * [`--aud`](#aud)
 * [`--id-token`](#id-token)
@@ -122,6 +124,33 @@ eval `oidc-token <shortname> -oi`      # puts the access token and issuer url in
 eval `oidc-token <shortname> -o TOKEN` # puts the issuer url into TOKEN
 ```
 
+### `--auth-header`
+
+The `--auth-header` or `--auth` option can be used to print the token
+included in an authorization header for usage with api calls.
+This will output the following: `Authorization: Bearer <token>` without a
+newline at the end.
+
+Example call with integration into a `curl` command:
+
+```bash
+curl https://example.com/api -H "$(oidc-token --bearer <shortname>)"
+```
+
+### `--bearer`
+
+The `--bearer` option can be used to print the token in the bearer "format",
+to be used with authorization headers.
+This will output the following: `Bearer <token>` without a newline at the end.
+
+Example call with integration into a `curl` command:
+
+```bash
+curl https://example.com/api -H "Authorization: $(oidc-token --bearer <shortname>)"
+```
+
+There is also the [`--auth-header`](#auth-header) option that might be useful.
+
 ### `--force-new`
 
 The `--force-new` option can be used to force oidc-agent to return a new access token. This will return an access token