The config.json file

This configuration file must be in JSON format. It contains two sections, ibm-auth-api and credential-provider.

Format

{
    "ibm-auth-api":{
        "client-id":"????????-????-????-????-????????????",
        "ofb-client-secret":"**********",
        "protocol":"https",
        "host":"tenant.verify.ibm.com",
        "port":443,
        "max-handles":16
    },
    "credential-provider":{
        "username-format":"%D\\\\%U",
        /*"trace-file":"c:/credprov/credprov.log",*/
        "disable-builtin-password-logon": false,
        "auth-method":"winpwd-then-choice-then-otp"
    }
}

Configuring ibm-auth-api

Entry	Sample Value	Description
"client-id"	"84e8da25-d7ed-47cc-9782-b852cb64365c"	This value is required. An IBM® Security Verify API client must be created for use by the IBM Security Verify Gateway for Windows Login.
"ofb-client-secret"	"KsjKZsKrbbgNaPe7+kYIcOyWzZdzYNtF4KlCyYoNEFA="	This value is required. The IBM Security Verify API client is given a password when it is created and must be set in this configuration setting. The obf-client-secret is provided in an obfuscated form. Note: This obf-client-secret can alternatively be provided in clear text by using the "client-secret" option instead. For example, `"client-secret”:"XOpiba1XeP"` . `"obf-client-secret”: "asjKZsKrbbgNaPe7+kYIcOyWzZdzYNtF4KlCyYoNEFA=",`
"protocol"	"https"	This value is optional and defaults to “https”. This protocol is used to communicate to the Verify server. Either value, “http” or “https”, can be used. When https is used and the cacert.pem file is present, the IBM Security Verify server certificate and server name are validated.
"host"	"tenant.verify.ibm.com"	This value is required. It identifies the Verify server that you are using.
"port"	443	This value is optional and defaults to 443. This port is the port that the Verify server is listening on for requests.
"max-handles"	2	This value is optional and defaults to 16. This value is the maximum number of parallel connections that the IBM Verify Gateway for Windows Login makes to the IBM Security Verify server for user authentication. Each Credential Provider interface never uses more than two connections at the same time, so a value of 2 is appropriate.
"proxy"	"http://proxy.ibm.com:1080"	This value is optional and defaults to not using a proxy, and to use direct connections. Set the proxy to access the Verify tenant. The value is a hostname or a dotted numerical IP address. A numerical IPv6 address must be written within [brackets]. To specify port number in this string, append `:[port]` to the end of the hostname. The proxy's port defaults to `port :1080`. The proxy string can be prefixed with `[scheme]://` to specify which kind of proxy is used. http:// HTTP Proxy. The default type when no scheme or proxy type is specified. https:// HTTPS Proxy. Added in 7.52.0 for OpenSSL, Gnus, and NSS. socks4:// SOCKS4 Proxy. socks4a:// SOCKS4a Proxy. The proxy resolves the URL hostname. socks5:// SOCKS5 Proxy. socks5h:// SOCKS5 Proxy. The proxy resolves the URL hostname. Without a schema prefix, it defaults to `http://`. Setting the proxy string to `""`, an empty string, explicitly disables the use of a proxy, even if an environment variable is set for it. A proxy host string can also include protocol scheme `http://` and an embedded user and a password. Note: If you’re using an HTTPS Proxy, set the OpenSSL environment variable, `SSL_CERT_FILE`, on the Windows system where the IBM Verify Gateway for Windows Login is running. This environment variable indicates the name and location of the CA certificates file. Go to the Control Panel > System and Security System > Advanced System Settings > Environment Variables > System variables and specify the variable. For example, `SSL_CERT_FILE = C:\ Program Files\IBM\WindowsLogin\ cacert.pem`
"proxytunnel"	true	This value is optional and defaults to true if the proxy is enabled. Set the `proxytunnel` argument to `true` to make Verify tenant operation tunnel through the HTTP proxy. Using a proxy is different than to tunneling through it. Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it to connect to a remote host on a specific port number and then the traffic is passed through the proxy. Proxies allowlist the specific port numbers that it allows CONNECT requests to. Typically, only ports 80 and 443 are allowed.
"connect-timeout"	10	This value is optional and defaults to 10 seconds. The time in seconds to wait while it tries to open a connection to the Verify server. If the first attempt fails, one retry occurs.
"timeout"	20	This value is optional and defaults to 20 seconds. The time in seconds, that the IBM Verify Gateway for Windows Login waits for data to be received on the Verify server connection.
"token-type"	"Bearer"	Specifies the access token type of "access-token".
"access-token"	"abced..."	Specifies the access token to use for the tenant. This is an alternative to using "client-id" and "client-secret" options if the access token is already known.
"ca-path"	"C:\Program\Files\IBM\WindowsLogin\cacert.pem"	Specifies a file with a list of permitted certificate authority signers of the Verify tenant server certificate. This text file contains one or more PEM CA public key certificates in base64 format. By default it uses the cacert.pem file located in the configuration file directory.
"origin-user-agent"	"IBM Security Verify"	Specifies the user agent send in the request to initiate a push (device) transaction.
"proxy-ca-path"	"C:\Program\Files\IBM\WindowsLogin\cacert.pem"	Specifies a file with a list of permitted certificate authority signers of the proxy server certificate. This text file contains one or more PEM CA public key certificates in base64 format. By default it uses the cacert.pem file located in the configuration file directory.
"revoke-best-effort"	false	For the TLS communication to the Verify tenant REST API. This indicates if it should ignore certificate revocation checks in case of missing or offline distribution points for those TLS backends where such behavior is present.
"no-revoke"	false	For the TLS communication to the Verify tenant REST API. This indicates if it should disable certificate revocation checks for those TLS backends where such behavior is present. This option is only supported on Windows, with an exception in the case of Windows Untrusted Publishers block list which cannot be bypassed. This option takes precedence over "revoke-best-effort".

Configuring credential-provider

Entry	Sample Value	Description
"trace-file"	“C:\Temp\credprov.log”	This value is optional and defaults to not tracing. Note: If the file C:\Program Files\IBM\WindowsLogin\credprov.log exists, then logging is automatically enabled and at an earlier stage in the start-up of the Verify Gateway for Windows Login.
"auth-method"	"winpwd-then-choice-then-otp"	This value is optional and defaults to "winpwd-then-choice-then-otp", which defines the MFA method that is used to authenticate the user. "winpwd" Windows password only. "winpwd-and-totp" Windows password combined with the time-based one-time-passcode in a single input. "winpwd-then-smsotp" Windows password followed by the SMS one-time-passcode. "winpwd-then-emailotp" Windows password followed by an email one-time-passcode. "winpwd-then-choice-then-otp" Windows password followed by a choice from the available 2FA methods, followed by the selected one-time-passcode, or the waiting for device notification. Note: If only one choice is available, then the Choice step is skipped. "winpwd-then-device" Windows password followed by the waiting for device notification. If more than one device is registered for the user, then a choice step is presented. "winpwd-then-transient" Windows password followed by the one-time-password. If more than one transient is registered for the user, then a choice step is presented.
"accept-on-missing-auth-method"	false	This value is optional and defaults to false. If set to true and a user does not have an appropriate registered 2FA for the auth-method, then they are allowed to log on with just their password.
"password-first"	false	This value is optional and defaults to false. If set to true and the auth-method is winpwd-and-totp, then the combined password, totp value input must have the password first. If false, then the totp value must be provided first in the combined input.
"otp-prompt"	“Enter the One Time Passcode %C-”	This value is optional and defaults to “Enter the One Time Passcode %C-”. This prompt is displayed when the user is prompted to input their one-time-password. The %C string, if present in the prompt, is substituted by the correlation value for the OTP method. It is the empty string for time-based OTP.
"password-separator"	“,”	This value is optional and defaults to “`,`”. This character must be placed between the password and TOTP combined input for the "windpwd-and-totp" auth method.
"verify-method-order"	["fingerprint","userPresence"]	This value is optional and defaults to ["fingerprint","userPresence"].
"verify-message"	“Do you approve the request from winhost.ibm.com?”	This value is optional and defaults to “Do you approve the request from {hostname}?” where {hostname} is replaced by the inferred hostname that the Verify Gateway for Windows Login is running on. When the “device” auth_method is used, the user's device displays this message when the user is asked to verify the access.
"choices"	["device","transient","totp","smsotp","emailotp", "voiceotp"]	This value defines the types of 2FA that is presented to the user for the auth-method of "winpwd-then-choice-then-otp".
"transient-choices"	[ {"choice": "phoneNumbers", "sub-choices": ["mobile", "work"]}, "emails" ]	This value is optional and defaults to ["phoneNumbers","emails"]. This value defines the types of transient OTP methods that are presented to the user when transient 2FA is enabled. You can specify the sub-choices for “phoneNumbers”. Customers typically use this option to restrict the phone numbers to“mobile”. Strings or detailed objects, or both can be inter-mixed in the “transient-choices” array, to allow for compatibility with earlier versions.
"no-mfa-on-unlock"	true \| false	This entry defaults to false. When set to true, no 2FA input is requested, only the password is required to unlock the desktop.
"poll-timeout"	60	This value is optional and defaults to 60 seconds. This value specifies how long a PUSH notification from a device waits to be approved or denied by the user. If the timeout is reached, then the request is automatically denied.
"poll-rate-ms"	1000	This value is optional and defaults to 1000 milliseconds. This value specifies how often the Verify Gateway for Windows Login checks with the Verify server to determine whether the device PUSH was denied or approved. It affects how responsive the IBM Verify Gateway for Windows Login is to the device PUSH. Note: Small poll rate values send many requests per second to the Verify server, which increases its load.
"ignore-isvalidated"	false	This value is optional and defaults to false. When set to true, the Verify Gateway for Windows Login allows 2FA methods that are not validated.
"username-format"	“%D\\%U”	This value is optional and defaults to “%D\\%U”. It defines how to map the Windows user domain and name to the Verify username. Occurrences of `%D` are replaced by the Windows user's domain, and occurrences of `%U` are replaced by the windows username in the string that is provided. The values `%D` and `%U` are optional in the string.
"disable-builtin-password-logon"	false	This value is optional and defaults to false. When set to true, the Windows built-in password Credential Provider is disabled, and leaves only the Verify Gateway for Windows Login credential provider. If set to false, then both are made available by the Windows Logon as a choice. In production environments, set this value to true to ensure that users cannot bypass the Verify Gateway for Windows Login credential provider by selecting the Windows credential provider.
“rdp-only”	false	This value is optional and defaults to false. When set to true, the Verify Gateway for Windows Login credential provider is only used with Remote Desktop logon. It is not used for other logon types such as a local desktop logon.
“no-mfa-account”	“DOMAIN\\User”	This value is optional and defaults to not having an account that can bypass MFA. If set, each user logon is compared to this account. The comparison is case-insensitive. If it matches, then the user uses the auth-method of “winpwd”, which does not require 2FA or access to the Verify server. Only the Windows password is required to log on. This is a special account that allows access to the device even if the Verify service is inaccessible. Note: You might want to block this account from RDP access. The Windows administrator can block this access.
"username-table"	`"username-table": [ { "from": "testuser1", "to": "testuser1@x.y.com" }, { "from": "testuser2", "to": "testuser2@x.y.com" } ]`	This attribute maps the username to a new value. If the username is not in the table, it is used as-is.
"trace-rollover"	0	Specifies the approximate maximum size in bytes of the trace-file when the file is saved and a new empty trace-file is created. The trace-file is saved by renaming it by appending the current timestamp.
"trace-localtime"	false	Specifies if the trace file timestamps should be in local time. By default the timestamps use UTC.
"trace-prefix-all"	false	Specifies if all trace lines should be prefixed with a timestamp. By default the Verify REST API request/response trace capture lines are only prefixed on the first line.
"failmode-insecure"	false	Allows login using just the password and no 2FA if the connection to the Verify tenant REST API cannot be established.
"username-attr"	uid	When using Active Directory, the Verify username to use 2FA from can be fetched from an attribute of the Active Directory user being logged in as.
"username-cd-attr"	"urn:ietf:params:scim:schemas:extension: ibm:2.0:User:customAttributes.userAlias"	The Verify user with 2FA is located by finding an Verify user that has this attribute with a value matching the windows login username.
"username-attr-strict"	false	If set to false, then if the "username-attr" attribute is not present on the Active Directory user then the login will use the windows username to locate the Verify user for 2FA.
"username-attr-format"	"%A"	A string to map the "username-attr" value with. Any %A is replaced by the attribute value, allowing string constants to be added as a prefix and/or suffix. The default is just "%A" which is no modification.