Okta with Trusona as a Factor

This guide details the steps required to configure Trusona as a passwordless authentication factor within the Okta context.

When configuring Okta with Trusona as a Factor, users are redirected to an Okta landing page where they will be prompted for their username. The user can then be offered a choice to use Trusona or other Okta authentication methods. Selecting Trusona sends a security challenge for the user to Accept (or Reject) on their smartphone. By providing the username to Okta first, additional Okta authentication policies can be applied and there’s no need to scan a QR code.

Okta provides some general documentation you may wish to review for background and suggested best practices.

Custom IdP authenticator

Set up passwordless sign-in experience

1. Prerequisites

Before proceeding, ensure that you have the following steps completed:

  • Admin access to Okta Cloud IAM.
  • Have admin access to the Trusona Dashboard. If your company does not have an account, visit the Trusona Dashboard to create one. Otherwise, consult with the owner of your company’s Trusona Dashboard account in order to create the integration.

2. Getting Started

2.1. Log into the Okta admin portal

Okta admin portal
Okta admin portal

2.2. Create API token

Navigate to Security > API > Tokens and then click the Create Token button. Enter “Trusona”

Navigate to Security
Navigate to Security

Copy your API token (Token Value) and save it somewhere safe. You will be using it in later steps

Create and copy API token
Create and copy API token

2.3. Create a group

Navigate to Directory > Groups > click Add Group and create a name and a description.

  1. Name the group Trusona
  2. Provide a group description
  3. Click Add Group

This group is used to prevent users, who are using Trusona for passwordless login, from being prompted for an additional second factor of authentication.

You don’t need to maintain the membership of this group. Group membership is automatically managed by Trusona via the Okta API. Do not add any members to the group.

Create a new group
Create a new group

After creating the group, select it from the list of groups, and copy the Group ID from the URL in your address bar, as shown in the following screenshot

Copy Group ID
Copy Group ID from URL

2.4. Create Okta Integration in Trusona

Log into the Trusona Dashboard then navigate to Okta & click on Create Okta Integration.

Navigate the Trusona Integration dashboard
Navigate the Trusona Integration dashboard

2.5. Provide Okta configuration

Fill in the 4 input fields as described below:

  • Name
    • A meaningful name for the integration.
  • Okta Tenant URL
    • This will look similar to https://example.okta.com.
  • API Token
    • The value from the token you made in Step 2.2.
  • Group ID
    • This is the value from the URL you copied in Step 2.3.
Input the required data
Input the required data

Then click Save to create the Okta integration.

2.6. Okta Identity Provider details

After saving, you will see the SAML specific configuration details needed to complete the Okta Identity Provider configuration. Keep this page open for reference and return to the Okta admin portal.

View data
View data

3. Create an Identity Provider

In the Okta admin portal, navigate to Security > Identity Providers and then click Add Identity Provider.

Create an identity provider
Create an identity provider

Select SAML 2.0 IdP from the list and click Next

Select provider
Select provider

Complete the form to add the new SAML IdP using the information below:

3.1. General Settings

Field Value
Name Trusona

3.2. Authentication Settings

Field Value
IdP Usage Factor only
IdP Username idpuser.subjectNameId
Filter Unchecked
Match against Okta Username
If no match found Create new user (JIT)

3.3. SAML Protocol Settings

The exact values needed can be found in the Trusona Dashboard, by either returning to the window from step 2.6, or navigating to Okta and in the Actions submenu for your integration clicking Show.

Field Value Instructions
IdP Issuer URI https://gateway.trusona.net/saml/metadata  
IdP Single Sign-On URL https://<YOUR ORIGIN URL>/saml This is unique to your integration with Trusona. and will look something like https://example.gateway.trusona.net/saml
IdP Signature Certificate Back at the Trusona Dashboard, download the Signature Certificate by clicking the ‘View’ button and clicking ‘Download Certificate’  

Once the information in the tables above has been entered into the form, click the Finish button to continue.

Completed IdP
Completed IdP

4. Add Origin

Navigate to Security > API > Trusted Origins and click the Add Origin button.

  1. Name your Origin Trusona.
  2. To create your Origin url, copy your IDP Single Sign-On from the Okta integration in the Trusona Dashboard then delete the path /saml. Example: https://example.gateway.trusona.net
  3. Enter you newly created Origin URL.
  4. Check both CORS and Redirect checkboxes.
  5. Click Save
Add Origin
Add Origin

5. Create an Authenticator

Navigate to Security > Authentictors and click Add Authenticator and select IdP Authenticator.

  1. Select Trusona as the Identity Provider (IdP).

  2. Select the Enrollment tab and click Add Multifactor Policy.

  3. Name your policy “Trusona”.

  4. Type and select “Trusona” under Assign to Groups.

  5. Under Eligiable Authenticators, set Password and Trusona as required, email as optional.

  6. In the Add Rule dialog, set the Rule Name to Trusona. It is a best practice to exclude your primary admin user. You can enter their username/email here.

  7. Optional: If you don’t want Email to be available as a login option, click on the Setup tab. For the Email authenticator select Actions > Edit, and select Recovery.

6. Create new Sign-On policy

Navigate to Security > Authentication Policies (or Authentication > Sign on) and click Add a Policy button.

Create a new sign-on policy
Create a new sign-on policy
  1. Enter “Okta with Trusona IdP factor” for the Policy Name.
  2. Enter “Use Trusona IdP as a factor within Okta context” for the Policy Description.
  3. Click Save and then Add Rule for your new policy.
  4. Enter “Trusona IdP as factor” for the Rule Name
  5. You can specify any group you have defined for this sign-in policy under the User’s group membership includes section.
  6. Select user must authenticate with “Any 1 factor type / IdP” and Click Save.
  7. If the Catch-all rule shows a warning “Catch-all Rule has authenticator requirements that aren’t satisfied”, edit this rule to select user must authenticate with “Password / IdP” and Click Save.
  8. Under the Applications tab click on Add app and add the Okta Dashboard app to this authentication policy.

6.1. Create a Global Session Policy

Navigate to Security > Global Session Policy.

  1. Click on the Default Policy.
  2. Click on “Add rule”.
  3. Name your rule “Trusona”.
  4. Set the Identify Provider to Okta.
  5. It is a best practice to exclude your primary admin user. You can enter their username/email here.
  6. For Establish the user session with choose Any factor used to meet the Authentication Policy requirements.
  7. Set MFA to not required.
  8. Scroll down and click “Update Rule”.

6.2. Download metadata from Okta to your Trusona Okta Integration

Navigate to Security > Identity Providers. Click on the disclosure triangle to expand the Trusona IdP and then click on Download metadata.

Download metadata
Download metadata

Back on the Trusona dashboard, edit your Okta Integration.

Edit Okta Integration
Edit Okta Integration

Select the metadata.xml file you downloaded above and click Save.

Upload SAML metadata
Upload SAML metadata

7. Disable User Enumeration Prevention

Navigate to Security > General, scroll down to “User Enumeration Prevention”, click Edit, select Disabled, and press Save.

8. Test the Integration

  1. Identify or create a test user. Your test user should have installed the Trusona mobile app and followed the instructions to register with Trusona. Your test user must be in the Trusona Group. You can create a user by navigating to Directory > People and click Add person.
  2. If creating a new user, you can provide them with a temporary password, or have them receive an Email invitation to activate their account.
  3. Have the test user follow the emailed link to activate their account, or have them login with their temporary password (you can use an Incognito or Private Window to avoid logging out of your admin account while testing).
  4. Once the new user is logged in (possibly for the first time), they must be enrolled with at least one authernticator (Trusona, password, or both). Choose “My settings” from the logged in user menu on the upper right.
  5. In the Security Methods section, press the Setup button for Trusona and follow the on screen instructions to enroll your smartphone (by scanning the QR code presented). After the user has enrolled, the button for Trusona will change from Setup to Remove.
  6. The next time this user logs in to Okta, the option to use Trusona should be available.
  7. If the user sees an error that no authenticators are available, you can navigate to Security > Authenticators > Setup > Email to allow Email to be used to login (temporarily) and have them setup at least one other authenticator.

If you still see an error or were unable to login, please contact support@trusona.com

9. Customizing your Trusona experience

The Trusona Gateway (pictured below) includes default styling that will be familiar to your users using the Trusona App.


Optionally, it’s possible to provide a custom branded experience for your users including things like:

  • A custom vanity URL
  • Custom secure QR code colors
  • Your company logo and colors

In order for Trusona to create your custom gateway you need to provide to Trusona hex values and images for the following:

9.1. Provide images

  • Hero image: 1440 x 1800 px
  • Logo image: 500 x 500 px

9.2. Provide hex values

  • Animated dot color: this is the color dots that animate
  • List of QR colors: multiples of the same color will appear more (provide 2 hex values)
  • Link color: also changes the Okta widget button colors
  • Text color:
  • Background color: affects background behind the QR, usually we just do pure white (#FFFFFF)

10. Okta Identifier Registration

Users who intend to use Trusona to login to Okta must complete these required one-time steps.

  1. Download and install the Trusona App.
  2. Register in the Trusona App.
  3. Login to Okta using their existing username and password.
  4. Find, and click on, the Trusona application “chiclet” created in Step 10.
  5. Scan the QR code with the Trusona App.
  6. Accept and complete the Trusonafication.

The user’s Okta identifier has now been linked to their Trusona account and they are now ready to use Trusona to login with Okta.

Please see Integrating Trusona and Okta SCIM for SCIM provisioning.




Get started guides
Implementation guides
Users guides


Mobile SDKs
Server SDKs
Web SDKs


Authentication Service
ID Proofing Service
Mobile Auth for Browsers Service