Set up SSO with Microsoft Entra ID

Microsoft Entra ID (formerly Azure Active Directory) supports single sign-on (SSO) to Airwallex using OpenID Connect (OIDC). Connect your Entra tenant so your IT team can manage authentication centrally.

Who can configure this feature: Owners and Admin users in Airwallex, and an Entra ID administrator with permission to add applications and assign users in your Entra ID 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.

Feature availability: Entra ID integration is currently in beta and is available on request. To have it enabled for your organisation, contact your Airwallex account manager or raise a support ticket through the chat interface in the Airwallex web app.

This article covers: 

• Supported features
• Before you begin
• Set up the recommended Airwallex app
• Optional: Use your own Entra app registration
• Signing in
• Troubleshooting
• Frequently asked questions

Supported features

Before you begin

Make sure you have:

• An Airwallex organisation on an eligible plan. SSO is available on Accelerate, and on Grow and Accelerate in the US and Canada.
• An Airwallex Owner, Admin or IT Admin with permission to configure SSO.
• An Entra administrator who can grant tenant-wide admin consent for the Airwallex app. For the dedicated setup, the administrator must also be able to register an application and create a client secret.
• At least one corporate email domain that you own and can verify by adding a DNS TXT record.
• The users who need access are enrolled in your Airwallex organisation and assigned to the Airwallex enterprise application in Entra.

Assigning a user to an Entra application does not provision that user in Airwallex. Invite or enrol users in Airwallex separately. SSO applies to users whose Airwallex email address matches a domain verified for your organisation.

Set up the recommended Airwallex app

This option uses Airwallex’s shared Entra application. You do not need to create an app registration or enter a client ID or secret. An Entra administrator must grant tenant-wide consent during setup.

Step 1: Start Entra SSO setup in Airwallex

1. Sign in to Airwallex as an Owner, Admin or IT Admin with SSO setup permission.
2. Go to Settings → Connections → Security.
3. Select Microsoft Entra ID, then choose Connect with the Airwallex app (recommended).
4. Continue to the Entra administrator-consent step.

Step 2: Grant tenant-wide admin consent

1. When prompted, sign in to Entra with an account authorised to grant consent for your organisation.
2. Review the permissions shown on the Microsoft consent screen.
3. Approve the request for your organisation.
4. Return to Airwallex and continue setup.

The consent step connects your Entra tenant to Airwallex. End users do not need to grant consent individually. If you are not authorised to grant tenant-wide consent, ask your Entra administrator to complete this step.

Step 3: Test the connection

1. Follow the Airwallex prompt to test the connection using your own Entra account.
2. Confirm that the account belongs to the intended Entra tenant and can authenticate successfully.
3. Continue only after Airwallex confirms that the connection test passed.

Step 4: Verify your email domain

1. In the Airwallex SSO setup, enter the corporate email domain you want to verify and select Add domain.
2. Copy the TXT record generated by Airwallex.
3. Sign in to your DNS provider and add the TXT record exactly as shown.
4. Return to Airwallex and select Verify.
5. When the domain status is Verified, continue.

DNS changes can take time to propagate. Leave the TXT record in place after verification; Airwallex may periodically re-check domain ownership. A domain can be associated with only one Airwallex organisation at a time.

Step 5: Review access and choose backup users

1. Review the users and login methods shown in the Airwallex setup.
2. Confirm that the intended users have the correct email domains and are assigned to the Airwallex enterprise application in Entra.
3. Remove or offboard anyone who should no longer have Airwallex access.
4. Nominate at least one eligible Owner, Admin or IT Admin to retain the secure backup sign-in method. Airwallex recommends nominating two eligible users so access does not depend on one person.

Users on domains that are not verified for the organisation will not be routed through this SSO connection. Review external collaborators and users with personal or partner-company email addresses before activation.

Step 6: Activate SSO

1. Review the final setup summary and the users affected by the change.
2. Select Activate SSO.
3. Allow time for the change to apply across your organisation.

After activation, users whose email addresses match a verified domain are routed to Entra when they sign in to Airwallex.

Optional: Use your own Entra app registration

Choose this option if your organisation requires a customer-owned app registration. You will create an OIDC web application in your Entra tenant and provide its tenant ID, client ID and client secret to Airwallex.

Step 1: Create an app registration

1. Sign in to the Microsoft Entra admin center.
2. Open App registrations and select New registration.
3. Enter a name, such as Airwallex SSO.
4. Register the app for accounts in your organisation’s directory.
5. Under the Web redirect URI platform, enter the redirect URI displayed in the Airwallex setup screen. Copy it exactly, then register the app.

Use the redirect URI provided by Airwallex for your connection. Do not substitute a URI from another integration or configure SAML for this OIDC connection.

Step 2: Copy the application and directory IDs

From the app registration’s overview page, copy:

• Application (client) ID
• Directory (tenant) ID

Keep the tenant ID for the Airwallex setup. The connection uses Entra’s OIDC v2.0 endpoints for that tenant.

Step 3: Create a client secret

1. In the app registration, open Certificates & secrets.
2. Select New client secret and create a secret that complies with your organisation’s credential policy.
3. Copy the secret Value when it is displayed. The value may not be shown again.
4. Store it securely and plan to rotate it before it expires.

Treat the client secret as a password. Do not send it by email or chat.

Step 4: Enter the app details in Airwallex

1. Return to Settings → Connections → Security in Airwallex and select Microsoft Entra ID.
2. Choose Use your own app registration.
3. Enter the Directory (tenant) ID, Application (client) ID and client secret from the app registration.
4. If prompted, configure the authentication context required for your organisation’s region.
5. Select Test connection and continue and complete the sign-in test.

If the client secret expires or is rotated, update the saved secret in the Airwallex connection settings so users can continue to sign in.

Then complete domain verification, access review and backup-user selection, and activation above.

Signing in

1. Go to the Airwallex sign-in page and select Log in with SSO.
2. Enter your work email address.
3. Airwallex redirects you to Microsoft Entra ID for authentication.
4. Complete any MFA or authentication-context challenge required by your organisation’s Entra policies.
5. After successful authentication, you return to Airwallex.

You can also launch Airwallex from a tile in Microsoft My Apps. The tile opens the Airwallex sign-in flow, which then redirects to Entra; it does not start a direct Entra-initiated OIDC sign-in.

Troubleshooting

The admin-consent step does not complete

• Confirm that you started setup in the correct Entra tenant.
• Make sure the account granting consent has permission to grant tenant-wide admin consent.
• If consent was revoked or the requested permissions changed, ask an Entra administrator to grant consent again.

The connection test fails

• Confirm that you selected the correct Entra tenant.
• For the dedicated app, check the tenant ID, client ID and client secret. Make sure you copied the secret Value, not its ID, and that the secret has not expired.
• Confirm that the redirect URI in the app registration exactly matches the URI shown in Airwallex.
• Confirm that the signing-in user is assigned to the Airwallex enterprise application and is enrolled in the Airwallex organisation.

Domain verification fails

• Confirm that the TXT record was added to the correct domain and that its name and value match the record shown in Airwallex.
• Allow time for DNS changes to propagate, then try verification again.
• Do not remove a TXT record after the domain is verified.

A user is not redirected to Entra

• Confirm that the user’s Airwallex email address matches a domain verified for the organisation.
• Confirm that the user is assigned to the Airwallex application in Entra and has an eligible Airwallex user account.
• Users on other email domains continue to use the sign-in method configured for those users.

Frequently asked questions

Does the recommended setup require me to create an Entra app registration?

The recommended setup connects your tenant to the Airwallex app through tenant-wide admin consent. Create your own app registration only if you choose the dedicated setup.

Does SSO create Airwallex users automatically?

Entra app assignment does not create an Airwallex user. Enrol users in Airwallex separately; SCIM provisioning is not included in this integration.

Can I use SAML or SCIM with this Entra connection?

This connection uses OIDC. SAML and SCIM provisioning are not included.

Can I keep another IdP active while I set up Entra?

Only one identity-provider connection can be active for an Airwallex organisation at a time. To switch from another IdP to Entra, deactivate the existing connection and then set up Entra. Review the deactivation warning because users may need to reset their passwords before they can sign in again.