SPS Starling plugin parameter reference
This section describes the available options of the SPS Starling 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.
[starling]
# Do NOT use api_key in production
; api_key=<Subscription-Key>
; api_url=https://api.2fa.cloud.oneidentity.com
timeout=60
rest_poll_interval=1
[users]
<exampleuser1>=123456789
<exampleuser2>=987654321
[plugin]
config_version=1
log_level=info
cred_store=<name-of-credstore-storing-sensitive-data>
[auth]
prompt=Hit Enter to send Starling 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=(&(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]...
[starling]
This section contains the options related to your Starling account.
If you are using a Starling 2FA plugin, (that is, you have uploaded it to Basic Settings > Plugins and then configured it at Policies > AA Plugin Configurations) and the SPS node is joined to One Identity Starling, you do not have to specify api_key and api_url in the Starling 2FA plugin configuration. This configuration method is more secure.
[starling] # Do NOT use api_key in production ; api_key=<Subscription-Key> ; api_url=https://api.2fa.cloud.oneidentity.com timeout=60 rest_poll_interval=1
api_key
| Type: | string |
| Required: | no | yes for testing purposes if SPS is not joined to One Identity Starling |
| 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 Subscription Key. Log on to your One Identity Starling account. Navigate to Dashboard and click Subscription Key. SPS uses this to communicate with the Starling server. For details on using a local Credential Store to host this data, read Store sensitive plugin data securely.
|
|
Caution:
According to the current Starling 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_url
| Type: | string |
| Required: | yes |
| Default: | N/A |
Description: The URL where the One Identity Starling server can be accessed. Usually you can use the default value:
api_url=https://api.2fa.cloud.oneidentity.com
To override the access URL for the Starling API, change the value.
timeout
| Type: | integer [seconds] |
| Required: | no |
| Default: | 60 |
Description: How long an HTTP request can take during communication with the Starling server.
rest_poll_interval
| Type: | integer [seconds] |
| Required: | no |
| Default: | 1 |
Description: How often the plugin checks the Starling server to see if the push notification was successful.
[users]
This section contains user-Starling 2FA application pairs.
[users] <exampleuser1>=123456789 <exampleuser2>=987654321
<exampleuser>
| Type: | integer [seconds] |
| Required: | no |
| Default: | 10 |
Description: To pair Starling 2FA applications with users, you have three options:
-
Retrieve the name of the user an attribute of the user stored in LDAP/AD.
-
Define a [users] section in the configuration file using the user=uniqueid format.
When users install the app, they register with a mobile phone number that serves as their unique ID. Users can install the app on different devices and register with the same phone number in order to be able to have a backup device in case the primary device is inaccessible.
-
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 SPS. 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 [starling] 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 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.