Chat now with support
Chat with Support

One Identity Safeguard for Privileged Sessions 6.0.5 - DEPRECATED Okta Multi-Factor Authentication - Tutorial

Configure SPS to use Okta multi-factor authentication

Prerequisites:
  • Your Okta API token.

    Caution:

    According to the current Okta 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 Okta multi-factor authentication

  1. Download the SPS Okta plugin

    SPS customers can download the official plugin from GitHub.

  2. 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.

  3. 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.

    1. Copy your Okta API token and the name of your Okta site in the [OKTA] section of the configuration file, for example:

      [OKTA]
      APIKey=YOUR-OKTA-API-KEY
      SiteName=yoursite.okta.com
    2. Configure the usermapping settings if needed. SPS must find out which Okta 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 Okta identities.

    3. Configure other parameters of your plugin as needed for your environment. For details, see SPS Okta plugin parameter reference.

  4. 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 Okta 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 Okta plugin in terminal connections and Perform multi-factor authentication with the SPS Okta plugin in Remote Desktop connections.

    Caution:

    According to the current Okta 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 Okta plugin parameter reference

This section describes the available options of the SPS Okta 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.

[okta]
# Do NOT use api_key in production
; api_key=YOUR-OKTA-API-KEY
application_id=PSMOktaAAPlugin/%(VERSION)s
api_url=https://example.okta.com/api/v1/
default_prefix=o
timeout=60
http_socket_timeout=10
rest_poll_interval=1
ignore_conn_err=no


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

[auth]
prompt=Hit Enter to send Okta Verify push notification or provide the OTP:
whitelist=name-of-a-userlist

[username_transform]
append_domain=""

[ldap]
ldap_server_config=<SPS-LDAP-server-policy-name>
filter=(&(cn={})(objectClass=inetOrgPerson))
user_attribute=cn

[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]...

[okta]

This section contains the options related to your Okta account.

[okta]
# Do NOT use api_key in production
; api_key=YOUR-OKTA-API-KEY
application_id=PSMOktaAAPlugin/%(VERSION)s
site_name=example.okta.com
api_url=https://%(site_name)s/api/v1/
default_prefix=o
http_socket_timeout=10
ignore_conn_err=Yes
rest_poll_interval=1
timeout=55
api_key
Type: string
Required: yes
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 Okta API key. SPS uses this to communicate with the Okta server. For details on using a local Credential Store to host this data, read Store sensitive plugin data securely.

Caution:

According to the current Okta 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.

application_id
Type: string
Required: no
Default: PSMOktaMFA/1.0

Description: The application ID used in the communication with the Okta server. This ID is visible in the Okta logs.

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

Description: The URL where the Okta server can be accessed. Usually you can use the default value:

api_url=https://example.okta.com/api/v1/

To override the access URL for the Okta API, change the value.

default_prefix
Type: string
Required: no
Default: o

Description: If the user uses an OTP-like factor, and does not specify the type of factor in the OTP string, the SPS plugin assumes that the OTP is for the default factor. The possible values are as follows:

  • Google Authenticator: g

  • inWebo Authenticator: o

  • Symantec token: s

  • YubiKey: y

  • RSA token: r

If you do not set this option and the user does not specify an OTP type, the plugin assumes that the OTP received from the user is an Okta OTP.

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

Description: How long the authentication process can take during the communication with the Okta server (potentially consisting of multiple HTTP requests).

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

Description: How long the plugin waits for an approval when using the Okta push notification factor. This option sets the timeframe (measured from the user initiating the connection to SPS) within which SPS must receive the approval from the Okta server. SPS periodically asks the Okta server to check if the user successfully authenticated on the Okta server.

rest_poll_interval
Type: integer [seconds]
Required: no
Default: 1

Description: How often the plugin checks the Okta server to see if the push notification was successful. Note that SPS rejects the connection of the user if it does not receive an approval for the push notification within the period set in http_socket_timeout.

ignore_conn_err
Type: yes | no
Required: no
Default: no

Description: Determines how to handle the sessions if the Okta service is not available. If set to yes, the plugin assumes that the user successfully authenticated even if the plugin cannot access Okta to verify this.

Caution:

Enabling this option allows the users to bypass multi-factor authentication if SPS cannot access the Okta service for any reason, for example, a network configuration error in your environment.

[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 SPS (AAA > Credential Stores > <name-of-credential-store>). You can use this credential store to store sensitive information of the plugin in a secure way, for example, the Okta API key. 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 SPS syslog system. You can check the log messages in the Basic settings > Troubleshooting > View log files section of the SPS 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