Okta Multi-Factor Authentication
This page explains how to use Okta as the second factor for QuantaStor management logins: creating an Okta API token, creating the QuantaStor multi-factor authentication (MFA) configuration, enabling MFA on user accounts, and what users see when they sign in. For the MFA feature in general, see Multi-factor Authentication on the Security Configuration page; for the other supported provider, see Cisco Duo Multi-Factor Authentication.
QuantaStor talks to Okta directly through the Okta management API. You do not create an application in Okta: QuantaStor needs only your Okta org's host name and an API token, and it finds each user's enrolled Okta factors by that user's email address.
| Section | Purpose |
|---|---|
| Before you begin | Okta host name, API token, and what each user needs |
| How QuantaStor matches users to Okta | Why every account needs a matching email address |
| Creating the Okta configuration | The Create dialog and CLI |
| Enabling MFA on user accounts | Assigning the configuration to accounts |
| Signing in with Okta | The login prompt, factor types, timing, and messages |
| Modifying and deleting the configuration | Replacing the token, deleting, token rotation |
| Troubleshooting | Reading the service log for Okta errors |
Before you begin
You need:
- An Okta org, and an Okta administrator account that can create API tokens.
- An Okta user for every QuantaStor account you intend to protect, with at least one supported factor enrolled and active: Okta Verify push, a TOTP authenticator (Okta Verify or Google Authenticator codes), or SMS. See Signing in with Okta for how each one is presented.
- An Email Address on each of those QuantaStor accounts that matches the Okta user. See How QuantaStor matches users to Okta.
- Outbound HTTPS (port 443) from every QuantaStor system in the grid to your Okta org. The MFA check runs on the system you log in to.
Find your Okta org host name
The API Host in QuantaStor is your Okta org's host name only -- no https://, no path, and without the -admin part that appears in the Admin Console address. For example:
| Okta Admin Console address | Enter as API Host |
|---|---|
https://integrator-1234567-admin.okta.com/admin/dashboard |
integrator-1234567.okta.com
|
https://yourcompany-admin.okta.com/ |
yourcompany.okta.com
|
Do not enter an authorization-server URL such as https://yourcompany.okta.com/oauth2/default. QuantaStor calls the Okta management API on the bare host.
Custom Okta domains are not supported. QuantaStor decides which provider a configuration uses from the API Host, and it treats a host as Okta only when it contains .okta.com or .oktapreview.com. A custom domain such as login.example.com is classified as a Cisco Duo host, whatever you pick in the Provider list, and the configuration does not work with Okta. If your org uses a custom domain, enter its original okta.com name instead; Okta keeps that name working alongside the custom domain.
Create an Okta API token
- Sign in to the Okta Admin Console as an administrator.
- Go to Security → API and open the Tokens tab.
- Click Create token, give the token a name that identifies it (for example
quantastor-mfa), and create it. - Copy the token value now. Okta shows it only once.
An Okta API token acts with the rights of the administrator who created it. The token QuantaStor uses must be able to look up users, list their enrolled factors, and verify factors, so create it from an administrator account whose role allows that. Okta also deprovisions the token if that administrator account is deactivated, so consider creating it from a dedicated service administrator rather than a person's own account.
Treat the token as a credential. Anyone who has it can act in your Okta org with the creating administrator's rights.
How QuantaStor matches users to Okta
QuantaStor does not send the QuantaStor user name to Okta. It sends the Email Address of the QuantaStor account, and looks for an Okta user whose Username (profile login) equals it, then for one whose primary email equals it.
So, for every account that uses Okta MFA:
- Set Email Address on the account. It is on the Alert Subscriptions tab of the Add User and Modify User dialogs; see User Management. Entering an email address there does not subscribe the user to any alerts unless you also select alert severities.
- Make sure it matches the Okta user's Username or primary email exactly. In the Okta Admin Console you can check both under Directory → People on the user's Profile tab.
An account with no email address, or one that matches no Okta user, cannot complete an Okta login.
Creating the Okta configuration
The Multi-Factor Authentication Manager lists the existing configurations by Name and Provider and has Create..., Delete..., Modify... and Assign/Unassign... buttons. Click Create... to open Create Multi-Factor Authentication Configuration and fill in:
- Provider -- select OKTA. This disables Secret Key, which Okta does not use. The selection only controls which fields the dialog asks for; QuantaStor determines the provider from the API Host, as described in Find your Okta org host name.
- Name -- a unique name for the configuration. It defaults to
mfa-config-followed by a number. This is the name you pick when enabling MFA on an account. - Description -- optional.
- API Host -- your Okta org host name, for example
yourcompany.okta.com. - Key Settings group:
- Integration Key -- paste the Okta API token. The field is plain text, so the token is visible while you type it. It may contain only letters, digits, and the characters
- _ . =. - Secret Key -- disabled for Okta. Leave it empty.
- Integration Key -- paste the Okta API token. The field is plain text, so the token is visible while you type it. It may contain only letters, digits, and the characters
Click OK to create the configuration.
QuantaStor does not contact Okta when it creates an Okta configuration. A mistyped host or token is accepted here and surfaces only at the first MFA login. Test the configuration on a non-administrator account before you enable MFA on admin -- see Testing before you enable MFA on admin.
Each API token can be used by only one configuration: creating a second configuration with the same Integration Key fails because one already exists.
Creating the configuration from the CLI
Create the configuration with qs multi-factor-auth-config-create (short form qs mfa-config-create). Pass the Okta API token as --integration-key and omit --secret-key:
qs multi-factor-auth-config-create --name=okta-mfa --api-host=yourcompany.okta.com --integration-key=<okta-api-token> --description="Okta MFA for administrators"
Enabling MFA on user accounts
A configuration does nothing until it is assigned to an account and MFA is enabled on that account. There are three ways to do this.
Add User or Modify User. On the General tab, check Enable Multi-Factor Auth and choose the Okta configuration in Multi-Factor Auth Config. Both controls are greyed out until at least one MFA configuration exists. Set Email Address on the Alert Subscriptions tab in the same dialog.
Assign/Unassign. The Assign/Unassign... button in the Multi-Factor Authentication Manager assigns a configuration to several accounts at once.
CLI. Assign configurations with qs multi-factor-auth-config-set-user (short form qs mfa-config-set-user). --user-config-assignments takes a comma-separated list of user:config pairs; prefix a user name with ~ to remove that user's configuration:
qs multi-factor-auth-config-set-user --user-config-assignments=jsmith:okta-mfa,akumar:okta-mfa
To create a new account with Okta MFA already enabled, use qs user-add with --email, --enable-mfa=true and --mfa-config, along with the other arguments the account needs:
qs user-add --name=jsmith --email=jsmith@example.com --enable-mfa=true --mfa-config=okta-mfa ...
For an existing account, qs user-modify takes the same --email, --enable-mfa and --mfa-config arguments, or use the Modify User dialog.
Signing in with Okta
After a user with Okta MFA enters their user name and password and clicks Login, the Multi-Factor Authenticate dialog opens. It shows Getting user authentication devices while QuantaStor asks Okta for the user's factors, then lists them.
The dialog has:
- Authentication Device -- N/A plus one entry for each active factor enrolled on the user's Okta account.
- Authentication Mode -- how to use the selected device. The choices depend on the factor type.
- Passcode -- for a code from an authenticator app or an SMS.
- Send Authentication Request and Retry. Retry abandons the attempt and returns to the login screen.
Okta factors appear in Authentication Device like this:
| Okta factor | Listed as | Authentication Mode to choose | What the user does |
|---|---|---|---|
| Okta Verify push | Okta Verify (Push) - followed by the device type Okta reports |
Push | Click Send Authentication Request, then approve the notification in Okta Verify. |
| TOTP authenticator (Okta Verify or Google Authenticator code) | OKTA Authenticator (TOTP) or GOOGLE Authenticator (TOTP) |
Passcode | Type the current code in Passcode and click Send Authentication Request. |
| SMS | SMS to followed by the phone number |
SMS | Click Send Authentication Request, type the texted code in Passcode, then click Submit Passcode. Resend Passcode sends a new code. |
| Voice call | Call to followed by the phone number |
Phone Call | See the note below. |
Choose an Okta factor, not N/A. With Okta, every request has to name a specific factor, so N/A fails with an error.
Voice call. A voice-call factor is listed and selecting Phone Call places the call, but the dialog does not provide a way to enter the code the call reads out. Use push, TOTP or SMS for QuantaStor logins.
Other factor types enrolled in Okta, such as email or security keys, are listed by their Okta type name but cannot be used to sign in to QuantaStor. A user who has only those factors needs to enroll one of the supported types.
Push timing
After you send a push request, QuantaStor checks with Okta every 5 seconds for up to 120 seconds. If the notification is not approved in that time, the dialog shows Authentication timed out, please try again. Click Retry and log in again.
A passcode (TOTP or SMS) must be submitted within 2 minutes of entering your password. After that the dialog shows Login timed out. and you need to start again from the login screen.
What the messages mean
| Result | What the user sees | What it means | What to do |
|---|---|---|---|
| Success | The dialog closes and the WUI opens. | Okta verified the factor. | -- |
| Enroll | A URL of the form https://yourcompany.okta.com/enduser/settings |
Okta found the user but no active factors on the account. | User: open the URL, sign in to Okta, and set up a supported factor, then log in again. Admin: check that the authenticator is enabled for the user in Okta and that the factor is not pending activation. |
| Denied | The reason Okta returned, for example that the push was rejected | The user rejected the push, or Okta refused the verification. | User: log in again and approve the request. Admin: if the user did not reject it, check the user's status and sign-on policy in Okta. |
| Timed out | Authentication timed out, please try again. or Login timed out. | The push was not approved within 120 seconds, or the passcode arrived more than 2 minutes after the password. | Log in again and respond sooner. |
| Error | Your authentication request has failed due to an error. Please try again. If this problem persists, please contact support. | QuantaStor could not complete the call to Okta: wrong host, bad or expired token, a user it could not find, a rejected code, or no network path to Okta. | User: try once more, then contact your QuantaStor administrator. Admin: see Troubleshooting. The dialog never shows the underlying Okta error; the service log does. |
Modifying and deleting the configuration
Modify... changes a configuration's Name, Description, and key. Provider is greyed out and API Host is not shown: you cannot change either. To move to a different Okta org, create a new configuration and reassign the users to it.
The key fields stay disabled until you check Replace existing keys with new keys. With it checked, paste the new API token into Integration Key; Secret Key stays disabled for Okta. A key field left blank keeps the value already stored, so you never need to re-enter a token just to rename a configuration.
From the CLI, qs multi-factor-auth-config-modify takes --mfa-config and a new --integration-key.
Delete... removes configurations. If a configuration is still assigned to accounts, the delete is refused unless you check Force (required when in use). With it checked, the configuration is deleted and MFA is turned off on every account that used it -- those accounts can then log in with a password alone.
Rotating the API token
An Okta API token expires once it has gone 30 days without being used, and QuantaStor uses the token only when an MFA user logs in. On a system where Okta-protected accounts can go a month without logging in, expect the token to lapse; the next MFA login then fails with the error message above.
To rotate the token, create a new one in Okta, then open Modify... on the configuration, check Replace existing keys with new keys, paste the new token into Integration Key, and click OK. Revoke the old token in Okta afterwards. Rotate it the same way if the administrator who created it leaves or the token may have been exposed.
Testing before you enable MFA on admin
Because the Okta configuration is not checked when it is created, a mistake locks out every account that uses it. Before protecting admin:
- Create a test account with the Administrator role, an email address that matches an Okta user, and MFA enabled with the Okta configuration.
- In a separate browser session, log in as that account and complete the Okta prompt.
- Only when that works, enable MFA on admin and your other accounts.
If admin is locked out anyway -- for example because the token was revoked in Okta -- MFA can be disabled for the admin account from the system console with qs_service --disable-mfa. The procedure is on the Duo Multi-Factor Authentication page and applies to Okta too. Then fix the configuration with Modify....
Troubleshooting
The login dialog shows only a generic error. The detail is in the QuantaStor service log, /var/log/qs/qs_service.log, on the system the user logged in to. Search it for Okta.
| Symptom | Likely cause | Fix |
|---|---|---|
| Log shows an HTTP 401 error from Okta | The API token is wrong, has been revoked, or expired after 30 days without use. | Create a new token and rotate it into the configuration. |
| Log shows an HTTP 403 error from Okta | The token's administrator lacks the rights to read users or factors, or to verify factors. A wrong TOTP code can also be reported this way. | Check the code first; otherwise create the token from an administrator with sufficient rights. |
| Log shows an HTTP 404 error, or no active factors | No Okta user matches the account's email address. | Set the QuantaStor account's Email Address to the Okta user's Username or primary email. |
| Log shows a connection or name-resolution error | Wrong API Host, or no outbound HTTPS from the QuantaStor system to Okta. | Check the host name against Find your Okta org host name and the firewall path to Okta. |
| The user is sent to the Okta enrollment URL | The Okta user has no active factor. | Enroll a supported factor in Okta, or activate the pending one. |
| Configuration creation fails with a keys-invalid or invalid-characters error | The API Host is a custom domain, so QuantaStor validated it as a Cisco Duo configuration. | Use the org's okta.com host name.
|
| Voice call arrives but there is nowhere to enter the code | Not supported by the login dialog. | Use push, TOTP or SMS. |
Related pages
- Security Configuration -- user management and the multi-factor authentication overview
- Duo Multi-Factor Authentication -- setting up the Cisco Duo MFA provider, and recovering a locked-out admin account
- QuantaStor CLI Command Reference -- full argument lists for the
multi-factor-auth-config-*anduser-*commands
Verified against QuantaStor 6.9.0.