Set up SSO with Okta

Airwallex supports Single Sign-On (SSO) with Okta using OpenID Connect (OIDC), so your IT team can centrally enforce authentication and manage access to Airwallex through your existing Okta tenant.

Who can configure this feature: Owners and Admin users in Airwallex, and an Okta administrator with permission to add applications and assign users in your Okta tenant. Learn more about User Roles.

Plan availability: Available on the Accelerate plan. In the US and Canada, available on both the Grow and Accelerate plans.

This article covers everything you need to set up SSO end to end:

• Supported features
• Prerequisites
• Step 1: Add the Airwallex app in Okta
• Step 2: Assign users and groups in Okta
• Step 3: Copy the OIDC credentials
• Step 4: Configure the connection in Airwallex
• Step 5: Verify your domain
• Step 6: Nominate a backup user
• Step 7: Review your users
• Step 8: Activate SSO
• Signing in
• Troubleshooting
• Frequently asked questions

Supported features

For definitions of the terms used in this guide, see Okta's SSO glossary.

Prerequisites

Before you begin, make sure you have all of the following.

In Airwallex:

• An active Airwallex organisation on a plan that includes SSO (see Plan availability above).
• An Airwallex user with the Owner or Admin role. Only these roles can configure SSO.
• At least one corporate email domain that you own, and the ability to add a DNS TXT record for that domain.
• The users who need SSO access already exist in your Airwallex organisation. Assigning a user to the Airwallex app in Okta does not create that user in Airwallex — invite them first from Settings → User Management (or via your HRIS integration) if they don't already have an account.

In Okta:

• An Okta administrator account with permission to add applications from the Okta Integration Network (OIN) catalog and assign users.

Step 1: Add the Airwallex app in Okta

1. Sign in to the Okta Admin Console.
2. Go to Applications → Applications, then click Browse App Catalog.
3. Search for Airwallex and select the Airwallex app from the Okta Integration Network (also available at:  https://www.okta.com/integrations/airwallex/).
4. Click Add Integration.
5. On the General Settings tab, enter an Application label (for example, Airwallex), then click Next.
6. On the Sign-On Options tab, leave the default OIDC settings in place and click Done.

The integration ships with the Airwallex sign-in redirect URIs and initiate-login URI already configured — you don't need to enter any Airwallex-specific values in Okta.

Reference: values configured by the integration

You don't need to set these manually, but they're listed here for your records and for internal security review.

Step 2: Assign users and groups in Okta

1. Open the Airwallex app and go to the Assignments tab.
2. Click Assign → Assign to People or Assign to Groups.
3. Select the users or groups who should be able to sign in to Airwallex.
4. Click Assign, then Done.

Only users assigned to the Airwallex app in Okta can authenticate to Airwallex via SSO. Assigning a user in Okta does not create that user in Airwallex — the user must already exist in your Airwallex organisation.

Step 3: Copy the OIDC credentials

From the Airwallex app in Okta, collect the following. You'll paste these into Airwallex in the next step.

1. Client ID
2. Client secret
3. Issuer URL — your Okta domain, in the form https://your-domain.okta.com. Do not include -admin in the hostname.

Treat the client secret as a credential: copy it directly into Airwallex and don't circulate it by email or chat.

Step 4: Configure the connection in Airwallex

1. Sign in to Airwallex at www.airwallex.com/app/login as an Owner or Admin.
2. Go to Settings → Connections → Security.
3. Select Okta and click Set up.
4. Enter the Issuer URL, Client ID, and Client secret you copied in Step 3.
5. Click Test connection and continue.

Airwallex validates the connection end to end before allowing you to proceed. If the test fails, review the configuration in Okta — most failures are caused by a mismatched redirect URI or by the signing-in user not being assigned to the app — then try again.

Step 5: Verify your domain

You must verify ownership of at least one domain before SSO can be activated. Once a domain is verified, any user in your Airwallex organisation whose email address matches that domain becomes eligible to sign in via SSO.

Important: only users whose email address matches a domain you've verified in Airwallex will be routed through SSO. Users on any other domain continue to sign in with email and password.

1. Enter the domain you want to verify and click Add domain.
   
   
    
2. Airwallex generates a unique TXT record (verification key) for that domain.
3. Sign in to your DNS provider, open the DNS records for the domain, and add the TXT record exactly as provided by Airwallex. Save the record.
4. Return to the Airwallex SSO configuration page and click Verify selected. Airwallex performs a DNS lookup to confirm the record is present.
   
   
    
5. When the lookup succeeds, the domain status changes to Verified. Click Continue.

A few things to keep in mind:

• DNS propagation can take 24–48 hours. You can continue with the rest of the configuration while verification is pending, but SSO stays inactive for any domain that isn't yet verified.
• Do not delete the TXT record after verification. Airwallex periodically re-checks domain ownership, and removing the record may cause your organisation to lose SSO access.
• A domain can be associated with only one Airwallex organisation at a time. If you see an error saying the domain is already in use, contact Airwallex support.
• You can verify multiple domains for the same organisation if your users sign in with different email domains.

Step 6: Nominate a backup user

Before activating SSO, nominate at least one Owner or Admin who retains standard email and password login access. This guarantees a backup sign-in method if your Okta tenant is unavailable.

Step 7: Review your users

Review user access before you enforce SSO.

• Use Filters on the user list and filter where New login method is Password to identify users who won't be routed through SSO.
• Offboard any user who should no longer have access, in Settings → User Management, before activating SSO.
• Review external collaborators and guests. Contractors, auditors, or partners using a personal email address or another company's domain will fall outside your Okta tenant's control once SSO is active.
• Where possible, bring external collaborators into Okta as guest identities under a separate user pool, so all access stays centrally governed and you avoid users that bypass your SSO controls.

Step 8: Activate SSO

On the final review screen, click Activate SSO. Depending on the number of users in your org, the SSO migration may take 1–2 hours. Once the migration is complete, any user with an email address matching one of your verified domains will be routed to Okta.

Signing in

SP-initiated sign-in

1. Go to www.airwallex.com/app/login and select Log in with SSO
2. Enter your work email address.
3. If your email domain is verified and SSO is active, Airwallex redirects you to your Okta sign-in page.
4. Authenticate with Okta, including any MFA required by your Okta app sign-on policy.
5. Okta returns you to Airwallex and your session starts.

SP-initiated sign-in is also supported in the Airwallex iOS and Android apps, which hand off to Okta using the standard app-to-app redirect pattern.

Launching Airwallex from Okta

Airwallex does not support IdP-initiated sign-in. Sign-in must start at the Airwallex sign-in page, which then hands off to Okta for authentication.

If you want your users to be able to reach Airwallex from their Okta End-User Dashboard, add a bookmark app. The tile behaves like any other app tile, but instead of starting the sign-in at Okta it opens the Airwallex sign-in page, where the standard SSO flow takes over.

To add the bookmark app:

1. In the Okta Admin Console, go to Applications → Applications, then click Browse App Catalog.

2. Search for Bookmark App and select it, then click Add Integration.

3. Enter an Application label (for example, Airwallex).

4. In the URL field, enter https://www.airwallex.com/app/login?sso=true.

5. Click Done, then assign the bookmark app to the relevant users and groups on the Assignments tab.

What your users will experience:

• Clicking the tile opens the Airwallex Log in with SSO page.

• The first time they use it, they enter their work email address so Airwallex knows which organisation and identity provider to route them to. They are then redirected to Okta to authenticate as normal.

• On subsequent visits from the same browser, Airwallex reuses the email address from their last SSO sign-in, so they go straight through to Okta without re-entering it.

Troubleshooting

The connection test fails in Airwallex. Check that the Client ID, client secret, and Issuer URL were copied exactly, and that the Issuer URL doesn't contain -admin. Confirm that the user running the test is assigned to the Airwallex app in Okta.

Domain verification fails. If verification fails immediately, wait 15–30 minutes and try again — DNS changes can take up to 24 hours to propagate globally. If it's still failing after 24 hours, confirm that the TXT record was added to the correct domain (not a subdomain) and that the Name/Host and Value/Content match exactly what Airwallex provided, including any prefixes or trailing characters. If the records are correct and verification still fails, contact Airwallex support.

Some users are still prompted for a password. SSO applies only to users whose email address matches a verified domain. Users on any other domain continue to use email and password. Verify the additional domain, or move those users onto a verified domain.

Frequently asked questions

Can I configure more than one identity provider? No. Airwallex supports a single IdP per organisation.

Does enabling SSO force every user in my organisation to use SSO? No. It applies only to users whose email address matches one of your verified domains. This lets you continue to support guest users and external collaborators on other domains.