Skip to main content

Single Sign-On (SSO) with Okta

Single Sign-On (SSO) allows you to access the Merchant Area using existing corporate credentials. By utilizing OpenID Connect (OIDC), your Identity Provider (IdP) centralizes authentication, enhancing security and streamlining the user experience.

Warning

Key Limitations:

  • OIDC Only: Merchant Area currently only supports OpenID Connect (OIDC). SAML is not supported at this time.
  • Manual Provisioning: Users must be created in both the Merchant Area and the Okta Dashboard manually. Automated role assignment and user provisioning (SCIM) are currently not supported.
  • Coexistence: Enabling Okta SSO does not disable standard email/password login.

Supported Features​

  • SP-initiated SSO: Users start at the Merchant Area login page and are redirected to Okta.
  • IdP-initiated SSO: Users click the Merchant Area tile within their Okta "My Apps" dashboard to be logged in automatically.

Configuration Steps​

1. Okta Dashboard Setup​

  1. Navigate to Applications On the left sidebar, go to Applications > Applications.

  2. Create App Integration Click the Create App Integration button.

  3. Select Protocol & Type Choose OIDC - OpenID Connect and select Web Application as the application type.

  4. Configure Redirect URIs Enter the following values in the Login section:

    • Sign-in redirect URI: https://dashboard.ebanx.com/users/auth/oktaoauth/callback
    • Sign-out redirect URI: https://dashboard.ebanx.com/sign_out

  5. Enable IdP-Initiated Login Click Edit on the General Settings tab. Under the General Settings section, find the Initiate login URI field. This is mandatory for users to log in directly from the Okta dashboard.

    • Initiate login URI: https://dashboard.ebanx.com/users/auth/oktaoauth?iss={your-org-issuer-url}
    Note

    Replace {your-org-issuer-url} with your actual Okta Issuer URL (e.g., https://your-company.okta.com/oauth2/default).

2. User Provisioning​

For a successful login, the user identity must exist in both systems:

  1. Merchant Area: Create the user via User management. Note: The user does not need to accept the standard invitation email if they are using Okta SSO.
  2. Okta: Create the user (or group) and assign them to the newly created Merchant Area Application.

Integration Parameters​

To finalize the setup, please provide the following details to your EBANX Sales Engineer:

Tip

You can identify your specific organization's URLs by visiting your OIDC Discovery Endpoint: https://{your-org}.okta.com/oauth2/default/.well-known/openid-configuration

ParameterDescriptionDefault Value (Standard)
Client IDGenerated by Okta after app creation.Unique String
Client SecretGenerated by Okta.Unique String
Okta IssuerThe base URL of your Okta server.https://{your-org}
Auth Server IDRequired if using a Custom Authorization Server.optional
Authorize URLThe endpoint to initiate authorization.https://{your-org}/oauth2/v1/authorize
Token URLThe endpoint to exchange code for tokens.https://{your-org}/oauth2/v1/token
User info URLThe endpoint to retrieve user profile information.https://{your-org}/oauth2/v1/userinfo
Whitelisted domainsThe list of whitelisted email domains to connect.@company.com, @enterprise.com, @my_custom_domain.com

How to Sign In​

Via Merchant Area (SP-initiated)​

  1. Navigate to the Merchant Area login page.
  2. Click Login with Okta.
  3. Enter your Company Name (top right name Merchant Area) when prompted.
  4. You will be redirected to Okta. Enter your credentials, and upon success, you will be returned to the Merchant Area home page.

Via Okta Dashboard (IdP-initiated)​

  1. Log in to your Okta MyApps Dashboard.
  2. Locate and click the Merchant Area icon.
  3. The application will launch and authenticate you automatically in a new tab.

FAQ​

Can I log in with a different IdP (like Google, Azure AD or AWS federation)? Yes, via Inbound Federation. If your Okta instance is configured to use Google or Microsoft as an Identity Provider, Okta will act as the "bridge." EBANX communicates with Okta, and Okta delegates the authentication to your chosen provider.

What does the "Unauthorized" screen mean? This usually means your account exists in your company's Okta directory, but you haven't been assigned to the Merchant Area application within the Okta admin settings. Contact your EBANX team for access.

Can I use a personal email address (e.g., @gmail.com)? No. SSO is strictly reserved for enterprise domains that have been whitelisted by EBANX.

Does SSO block my old password? No. Users can still sign in using their Merchant Area email and password unless your organization's internal policy dictates otherwise.

Who controls my login session duration? The session duration is controlled by the Merchant Area, not by Okta. Once authenticated, the Merchant Area's session timeout rules will apply.

Still need help?

Help Image

We hope this article was helpful. If you still have questions, you can explore the following options: