Configure your YubiKey account for SPS
Prerequisites:
The users must have a YubiKey device and a means to map usernames to YubiKey Public IDs. For details, see [users] and [ldap].
To configure your YubiKey account for SPS
-
Generate the YubiKey Client ID and API Key.
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.
A Yubico OTP is a 44-character, one-use, secure, 128-bit encrypted Public ID and Password. The OTP is comprised of two major parts: the first 12 characters remain constant and represent the Public ID of the YubiKey device itself. The remaining 32 characters make up a unique passcode for each OTP generated.
For example, in the following Yubico OTP, the characters cccjgjgkhcbb are the Public ID, and the remaining characters are the passcode.
cccjgjgkhcbbirdrfdnlnghhfgrtnnlgedjlftrbdeut
-
YubiKey does not require network connectivity or access to a mobile phone device. Just touch or tap the YubiKey device to authenticate.
Configure SPS to use YubiKey multi-factor authentication
Prerequisites:
-
Your YubiKey Client ID and 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 SPS will reject your sessions if the API token is expired.
-
Administrator access to SPS.
-
Make sure that you have all the required components listed in Technical requirements.
To configure SPS to use YubiKey multi-factor authentication
-
Download the SPS YubiKey plugin
SPS customers can download the official plugin from GitHub.
-
Upload the plugin to SPS
Upload the plugin to SPS. For details, see "Using a custom Authentication and Authorization plugin to authenticate on the target hosts" in the Administration Guide.
-
Configure the plugin on SPS
The plugin includes a default configuration file, which is an ini-style configuration file with sections and name=value pairs. You can edit it on the Policies > AA Plugin Configurations page of the SPS web interface.
-
Configure the usermapping settings if needed. SPS must find out which YubiKey user belongs to the username of the authenticated connection. For that, it can query your LDAP/Microsoft Active Directory server. For details, see Mapping SPS usernames to YubiKey identities.
-
Configure other parameters of your plugin as needed for your environment. For details, see SPS YubiKey plugin parameter reference.
-
-
Configure a Connection policy and test it
Configure a Connection policy on SPS. In the AA plugin field of the Connection policy, select the SPS YubiKey plugin you configured in the previous step, then start a session to test it. For details on how a user can perform multi-factor authentication, see Perform multi-factor authentication with the SPS YubiKey plugin in terminal connections and Perform multi-factor authentication with the SPS YubiKey plugin in Remote Desktop connections.
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 SPS will reject your sessions if the API token is expired.
SPS YubiKey plugin parameter reference
This section describes the available options of the SPS 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 SPS web interface. The following code snippet is a sample configuration file.
[yubikey] client_id=<YubiKey-Client-ID> api_key=$ api_urls=<API-URL1,API-URL2> timeout=10 [auth] prompt=Press Enter for push notification or type one-time password: disable_echo=no [connection_limit by=client_ip_gateway_user] limit=0 [authentication_cache] hard_timeout=90 soft_timeout=15 reuse_limit=0 ######[WHITELIST]###### [whitelist source=user_list] name=<name-of-user-list-policy> [whitelist source=ldap_server_group] allow=no_user except=<group-1>,<group-2> ######[USERMAPPING]###### [usermapping source=explicit] <user-name-1>=<id-1> <user-name-2>=<id-2> [usermapping source=ldap_server] user_attribute=description [username_transform] append_domain=<domain-without-@-character> [ldap_server] name=<name-of-LDAP-server-policy> [credential_store] name=<name-of-credential-store-policy-that-hosts-sensitive-data> [logging] log_level=info [https_proxy] server=<proxy-server-name-or-ip> port=3128 [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_urls=<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 | yes for testing purposes |
| Default: | N/A |
|
|
Caution:
This parameter contains sensitive data. Make sure to store this data in your local Credential Store. Type the $ value for this parameter in production. For details, see "Store sensitive plugin data securely". Only enter a value different than $ for this parameter in the configuration for testing purposes in a secure, non-production environment. |
Description: Your YubiKey API key. SPS 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 SPS will reject your sessions if the API token is expired. |
api_urls
| Type: | string |
| Required: | no |
| 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 plugin waits for YubiKey server to respond.