Installing and Using the OSG Token Renewal Service¶
This document contains instructions to install and configure the
OSG Token Renewal Service package,
for obtaining and automatically renewing tokens with oidc-agent.
Before starting the installation process, consider the following points (consulting the Reference section below as needed):
- 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
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
- Obtain root access to the host
- Prepare the required Yum repositories
Installing the OSG Token Renewal Service¶
Install the OSG Token Renewal Service package:
[email protected] # 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¶
To create a new client account named
- Create a corresponding file named
/etc/osg/tokens/<ACCOUNT_SHORTNAME>.pwwith the encryption password to use for this client account.
- Consult the Requesting Tokens document to determine which scopes you will need for this client account.
Run the setup script as follows:
[email protected] # osg-token-renewer-setup <ACCOUNT_SHORTNAME>
[email protected] # osg-token-renewer-setup myaccount123
When prompted, enter your Issuer and desired scopes for this account from the list of valid options.
- 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).
- If this succeeds, you will be prompted with a new
[account <ACCOUNT_SHORTNAME>]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.
After you have created an OIDC client account and added it to
/osg/token-renewer/config.ini, you need to create a corresponding
section in the config for each token that should be generated for this account
(possibly with different options).
<TOKEN_NAME>and add a new
[token <TOKEN_NAME>]section (replacing the example section if it's still there).
accountoption in this section must match the
<ACCOUNT_SHORTNAME>for the corresponding
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:
list of audiences (see RFC7519)
list of scopes
min token lifetime in seconds
For tokens used against an HTCondor-CE, set the
<CE FQDN>:<CE PORT>.
[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¶
These services are managed by
systemctl and may start additional services as
As a reminder, here are common service commands (all run as
root) for EL7:
|To...||On EL7, run the command...|
|Start a service||
|Stop a service||
|Enable a service to start on boot||
|Disable a service from starting on boot||
Token renewal services¶
|OSG Token Renewer||
||The OSG Token Renewer, runs as a "oneshot" service, not a daemon.|
|OSG Token Renewer timer||
||Timer to run the OSG Token Renewer every 15 minutes|
The OSG token renewal service is set to run via a systemd timer every 15 minutes. After configuring your account(s) and token(s), enable the timer with:
[email protected] # systemctl enable osg-token-renewer.timer [email protected] # systemctl start osg-token-renewer.timer
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:
[email protected] # systemctl start osg-token-renewer.service
If this succeeds, the new token will be written to the location you configured
/etc/osg/tokens/<ACCOUNT_SHORTNAME>.token, by convention).
Failures can be diagnosed by running:
[email protected] # journalctl -eu osg-token-renewer
To get assistance please use this Help Procedure.
Files of interest¶
||Main config file for service|
||Encryption password file for client account|
||Output location for token files|
||Setup script for each new client account|
||SystemD service unit configuruation|
||SystemD timer for service|
||Main wrapper script invoked by service|
||Token renewal program invoked by main wrapper|