Okta Verify configuration settings for Linux

Policy settings

All settings in /etc/okta/adminconfig.json appear under a single top-level configuration object. The file is in JSON format with settings provided as flat key and value pairs:

{
  "configuration": {
    "EnrollmentOptions": "Enabled",
    "OrgUrl": "https://example.okta.com",
    "ReportDiagnostics": "False",
    "LogLevel": "Debug"
  }
}

Configuration options

Use the following options and values to configure your Okta Verify policy file:

EnrollmentOptions

Configure whether end users are prompted to enroll in Okta Verify during authentication.

You can use this option to reduce the number of enrollment prompts shown to a user, or to control the rollout of Okta Verify and Okta FastPass in your org.

Value [String] Description

Value [String]	Description
`SilentEnrollmentDisabled`	The app prompts users to enroll an account during authentication only when they select Sign in with Okta Verify. This is the default.
`Enabled`	The app prompts users to enroll an account during an Okta FastPass authentication, including flows that don't require user interaction.
`Disabled`	The app never prompts users to enroll in Okta Verify during authentication. To enroll, users must open the Okta Verify app and select Add an account.

SilentEnrollmentDisabled

The app prompts users to enroll an account during authentication only when they select Sign in with Okta Verify.

This is the default.

Enabled

The app prompts users to enroll an account during an Okta FastPass authentication, including flows that don't require user interaction.

Disabled

The app never prompts users to enroll in Okta Verify during authentication.

To enroll, users must open the Okta Verify app and select Add an account.

LogLevel

Configure the depth of logging sent to the log files.

Value [String]	Description
`None`	No messages are logged. Use this setting to disable logging.
`Critical`	Critical messages indicate a non-recoverable failure that may cause the app to crash.
`Error`	Error messages indicate a failure that may be recoverable but causes a significant failure of a component or an operation.
`Warning`	Warning messages indicate a potential issue or unexpected behavior that doesn't cause a failure, but may require attention.
`Info`	Informational messages provide general information about an operation, such as the start and finish, or other important milestones. These messages are typically used for monitoring and diagnostics.
`Debug`	Debug messages provide detailed information for diagnosing issues and understanding the internal state of the app. These messages are typically used during development and troubleshooting operations. This is the default log level for Okta Verify on Linux.

OrgUrl

When you configure this option, the org URL appears on the user's enrollment page.

This option has no default value.

Value [String]	Description
`<fully-qualified-domain-name>`	The complete URL for your org, including the `https://` prefix, for example, `https://okta.okta.com`.
`<org-sign-in-URL>`	The domain name for your org without a protocol prefix, for example, `okta.okta.com`.

ReportDiagnostics

Configure whether crash reports are sent to Okta's diagnostic and telemetry tools.

Value [String] Description

Value [String]	Description
`True`	Sends crash reports. This is the default.
`False`	Crash reports aren't sent.

True

Sends crash reports.

This is the default.

False

Crash reports aren't sent.

UserVerificationEnrollment

Early Access release

Configure the user verification enrollment behavior for Okta Verify. If this option isn't configured, the server configuration determines the enrollment behavior.

Note:

The user verification enrollment setting on the Okta Verify client app always overrides the enrollment policy configured on your org.

If you set the user verification level on your org to Required, then a client set to Deferred, Disabled, or Preferred doesn't satisfy the enrollment policy requirements and the enrollment is denied.

Value [String]	Description
`Disabled`	Users aren't prompted to enroll in user verification during enrollment. The option to enable user verification in the Accounts page isn't available in the Okta Verify app.
`Deferred`	Okta Verify skips the user verification enrollment page. Users can enable user verification later through the Accounts page in the Okta Verify app.
`Preferred`	Okta Verify prompts users to enroll in user verification, but they can click Not now to skip.
`Required`	Users must enroll in user verification and can't remove it afterward.

File permissions

The following table outlines the ownership and mode options for the policy file and its parent directory.

Object Owner and group Mode Reason

Object	Owner and group	Mode	Reason
`/etc/okta` (directory)	`root:okta-ff`	`1775`	The installer sets these modes. The group write setting allows the Okta feature flag service to maintain its cache. The sticky bit prevents it from replacing any root-owned policy files. The world setting of `r-x` lets the desktop app traverse the directory.
`/etc/okta/adminconfig.json` (file)	`root:root`	`0444`	Read-only to everyone, but only root can write to this file.

/etc/okta (directory)

root:okta-ff

1775

The installer sets these modes.

The group write setting allows the Okta feature flag service to maintain its cache.

The sticky bit prevents it from replacing any root-owned policy files.

The world setting of r-x lets the desktop app traverse the directory.

/etc/okta/adminconfig.json (file) root:root 0444 Read-only to everyone, but only root can write to this file.

Note:

The adminconfig.json file must be world-readable. Three accounts read it:

The Okta Verify desktop app, which runs as the signed-in user
The Okta feature flag service, which runs as the dedicated okta-ff system account
The Okta authenticator service, which runs as root

Setting a mode such as 0600 or 0640 root:root prevents both the app and the feature flag service from reading the policy. Okta Verify then reverts to the installation defaults, and ignores the policy file.

Other restrictions on the /etc/okta/adminconfig.json file and the /etc/okta directory:

Don't set the file as writable by non-root users. Using a mode of 0666, 0664, or assigning an owner other than root would permit a local user to rewrite the device policy.
Don't create or use a symbolic link to the file.
Don't place the directory on a restricted-execution or network mount that might be unavailable at boot.
Don't restrict the directory. Changing it to 0750 breaks the desktop app's ability to reach the file.

Applying policy changes

After you deploy or update the policy file, each component picks up the change differently. Use the following table to see what to expect from each component, including how to force an immediate refresh.

Component How changes are picked up

Component	How changes are picked up
Okta Verify desktop app	The app watches the configuration file. Some settings are read on launch, however most changes require the user to quit and relaunch Okta Verify.
Okta authenticator service	The service pulls in the configuration file at startup. Run `sudo systemctl restart okta-authenticator.service` to restart the service and apply changes immediately.
Okta feature flag service	This service watches the configuration file for changes, but you can restart the service with the command: `sudo systemctl restart okta-feature-flag.service`.

Okta Verify desktop app

The app watches the configuration file.

Some settings are read on launch, however most changes require the user to quit and relaunch Okta Verify.

Okta authenticator service

The service pulls in the configuration file at startup.

Run sudo systemctl restart okta-authenticator.service to restart the service and apply changes immediately.

Okta feature flag service

This service watches the configuration file for changes, but you can restart the service with the command: sudo systemctl restart okta-feature-flag.service.

Note: Rebooting the device picks up all changes.

Related files

The following files in /etc/okta are related to the proper functioning of the Okta Verify app:

File	Owner, group, and mode	Purpose
`oktaverify.json`	`root:root 0444`	Baseline settings for the installer. The `adminconfig.json` overrides the setting for any shared key. Edit `adminconfig.json` instead of this file.
`azureconfig.json`	`root:okta-ff 0440`	Configuration file for the Okta service. This isn't world-readable by design. Don't change this permission.
`featureflagscache.json`	`okta-ff:okta-ff 0644`	Runtime cache maintained by the Okta feature flag service. Don't edit or delete this file.
`authenticator/Plugins/`	`root:root`	Directory for device-attestation plugin manifests, if your deployment uses them.

App lifecycle

After installing the package and the policy settings, the app lifecycle consists of three potential future actions:

Upgrade

As adminconfig.json isn't managed by the package manager, when you upgrade or reinstall the Okta Verify app, it never modifies, replaces, or prompts you about this file.

Remove

To remove the package, run apt remove okta-verify.

This doesn't remove the policy file, so any policy settings survive if you reinstall the package.

Purge

To purge the package, run apt purge okta-verify.

The purge action deletes the /etc/okta directory, including the adminconfig.json file. If you run a purge and then reinstall the package, you must redeploy the policy file.

A purge also deletes the /var/log/okta folder, including the Okta authenticator and feature flag service log files. Collect any logs required for a support case before you purge the package.

Important:

A purge doesn't remove the individual OktaVerify*.log files located in the ~/.local/share/okta/Logs/ directory.

Log files

Use the following logs for support cases.

Scope Path Contents

System services

Scope	Path	Contents
System services	`/var/log/okta/OktaLinuxAuthenticatorService.log` `/var/log/okta/OktaLinuxFeatureFlagService.log`	These system service logs roll daily or when they reach 5 MiB. The logs are retained for 7 days. As the logs also roll when they reach the size limit, a busy day can produce more than one file. This means that a 7-day retention window doesn't cap the total log sizes at 5 MiB times 7.
Desktop app	`~/.local/share/okta/Logs/OktaVerify*.log`	These app logs are created for each user and have the same rolling policy as the system service logs.
`systemd` journal	`journalctl -u okta-authenticator -u okta-feature-flag`	These logs contain details from the app startup and any crashes.

/var/log/okta/OktaLinuxAuthenticatorService*.log

/var/log/okta/OktaLinuxFeatureFlagService*.log

These system service logs roll daily or when they reach 5 MiB.

The logs are retained for 7 days.

As the logs also roll when they reach the size limit, a busy day can produce more than one file.

This means that a 7-day retention window doesn't cap the total log sizes at 5 MiB times 7.

Desktop app ~/.local/share/okta/Logs/OktaVerify*.log These app logs are created for each user and have the same rolling policy as the system service logs.

systemd journal journalctl -u okta-authenticator -u okta-feature-flag These logs contain details from the app startup and any crashes.

The default log level for Okta Verify on Linux is Debug.