Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 5.7.0 - YubiKey Multi-Factor Authentication - Tutorial

Safeguard for Privileged Sessions YubiKey plugin parameter reference

This section describes the available options of the Safeguard for Privileged Sessions YubiKey plugin.

The plugin uses an ini-style configuration file with sections and name=value pairs. This format consists of sections, led by a [section] header and followed by name=value entries. Note that the leading whitespace is removed from values. The values can contain format strings, which refer to other values in the same section. For example, the following section would resolve the %(dir)s value to the value of the dir entry (/var in this case).

[section name]
dirname=%(dir)s/mydirectory
dir=/var

All reference expansions are done on demand. Lines beginning with # or ; are ignored and may be used to provide comments.

You can edit the configuration file from the Safeguard for Privileged Sessions web interface. The following code snippet is a sample configuration file.

[yubikey]
client_id=<YubiKey-Client-ID>
# Do NOT use api_key in production
; api_key=<YubiKey-API-key>
api_url=<API-URL1,API-URL2>
timeout=10

[users]
<exampleuser1>=abcdefghijkl
<exampleuser2>=mnopqrstuvwy

[plugin]
config_version=1
log_level=info
cred_store=<name-of-credstore-storing-sensitive-data>

[auth]
prompt=Enter your YubiKey one-time-password:
whitelist=name-of-a-userlist

[username_transform]
append_domain=""

[ldap]
ldap_server_config=<Safeguard for Privileged Sessions-LDAP-server-policy-name>
filter=(&(samAccountName={})(objectClass=user))
user_attribute=mail

[cache]
soft_timeout=15
hard_timeout=90
conn_limit=5

[question_1]
key=<name-of-name-value-pair>
prompt=<the-question-itself-in-text>
disable_echo=No
		
[question_2]...

[yubikey]

This section contains the options related to your YubiKey account.

[yubikey]
client_id=<API-integration-key>
# Do NOT use api_key in production
; api_key=<API-security-key>
api_url=<API-URL>
timeout=10
client_id
Type: string
Required: yes
Default: N/A

Description: Your YubiKey Client ID (also known as AuthID or API ID). For details on generating your Client ID and API Key, see How do I get an API key for YubiKey development?.

To generate your Client ID and API Key, authenticate yourself using a Yubikey One-Time Password and provide your e-mail address as a reference at Yubico get API key.

api_key
Type: string
Required: no
Default: N/A

Caution:

This parameter contains sensitive data. Make sure to store this data in your local credential store. Never use it in production.

For details, see "Store sensitive plugin data securely".

Only use this parameter in the configuration for testing purposes in a secure, non-production environment.

Description: Your YubiKey API key. Safeguard for Privileged Sessions uses this to communicate with the YubiKey server. For details on using a local Credential Store to host this data, read Store sensitive plugin data securely.

For details on generating your Client ID and API Key, see How do I get an API key for YubiKey development?.

To generate your Client ID and API Key, authenticate yourself using a Yubikey One-Time Password and provide your e-mail address as a reference at Yubico get API key.

Caution:

According to the current YubiKey policies, your API token expires if it is not used for 30 days. Make sure that you use it regularly, because Safeguard for Privileged Sessions will reject your sessions if the API token is expired.

api_url
Type: string
Required: yes
Default: N/A

Description: The default configuration uses Yubico's Cloud validation servers. You can also host your own YubiKey validation server. For details on hosting your own server, see YubiKey OTP Validation Server. If you decide to host your own, use this option to enter a comma-separated list of URLs that point to a YubiKey validation service. Multiple URLs will be attempted in parallel, the first response wins.

timeout
Type: integer [seconds]
Required: no
Default: 10

Description: How long the YubiKey server waits to respond.

[users]

This section contains user-YubiKey pairs.

[users]
<exampleuser1>=abcdefghijkl
<exampleuser2>=mnopqrstuvwy
<exampleuser>
Type: integer [seconds]
Required: no
Default: 10

Description: To pair YubiKeys with users, you have three options:

  • Retrieve it from userattribute through LDAP/AD.

  • Define a [users] section in the configuration file using the user=deviceid format.

  • Store the the user/device mapping in a credential store with the usual syntax: host=users, user=exampleuser, password=deviceid.

Use the second ([users] section) option only if there are not too many users, or for testing purposes. If there are too many users, it can cause performance issues.

[plugin]

This section contains general plugin-related settings.

[plugin]
config_version=1
log_level=20
cred_store=<name-of-credstore-hosting-sensitive-data>
config_version
Type: integer
Required: yes
Default: 1

Description: The version number of the configuration format. This is used to enable potentially incompatible changes in the future. If provided, the configuration will not be upgraded automatically. If not provided, the configuration will be upgraded automatically.

cred_store
Type: string
Required: no
Default: N/A

Description: The name of a local credential store policy configured on Safeguard for Privileged Sessions. You can use this credential store to store sensitive information of the plugin in a secure way, for example, the ikey/skey values in the [yubikey] section. For details, see Store sensitive plugin data securely.

log_level
Type: integer or string
Required: no
Default: info

Description: The logging verbosity of the plugin. The plugin sends the generated log messages to the Safeguard for Privileged Sessions syslog system. You can check the log messages in the Basic settings > Troubleshooting > View log files section of the Safeguard for Privileged Sessions web interface. Filter on the plugin: string to show only the messages generated by the plugins.

The possible values are:

  • debug or 10

  • info or 20

  • warning or 30

  • error or 40

  • critical or 50

For details, see Python logging API's log levels: Logging Levels.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating