From 92b6698bc2021189617e4450ce3a1f7635d9000e Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 20 Aug 2021 19:42:10 -0500 Subject: [PATCH 01/23] add initial osg token renewer doc (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 195 ++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 196 insertions(+) create mode 100644 docs/other/osg-token-renewer.md diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md new file mode 100644 index 000000000..1eefd5059 --- /dev/null +++ b/docs/other/osg-token-renewer.md @@ -0,0 +1,195 @@ +Installing and Using the OSG Token Renewal Service +================================================== + +This document contains instructions to install and configure the +OSG Token Renewal Service package, `osg-token-renewer`, +for obtaining and renewing tokens with the OIDC tools. +This service automates the procedure in the +[Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) +document. + + +Before Starting +--------------- + +Before starting the installation process, consider the following points +(consulting [the Reference section below](#reference) as needed): + +- **WLCG INDIGO IAM account:** You'll need an account with WLCG. + You can register for an account + [here](https://wlcg.cloud.cnaf.infn.it/start-registration). +- **User and Group IDs:** If they do not exist already, the installation will + create the Linux user and group named `osg-token-svc` + +As with all OSG software installations, there are some one-time (per host) +steps to prepare in advance: + +- Ensure the host has + [a supported operating system](../release/supported_platforms.md) +- Obtain root access to the host +- Prepare the [required Yum repositories](../common/yum.md) +- Install [CA certificates](../common/ca.md) + + +Installing the OSG token renewal service +---------------------------------------- + +Install the OSG Token Renewal Service package: + +```console +root@server # yum install osg-token-renewer +``` + +This will install the `osg-token-renewer` scripts & systemd service files, +and will pull in the `oidc-agent` package that the service depends on. + + +Configuring the OSG token renewal service +----------------------------------------- + +The main configuration file for the service is `/osg/token-renewer/config.ini`. + +For each OIDC Client, you will add an `account` section to the config file. +For each token you wish to generate for this client account, +you will configure a `token` section with any relevant options. + +Examples of this can be found in the `/osg/token-renewer/config.ini` that gets +installed with the package. + +Each `[account ]` section corresponds to a client account +named ``, set up with the `oidc-gen` tool, run by the +`osg-token-renewer-setup.sh` script. + +In this `account` section, the `password_file` option is a path to a file +you create as `root` with the encryption password to be used for this client +account. + +For each client account, you can configure one or more `[token ]` +sections, where `` is a unique name of your choosing. +These sections describe how to create the token with the `oidc-token` tool. +For details, see +[Creating a new OIDC Client Account](#creating-a-new-oidc-client-account) +below. + + +Details for this configuration can be found below under +[Configuring tokens for an OIDC client account](#configuring-tokens-for-an-oidc-client-account). + + +Creating a new OIDC client account +---------------------------------- + +The +[Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) +document describes the process of running `oidc-gen` as `root` to create a +new OIDC client account. +However, in order to keep relevant oidc-agent config files owned by the +`osg-token-svc` service account rather than `root`, we provide a +`osg-token-renewer-setup.sh` script. + +To create a new client account named ``: + +- Create a corresponding file named `/etc/osg/tokens/.pw` + with the encryption password to use for this client account. +- Consult the + [Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) + document to determine which scopes you will need for this client account. +- Run the setup script as follows: + ```console + root@server # osg-token-renewer-setup.sh + ``` + For example, + ```console + root@server # osg-token-renewer-setup.sh myaccount123 wlcg offline_access + ``` +- You will be prompted on the console to visit a WLCG web link to authorize + the client request with a passcode printed on the console. + Follow the prompts (visit the web link, enter the request passcode, + log in with your WLCG INDIGO IAM user account, and authorize the request). +- If this succeeds you will be prompted with a new + `[account ]` section to add to your `config.ini`. + Go ahead and add it, replacing the example section if it's still there. + +Next you can configure one or more tokens for this client account. + + +Configuring tokens for an OIDC client account +--------------------------------------------- + +After you have created an OIDC client account and added it to +`/osg/token-renewer/config.ini`, you need to create a corresponding `token` +section in the config for each token that should be generated for this account +(possibly with different options). + +Choose a `` and add a new `[token ]` section +(replacing the example section if it's still there). + +The `account` option in this section must match the `` +for the corresponding `[account ]` section. + +The `token_path` option specifies the output path where the generated token +will be saved. + +Optionally, you may also specify any of the following options, which will +be passed to the `oidc-token` command when generating the token: + +| Option | Description | +|:---------------|:----------------------------------------------------------| +| `audience` | list of audiences to pass via `--aud` option | +| `scope` | list of scopes to pass via `--scope` option | +| `min_lifetime` | min token lifetime in seconds to pass via `--time` option | + +!!! note + For tokens used against an HTCondor-CE, set the `audience` option to + `:`. + + +Running the token renewal service +--------------------------------- + +The OSG token renewal service is set up as a "oneshot" systemd service, +which runs under the `osg-token-svc` user, sets up an `oidc-agent`, +adds the relevant OIDC client accounts as specified in the `config.ini` +with `oidc-add`, and generates the tokens with `oidc-token`. + +This service is set to run via a systemd timer nightly at midnight. + +If you would like to run the service manually at a different time (to generate +all the tokens immediately), you can run the service once with: + +```console +root@host # systemctl start osg-token-renewer +``` + +If this succeeds, the new token will be written to the location you configured +for `token_path` (`/etc/osg/tokens/.token`, by convention). + +Failures can be diagnosed by running: + +```console +root@host # journalctl -eu osg-token-renewer +``` + +Help +---- + +To get assistance please use this [Help Procedure](../common/help.md). + + +Reference +---------- + +### Files of interest + +| Path | Description | +|:----------------------------------------------------|:----------------------------------------------| +| `/etc/osg/token-renewer/config.ini` | Main config file for service | +| `/etc/osg/tokens/.pw` | Encryption password file for client account | +| `/etc/osg/tokens/.token` | Output location for token files | +| `/usr/bin/osg-token-renewer-setup.sh` | Setup script for each new client account | +| `/usr/lib/systemd/system/osg-token-renewer.service` | SystemD service unit configuruation | +| `/usr/lib/systemd/system/osg-token-renewer.timer` | SystemD timer for service | +| `/usr/bin/osg-token-renewer.sh` | Main wrapper script invoked by service | +| `/usr/bin/osg-token-renewer` | Token renewal program invoked by main wrapper | + + diff --git a/mkdocs.yml b/mkdocs.yml index a39c9b536..8cb263271 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,6 +56,7 @@ nav: - 'Install a CVMFS Stratum 1': 'other/install-cvmfs-stratum1.md' - 'Troubleshooting Gratia': 'other/troubleshooting-gratia.md' - 'Install Transfer Log Filebeats': 'other/schedd-filebeats.md' + - 'Install OSG Token Renewal Service': 'other/install-osg-token-renewer.md' - Deprecated: - POSIX Storage: - 'Install GridFTP Server': 'data/gridftp.md' From 7588a58a75e697edfacd99906be68ae79eb8cd59 Mon Sep 17 00:00:00 2001 From: edquist Date: Mon, 23 Aug 2021 23:14:47 +0300 Subject: [PATCH 02/23] Apply suggestions from code review by @brianhlin Co-authored-by: Brian Lin --- docs/other/osg-token-renewer.md | 69 +++++++++++++++------------------ 1 file changed, 32 insertions(+), 37 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 1eefd5059..c21938cc8 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -3,7 +3,7 @@ Installing and Using the OSG Token Renewal Service This document contains instructions to install and configure the OSG Token Renewal Service package, `osg-token-renewer`, -for obtaining and renewing tokens with the OIDC tools. +for obtaining and automatically renewing tokens with the OIDC tools. This service automates the procedure in the [Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) document. @@ -28,10 +28,9 @@ steps to prepare in advance: [a supported operating system](../release/supported_platforms.md) - Obtain root access to the host - Prepare the [required Yum repositories](../common/yum.md) -- Install [CA certificates](../common/ca.md) -Installing the OSG token renewal service +Installing the OSG Token Renewal Service ---------------------------------------- Install the OSG Token Renewal Service package: @@ -79,13 +78,6 @@ Details for this configuration can be found below under Creating a new OIDC client account ---------------------------------- -The -[Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) -document describes the process of running `oidc-gen` as `root` to create a -new OIDC client account. -However, in order to keep relevant oidc-agent config files owned by the -`osg-token-svc` service account rather than `root`, we provide a -`osg-token-renewer-setup.sh` script. To create a new client account named ``: @@ -95,20 +87,22 @@ To create a new client account named ``: [Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) document to determine which scopes you will need for this client account. - Run the setup script as follows: - ```console - root@server # osg-token-renewer-setup.sh - ``` - For example, - ```console - root@server # osg-token-renewer-setup.sh myaccount123 wlcg offline_access - ``` + + :::console + root@server # osg-token-renewer-setup.sh + + For example, + + :::console + root@server # osg-token-renewer-setup.sh myaccount123 wlcg offline_access + - You will be prompted on the console to visit a WLCG web link to authorize the client request with a passcode printed on the console. Follow the prompts (visit the web link, enter the request passcode, log in with your WLCG INDIGO IAM user account, and authorize the request). - If this succeeds you will be prompted with a new `[account ]` section to add to your `config.ini`. - Go ahead and add it, replacing the example section if it's still there. + Add the section to your `/etc/token-renewer/config.ini`, replacing the example section if it's still there. Next you can configure one or more tokens for this client account. @@ -121,31 +115,32 @@ After you have created an OIDC client account and added it to section in the config for each token that should be generated for this account (possibly with different options). -Choose a `` and add a new `[token ]` section -(replacing the example section if it's still there). +1. Choose a `` and add a new `[token ]` section + (replacing the example section if it's still there). -The `account` option in this section must match the `` -for the corresponding `[account ]` section. + The `account` option in this section must match the `` + for the corresponding `[account ]` section. -The `token_path` option specifies the output path where the generated token -will be saved. +1. Set the `token_path` to `/etc/osg/tokens/.token -Optionally, you may also specify any of the following options, which will -be passed to the `oidc-token` command when generating the token: +1. Optionally, you may also specify any of the following options, which will + be passed to the `oidc-token` command when generating the token: -| Option | Description | -|:---------------|:----------------------------------------------------------| -| `audience` | list of audiences to pass via `--aud` option | -| `scope` | list of scopes to pass via `--scope` option | -| `min_lifetime` | min token lifetime in seconds to pass via `--time` option | + | Option | Description | + |:---------------|:----------------------------------------------------------| + | `audience` | list of audiences to pass via `--aud` option | + | `scope` | list of scopes to pass via `--scope` option | + | `min_lifetime` | min token lifetime in seconds to pass via `--time` option | -!!! note - For tokens used against an HTCondor-CE, set the `audience` option to - `:`. + !!! note + For tokens used against an HTCondor-CE, set the `audience` option to + `:`. +### Example configuration + -Running the token renewal service ---------------------------------- +Managing the OSG Token Renewal Service +-------------------------------------- The OSG token renewal service is set up as a "oneshot" systemd service, which runs under the `osg-token-svc` user, sets up an `oidc-agent`, @@ -154,7 +149,7 @@ with `oidc-add`, and generates the tokens with `oidc-token`. This service is set to run via a systemd timer nightly at midnight. -If you would like to run the service manually at a different time (to generate +If you would like to run the service manually at a different time (e.g., to generate all the tokens immediately), you can run the service once with: ```console From 11edb379b903ab06327e8f6d655d72d09f1f4eb0 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Sat, 21 Aug 2021 04:19:01 -0500 Subject: [PATCH 03/23] slide this up (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index c21938cc8..108ef8c6f 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -63,6 +63,9 @@ In this `account` section, the `password_file` option is a path to a file you create as `root` with the encryption password to be used for this client account. +Details for this configuration can be found below under +[Configuring tokens for an OIDC client account](#configuring-tokens-for-an-oidc-client-account). + For each client account, you can configure one or more `[token ]` sections, where `` is a unique name of your choosing. These sections describe how to create the token with the `oidc-token` tool. @@ -71,10 +74,6 @@ For details, see below. -Details for this configuration can be found below under -[Configuring tokens for an OIDC client account](#configuring-tokens-for-an-oidc-client-account). - - Creating a new OIDC client account ---------------------------------- From 895917e4779259cf46870c9cc5774a6721eabb0d Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 10:10:54 -0500 Subject: [PATCH 04/23] update setup script usage to include ISSUER parameter (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 108ef8c6f..e4d323f2e 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -88,17 +88,20 @@ To create a new client account named ``: - Run the setup script as follows: :::console - root@server # osg-token-renewer-setup.sh + root@server # osg-token-renewer-setup.sh For example, :::console - root@server # osg-token-renewer-setup.sh myaccount123 wlcg offline_access + root@server # account=myaccount123 + root@server # issuer=https://wlcg.cloud.cnaf.infn.it/ + root@server # scopes="wlcg offline_access" + root@server # osg-token-renewer-setup.sh $account $issuer $scopes -- You will be prompted on the console to visit a WLCG web link to authorize +- You will be prompted on the console to visit a web link to authorize the client request with a passcode printed on the console. Follow the prompts (visit the web link, enter the request passcode, - log in with your WLCG INDIGO IAM user account, and authorize the request). + log in with your account for your issuer, and authorize the request). - If this succeeds you will be prompted with a new `[account ]` section to add to your `config.ini`. Add the section to your `/etc/token-renewer/config.ini`, replacing the example section if it's still there. From d6ab9cb3b22e451f72f7dbf672c8b4cb364a5355 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 10:11:39 -0500 Subject: [PATCH 05/23] make OIDC token issuer account requirement non-WLCG-specific SOFTWARE-4763 --- docs/other/osg-token-renewer.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index e4d323f2e..9fe51220b 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -15,9 +15,7 @@ Before Starting Before starting the installation process, consider the following points (consulting [the Reference section below](#reference) as needed): -- **WLCG INDIGO IAM account:** You'll need an account with WLCG. - You can register for an account - [here](https://wlcg.cloud.cnaf.infn.it/start-registration). +- An account is needed with an OIDC token issuer that offers the device flow - **User and Group IDs:** If they do not exist already, the installation will create the Linux user and group named `osg-token-svc` From b58770b57c412950078c1fe7675cb161e43c6b7b Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 10:17:09 -0500 Subject: [PATCH 06/23] convert steps to ordered list (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 9fe51220b..0d610e02a 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -78,12 +78,12 @@ Creating a new OIDC client account To create a new client account named ``: -- Create a corresponding file named `/etc/osg/tokens/.pw` - with the encryption password to use for this client account. -- Consult the - [Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) - document to determine which scopes you will need for this client account. -- Run the setup script as follows: +1. Create a corresponding file named `/etc/osg/tokens/.pw` + with the encryption password to use for this client account. +1. Consult the + [Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) + document to determine which scopes you will need for this client account. +1. Run the setup script as follows: :::console root@server # osg-token-renewer-setup.sh @@ -96,13 +96,13 @@ To create a new client account named ``: root@server # scopes="wlcg offline_access" root@server # osg-token-renewer-setup.sh $account $issuer $scopes -- You will be prompted on the console to visit a web link to authorize - the client request with a passcode printed on the console. - Follow the prompts (visit the web link, enter the request passcode, - log in with your account for your issuer, and authorize the request). -- If this succeeds you will be prompted with a new - `[account ]` section to add to your `config.ini`. - Add the section to your `/etc/token-renewer/config.ini`, replacing the example section if it's still there. +1. You will be prompted on the console to visit a web link to authorize + the client request with a passcode printed on the console. + Follow the prompts (visit the web link, enter the request passcode, + log in with your account for your issuer, and authorize the request). +1. If this succeeds you will be prompted with a new + `[account ]` section to add to your `config.ini`. + Add the section to your `/etc/token-renewer/config.ini`, replacing the example section if it's still there. Next you can configure one or more tokens for this client account. From f1c0d264816fb65c63082680be8d6ab95b4042b0 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 10:33:12 -0500 Subject: [PATCH 07/23] whitespace cleanup --- docs/other/osg-token-renewer.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 0d610e02a..3a06c07c3 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -80,7 +80,7 @@ To create a new client account named ``: 1. Create a corresponding file named `/etc/osg/tokens/.pw` with the encryption password to use for this client account. -1. Consult the +1. Consult the [Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) document to determine which scopes you will need for this client account. 1. Run the setup script as follows: @@ -121,7 +121,7 @@ section in the config for each token that should be generated for this account The `account` option in this section must match the `` for the corresponding `[account ]` section. -1. Set the `token_path` to `/etc/osg/tokens/.token +1. Set the `token_path` to `/etc/osg/tokens/.token 1. Optionally, you may also specify any of the following options, which will be passed to the `oidc-token` command when generating the token: @@ -171,8 +171,8 @@ Help To get assistance please use this [Help Procedure](../common/help.md). -Reference ----------- +Reference +--------- ### Files of interest From 81d240041fc4d2a08fbcd87934899872df11e5b1 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 11:22:31 -0500 Subject: [PATCH 08/23] reorganize section names a bit (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 3a06c07c3..59b53ab5c 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -62,7 +62,7 @@ you create as `root` with the encryption password to be used for this client account. Details for this configuration can be found below under -[Configuring tokens for an OIDC client account](#configuring-tokens-for-an-oidc-client-account). +[Configuring tokens](#configuring-tokens). For each client account, you can configure one or more `[token ]` sections, where `` is a unique name of your choosing. @@ -72,9 +72,11 @@ For details, see below. -Creating a new OIDC client account ----------------------------------- +Configuring the OSG Token Renewal Service +----------------------------------------- + +### Configuring accounts To create a new client account named ``: @@ -107,8 +109,7 @@ To create a new client account named ``: Next you can configure one or more tokens for this client account. -Configuring tokens for an OIDC client account ---------------------------------------------- +### Configuring tokens After you have created an OIDC client account and added it to `/osg/token-renewer/config.ini`, you need to create a corresponding `token` From 4c119a4fd2cd642ad2fd290425fea929ca3fa8a1 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 11:33:17 -0500 Subject: [PATCH 09/23] move details out that belong in readmen (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 59b53ab5c..f2e860136 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -143,12 +143,7 @@ section in the config for each token that should be generated for this account Managing the OSG Token Renewal Service -------------------------------------- -The OSG token renewal service is set up as a "oneshot" systemd service, -which runs under the `osg-token-svc` user, sets up an `oidc-agent`, -adds the relevant OIDC client accounts as specified in the `config.ini` -with `oidc-add`, and generates the tokens with `oidc-token`. - -This service is set to run via a systemd timer nightly at midnight. +The OSG token renewal service is set to run via a systemd timer nightly at midnight. If you would like to run the service manually at a different time (e.g., to generate all the tokens immediately), you can run the service once with: From 25cf6b63748adc672b86264e8cebf209b46957cc Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 11:44:04 -0500 Subject: [PATCH 10/23] drop duplicate section heading (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index f2e860136..63a03cba8 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -41,7 +41,7 @@ This will install the `osg-token-renewer` scripts & systemd service files, and will pull in the `oidc-agent` package that the service depends on. -Configuring the OSG token renewal service +Configuring the OSG Token Renewal Service ----------------------------------------- The main configuration file for the service is `/osg/token-renewer/config.ini`. @@ -72,10 +72,6 @@ For details, see below. -Configuring the OSG Token Renewal Service ------------------------------------------ - - ### Configuring accounts To create a new client account named ``: From f000aca891b458ca6882f0e039d017ed1c7bb59f Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 11:46:44 -0500 Subject: [PATCH 11/23] drop configuration prose, to be moved to README (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 63a03cba8..b1a3634a6 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -44,33 +44,6 @@ and will pull in the `oidc-agent` package that the service depends on. Configuring the OSG Token Renewal Service ----------------------------------------- -The main configuration file for the service is `/osg/token-renewer/config.ini`. - -For each OIDC Client, you will add an `account` section to the config file. -For each token you wish to generate for this client account, -you will configure a `token` section with any relevant options. - -Examples of this can be found in the `/osg/token-renewer/config.ini` that gets -installed with the package. - -Each `[account ]` section corresponds to a client account -named ``, set up with the `oidc-gen` tool, run by the -`osg-token-renewer-setup.sh` script. - -In this `account` section, the `password_file` option is a path to a file -you create as `root` with the encryption password to be used for this client -account. - -Details for this configuration can be found below under -[Configuring tokens](#configuring-tokens). - -For each client account, you can configure one or more `[token ]` -sections, where `` is a unique name of your choosing. -These sections describe how to create the token with the `oidc-token` tool. -For details, see -[Creating a new OIDC Client Account](#creating-a-new-oidc-client-account) -below. - ### Configuring accounts From 9157999849d9f47a4abc31bd7bb4c0b146cf6ed9 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Fri, 27 Aug 2021 11:59:09 -0500 Subject: [PATCH 12/23] add service tables (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index b1a3634a6..49ec2e0b1 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -112,6 +112,24 @@ section in the config for each token that should be generated for this account Managing the OSG Token Renewal Service -------------------------------------- +These services are managed by `systemctl` and may start additional services as dependencies. +As a reminder, here are common service commands (all run as `root`) for EL7: + +| To... | On EL7, run the command... | +| :-------------------------------------- | :--------------------------------- | +| Start a service | `systemctl start ` | +| Stop a service | `systemctl stop ` | +| Enable a service to start on boot | `systemctl enable ` | +| Disable a service from starting on boot | `systemctl disable ` | + +### Public cache services + +| **Software** | **Service name** | **Notes** | +|--------------|------------------|-----------| +| OSG Token Renewer | `osg-token-renewer.service` | The OSG Token Renewer, runs as a "oneshot" service, not a daemon. | +| OSG Token Renewer timer | `osg-token-renewer.timer` | Nightly run schedule for OSG Token Renewer | + + The OSG token renewal service is set to run via a systemd timer nightly at midnight. If you would like to run the service manually at a different time (e.g., to generate From 3e4868a40321808484388ea983ebffb68e84b619 Mon Sep 17 00:00:00 2001 From: edquist Date: Tue, 14 Sep 2021 00:18:29 +0300 Subject: [PATCH 13/23] Apply suggestions from code review Thanks Brian Co-authored-by: Brian Lin --- docs/other/osg-token-renewer.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 49ec2e0b1..eee852fd9 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -3,10 +3,7 @@ Installing and Using the OSG Token Renewal Service This document contains instructions to install and configure the OSG Token Renewal Service package, `osg-token-renewer`, -for obtaining and automatically renewing tokens with the OIDC tools. -This service automates the procedure in the -[Requesting Tokens](https://opensciencegrid.org/technology/software/requesting-tokens/) -document. +for obtaining and automatically renewing tokens with [oidc-agent](https://github.com/indigo-dc/oidc-agent). Before Starting @@ -105,6 +102,7 @@ section in the config for each token that should be generated for this account !!! note For tokens used against an HTCondor-CE, set the `audience` option to `:`. + ### Example configuration From 359ecbd1b3d192125ba8e68ceed4cf61e5cb4b48 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Mon, 20 Sep 2021 19:00:11 -0500 Subject: [PATCH 14/23] include TOKEN_NAME in token path (SOFTWARE-4763) since there can be multiple tokens for a single account --- docs/other/osg-token-renewer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 49ec2e0b1..876e242dc 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -91,7 +91,7 @@ section in the config for each token that should be generated for this account The `account` option in this section must match the `` for the corresponding `[account ]` section. -1. Set the `token_path` to `/etc/osg/tokens/.token +1. Set the `token_path` to `/etc/osg/tokens/..token` 1. Optionally, you may also specify any of the following options, which will be passed to the `oidc-token` command when generating the token: @@ -163,7 +163,7 @@ Reference |:----------------------------------------------------|:----------------------------------------------| | `/etc/osg/token-renewer/config.ini` | Main config file for service | | `/etc/osg/tokens/.pw` | Encryption password file for client account | -| `/etc/osg/tokens/.token` | Output location for token files | +| `/etc/osg/tokens/..token` | Output location for token files | | `/usr/bin/osg-token-renewer-setup.sh` | Setup script for each new client account | | `/usr/lib/systemd/system/osg-token-renewer.service` | SystemD service unit configuruation | | `/usr/lib/systemd/system/osg-token-renewer.timer` | SystemD timer for service | From 8ea591ff3c579f5f9f1415fac2be93e1f0f8c95c Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Mon, 20 Sep 2021 19:00:30 -0500 Subject: [PATCH 15/23] tidy whitespace (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 876e242dc..7145be77d 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -159,15 +159,15 @@ Reference ### Files of interest -| Path | Description | -|:----------------------------------------------------|:----------------------------------------------| -| `/etc/osg/token-renewer/config.ini` | Main config file for service | -| `/etc/osg/tokens/.pw` | Encryption password file for client account | -| `/etc/osg/tokens/..token` | Output location for token files | -| `/usr/bin/osg-token-renewer-setup.sh` | Setup script for each new client account | -| `/usr/lib/systemd/system/osg-token-renewer.service` | SystemD service unit configuruation | -| `/usr/lib/systemd/system/osg-token-renewer.timer` | SystemD timer for service | -| `/usr/bin/osg-token-renewer.sh` | Main wrapper script invoked by service | -| `/usr/bin/osg-token-renewer` | Token renewal program invoked by main wrapper | +| Path | Description | +|:---------------------------------------------------------|:----------------------------------------------| +| `/etc/osg/token-renewer/config.ini` | Main config file for service | +| `/etc/osg/tokens/.pw` | Encryption password file for client account | +| `/etc/osg/tokens/..token` | Output location for token files | +| `/usr/bin/osg-token-renewer-setup.sh` | Setup script for each new client account | +| `/usr/lib/systemd/system/osg-token-renewer.service` | SystemD service unit configuruation | +| `/usr/lib/systemd/system/osg-token-renewer.timer` | SystemD timer for service | +| `/usr/bin/osg-token-renewer.sh` | Main wrapper script invoked by service | +| `/usr/bin/osg-token-renewer` | Token renewal program invoked by main wrapper | From 1c80c14866e1b29b201c50fa9991874737c2410c Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Mon, 20 Sep 2021 19:12:22 -0500 Subject: [PATCH 16/23] reflect updated osg-token-renewer-setup.sh usage (SOFTWARE-4763) now it runs oidc-gen interactively, which is where the user will be prompted to enter Issuer and scopes. Note this is probably better anyway, as the script presents the list of valid options for each. --- docs/other/osg-token-renewer.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 7145be77d..a38fa3447 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -57,17 +57,16 @@ To create a new client account named ``: 1. Run the setup script as follows: :::console - root@server # osg-token-renewer-setup.sh + root@server # osg-token-renewer-setup.sh For example, :::console - root@server # account=myaccount123 - root@server # issuer=https://wlcg.cloud.cnaf.infn.it/ - root@server # scopes="wlcg offline_access" - root@server # osg-token-renewer-setup.sh $account $issuer $scopes + root@server # osg-token-renewer-setup.sh myaccount123 -1. You will be prompted on the console to visit a web link to authorize +1. When prompted, enter your Issuer and desired scopes for this account + from the list of valid options. +1. You will also be prompted on the console to visit a web link to authorize the client request with a passcode printed on the console. Follow the prompts (visit the web link, enter the request passcode, log in with your account for your issuer, and authorize the request). From 594da1fe4928b919d6427e5b795517a8da2a90ef Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Mon, 20 Sep 2021 19:15:44 -0500 Subject: [PATCH 17/23] mention updated timer frequency (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index a38fa3447..34cd41f56 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -129,7 +129,8 @@ As a reminder, here are common service commands (all run as `root`) for EL7: | OSG Token Renewer timer | `osg-token-renewer.timer` | Nightly run schedule for OSG Token Renewer | -The OSG token renewal service is set to run via a systemd timer nightly at midnight. +The OSG token renewal service is set to run via a systemd timer every 15 +minutes. If you would like to run the service manually at a different time (e.g., to generate all the tokens immediately), you can run the service once with: From 6279ace4a1be50479a27a6ea6fd08a03106b0ef1 Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Mon, 20 Sep 2021 19:16:20 -0500 Subject: [PATCH 18/23] misc ocd tidying (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 34cd41f56..392707582 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -70,9 +70,10 @@ To create a new client account named ``: the client request with a passcode printed on the console. Follow the prompts (visit the web link, enter the request passcode, log in with your account for your issuer, and authorize the request). -1. If this succeeds you will be prompted with a new +1. If this succeeds, you will be prompted with a new `[account ]` section to add to your `config.ini`. - Add the section to your `/etc/token-renewer/config.ini`, replacing the example section if it's still there. + Add the section to your `/etc/token-renewer/config.ini`, + replacing the example section if it's still there. Next you can configure one or more tokens for this client account. @@ -90,7 +91,8 @@ section in the config for each token that should be generated for this account The `account` option in this section must match the `` for the corresponding `[account ]` section. -1. Set the `token_path` to `/etc/osg/tokens/..token` +1. Set the `token_path` to + `/etc/osg/tokens/..token` 1. Optionally, you may also specify any of the following options, which will be passed to the `oidc-token` command when generating the token: @@ -111,7 +113,8 @@ section in the config for each token that should be generated for this account Managing the OSG Token Renewal Service -------------------------------------- -These services are managed by `systemctl` and may start additional services as dependencies. +These services are managed by `systemctl` and may start additional services as +dependencies. As a reminder, here are common service commands (all run as `root`) for EL7: | To... | On EL7, run the command... | @@ -132,8 +135,8 @@ As a reminder, here are common service commands (all run as `root`) for EL7: The OSG token renewal service is set to run via a systemd timer every 15 minutes. -If you would like to run the service manually at a different time (e.g., to generate -all the tokens immediately), you can run the service once with: +If you would like to run the service manually at a different time (e.g., to +generate all the tokens immediately), you can run the service once with: ```console root@host # systemctl start osg-token-renewer From 3bd76b8bb8db4b905a89c3d10808a81254f3843b Mon Sep 17 00:00:00 2001 From: edquist Date: Mon, 27 Sep 2021 23:40:45 +0300 Subject: [PATCH 19/23] Apply suggestions from code review Co-authored-by: Brian Lin --- docs/other/osg-token-renewer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index fd31ede6f..219d4f6ff 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -122,7 +122,7 @@ As a reminder, here are common service commands (all run as `root`) for EL7: | Enable a service to start on boot | `systemctl enable ` | | Disable a service from starting on boot | `systemctl disable ` | -### Public cache services +### Token renewal services | **Software** | **Service name** | **Notes** | |--------------|------------------|-----------| From 1560838a040fbb0b2c6f5b8dfba7dd416c7380e0 Mon Sep 17 00:00:00 2001 From: edquist Date: Tue, 28 Sep 2021 16:34:13 +0300 Subject: [PATCH 20/23] doc tweaks from Brian Co-authored-by: Brian Lin --- docs/other/osg-token-renewer.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 219d4f6ff..424a1bd2e 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -91,14 +91,14 @@ section in the config for each token that should be generated for this account 1. Set the `token_path` to `/etc/osg/tokens/..token` -1. Optionally, you may also specify any of the following options, which will - be passed to the `oidc-token` command when generating the token: +1. Optionally, you may also specify any of the following options, which can attenuate + the respective values in the generated token compared to the associated with the account: | Option | Description | |:---------------|:----------------------------------------------------------| - | `audience` | list of audiences to pass via `--aud` option | - | `scope` | list of scopes to pass via `--scope` option | - | `min_lifetime` | min token lifetime in seconds to pass via `--time` option | + | `audience` | list of audiences (see [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3)) | + | `scope` | list of [scopes](https://github.com/WLCG-AuthZ-WG/common-jwt-profile/blob/master/profile.md#capability-based-authorization-scope) | + | `min_lifetime` | min token lifetime in seconds | !!! note For tokens used against an HTCondor-CE, set the `audience` option to From 32d448ab2b9b3df5696519f22bd3af87adb2175e Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Tue, 28 Sep 2021 08:36:20 -0500 Subject: [PATCH 21/23] reword a bit per PR discussion (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index 424a1bd2e..a983d207a 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -91,8 +91,9 @@ section in the config for each token that should be generated for this account 1. Set the `token_path` to `/etc/osg/tokens/..token` -1. Optionally, you may also specify any of the following options, which can attenuate - the respective values in the generated token compared to the associated with the account: +1. Optionally, you may also specify any of the following options, which can + limit the respective values in the generated token compared to the + associated account: | Option | Description | |:---------------|:----------------------------------------------------------| From 1486211161fdac2c4a6190bcc20a335d67983ebb Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Tue, 28 Sep 2021 08:39:59 -0500 Subject: [PATCH 22/23] provide example config (SOFTWARE-4763) --- docs/other/osg-token-renewer.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/other/osg-token-renewer.md b/docs/other/osg-token-renewer.md index a983d207a..395b4f89e 100644 --- a/docs/other/osg-token-renewer.md +++ b/docs/other/osg-token-renewer.md @@ -107,7 +107,18 @@ section in the config for each token that should be generated for this account ### Example configuration - +```file +[account myclient1234] + +password_file = /etc/osg/tokens/myclient1234.pw + + + +[token mytoken567] + +account = myclient1234 +token_path = /etc/osg/tokens/myclient1234.mytoken567.token +``` Managing the OSG Token Renewal Service -------------------------------------- From a804c2f27d2ffc9c4193bbada4bc4b40b3c5c34c Mon Sep 17 00:00:00 2001 From: Carl Edquist Date: Tue, 28 Sep 2021 08:42:52 -0500 Subject: [PATCH 23/23] fix path to other/osg-token-renewer.md in index (SOFTWARE-4763) --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 8cb263271..39a51b832 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,7 +56,7 @@ nav: - 'Install a CVMFS Stratum 1': 'other/install-cvmfs-stratum1.md' - 'Troubleshooting Gratia': 'other/troubleshooting-gratia.md' - 'Install Transfer Log Filebeats': 'other/schedd-filebeats.md' - - 'Install OSG Token Renewal Service': 'other/install-osg-token-renewer.md' + - 'Install OSG Token Renewal Service': 'other/osg-token-renewer.md' - Deprecated: - POSIX Storage: - 'Install GridFTP Server': 'data/gridftp.md'