Skip to content

Okta SSO with Better Auth

Overview

This guide connects an Okta organization directly to CloudAEye through the Better Auth SSO integration. CloudAEye supports both OpenID Connect (OIDC) and SAML 2.0.

OIDC is recommended for a new Okta integration. Use SAML when an existing identity-provider policy requires it.

CloudAEye supports one SSO connection and one company email domain per tenant. Users who authenticate with an email address from that domain are added to the tenant as members. SSO does not grant product access automatically.

Prerequisites

  • A CloudAEye tenant owner or administrator account.
  • An Okta organization with administrator access.
  • An HTTPS Okta organization URL reachable by the CloudAEye authentication service.
  • An HTTPS CloudAEye authentication API URL reachable by users' browsers and Okta.
  • An Okta user with an email address in the tenant's company domain.

Assign the test user or one of the user's groups to the CloudAEye Okta app integration before testing. Okta denies access to users who are not assigned.

!!! note

CloudAEye activates the configured domain immediately. A DNS TXT record is
not required. A company domain can belong to only one CloudAEye tenant.

Values Used in This Guide

Replace the placeholders below with values for the deployment:

Value Example
Okta organization URL https://example.okta.com
OIDC issuer https://example.okta.com
CloudAEye auth API https://auth.example.com
Company domain example.com
Tenant ID 01234567-89ab-cdef-0123-456789abcdef

To find the tenant ID, sign in to CloudAEye, open the browser developer tools, and inspect the response from GET /api/v1/tenants/current. Copy the tenantId value. CloudAEye generates the SSO provider ID as:

tenant-<tenant-id>

Do not enter or change the provider ID in the CloudAEye UI.

Configure OpenID Connect

Step 1: Calculate the Redirect URI

The Okta sign-in redirect URI must be registered before CloudAEye can validate the OIDC client. Build it from the CloudAEye authentication API and tenant ID:

<cloudaeye-auth-api>/api/auth/sso/callback/tenant-<tenant-id>

For example:

https://auth.example.com/api/auth/sso/callback/tenant-01234567-89ab-cdef-0123-456789abcdef

Step 2: Create an Okta OIDC App

  1. In the Okta Admin Console, go to Applications > Applications.
  2. Select Create App Integration.
  3. Select OIDC - OpenID Connect as the sign-in method.
  4. Select Web Application as the application type.
  5. Select Next.
  6. Enter an app integration name, such as CloudAEye.
  7. Under Grant type, enable Authorization Code. Disable implicit grants.
  8. Under Sign-in redirect URIs, enter the exact redirect URI calculated in Step 1.
  9. Set Login initiated by to App Only.
  10. Select the appropriate assignment option. For a controlled rollout, assign selected groups instead of all users.
  11. Select Save.

CloudAEye uses the authorization-code flow with PKCE and a confidential client. Do not create a Single-Page Application integration and do not use a public client without a secret.

Step 3: Collect the OIDC Values

From the Okta app's General tab, copy:

  • Client ID
  • Client secret

For ordinary workforce SSO, use the Okta organization authorization server:

https://<your-okta-domain>

Its discovery document must be available at:

https://<your-okta-domain>/.well-known/openid-configuration

If the organization intentionally uses a custom authorization server, use its exact issuer instead:

https://<your-okta-domain>/oauth2/<authorization-server-id>

The custom authorization server must have an access policy that permits the CloudAEye client and the openid, email, and profile scopes.

Step 4: Create the CloudAEye OIDC Connection

  1. Sign in to CloudAEye as a tenant owner or administrator.
  2. Go to Settings and select Single Sign On.
  3. Select OpenID Connect.
  4. Enter the following values:
CloudAEye field Value
Company domain Bare email domain, such as example.com
Issuer URL Exact Okta authorization-server issuer
Client ID Okta OIDC client ID
Client secret Okta OIDC client secret
  1. Select Create connection.
  2. Confirm that the generated Redirect URI exactly matches the URI registered in Okta.

Better Auth retrieves and validates the OIDC discovery document automatically. The discovery document's issuer value must exactly match the value entered in CloudAEye.

Configure SAML 2.0

Step 1: Calculate the CloudAEye SAML Values

Build the service-provider values from the CloudAEye authentication API and tenant ID:

ACS URL:
<cloudaeye-auth-api>/api/auth/sso/saml2/sp/acs/tenant-<tenant-id>

Entity ID:
<cloudaeye-auth-api>/api/auth/sso/saml2/sp/tenant-<tenant-id>

Metadata URL:
<cloudaeye-auth-api>/api/auth/sso/saml2/sp/metadata?providerId=tenant-<tenant-id>

Step 2: Create an Okta SAML App

  1. In the Okta Admin Console, go to Applications > Applications.
  2. Select Create App Integration.
  3. Select SAML 2.0 as the sign-in method.
  4. Select Next.
  5. Enter an app name, such as CloudAEye.
  6. Select Next.
  7. Configure the SAML settings:
Okta field Value
Single sign-on URL Calculated CloudAEye ACS URL
Use this for Recipient URL and Destination URL Selected
Audience URI (SP Entity ID) Calculated CloudAEye Entity ID
Default RelayState Leave empty
Name ID format EmailAddress
Application username Email
Response Signed
Assertion Signature Signed
Signature Algorithm RSA-SHA256
Digest Algorithm SHA256
  1. Add these attribute statements:
Name Name format Value
email Basic user.email
firstName Basic user.firstName
lastName Basic user.lastName
  1. Select Preview the SAML Assertion and confirm that each attribute occurs once.
  2. Select Next.
  3. Select I'm an Okta customer adding an internal app and This is an internal app that we have created.
  4. Select Finish.
  5. Assign the app to the test user or an applicable Okta group.

CloudAEye requires signed assertions and validates the assertion audience, destination, response correlation, timestamps, and replay state. The assertion audience must be the CloudAEye Entity ID.

Step 3: Collect the Okta IdP Values

  1. Open the CloudAEye SAML app's Sign On tab.
  2. In SAML 2.0, open Metadata details and copy the Metadata URL.
  3. Open the metadata XML in a browser.
  4. Collect these values:
CloudAEye field Metadata value
IdP issuer / entity ID EntityDescriptor entityID
SSO URL SingleSignOnService Location
Signing certificate Signing X509Certificate value

If Metadata details is unavailable, open SAML Signing Certificates, select Actions for the active SHA-2 certificate, and select View IdP metadata.

Format the signing certificate as PEM:

-----BEGIN CERTIFICATE-----
<base64 certificate from the metadata document>
-----END CERTIFICATE-----

Use the SAML signing certificate from the metadata document, not the TLS certificate for the Okta organization URL.

Step 4: Create the CloudAEye SAML Connection

  1. Sign in to CloudAEye as a tenant owner or administrator.
  2. Go to Settings and select Single Sign On.
  3. Select SAML 2.0.
  4. Enter the company domain, IdP issuer/entity ID, SSO URL, and signing certificate collected from Okta.
  5. Select Create connection.
  6. Confirm that the generated ACS URL and Entity ID exactly match the values configured in Okta.

Test the Connection

  1. In Settings > Single Sign On, select Test sign-in.
  2. Authenticate with an Okta user assigned to the app integration.
  3. Confirm that Okta returns to CloudAEye and the user is signed in.
  4. Sign out and test the public flow by selecting Sign in with SSO on the CloudAEye sign-in page.
  5. Enter the user's work email address and continue.

The work email selects the tenant's SSO connection. CloudAEye does not reveal whether a submitted domain is registered.

After the connection works, go to Settings > OAuth Config:

  • Enable Enterprise SSO under allowed sign-in methods.
  • Optionally enable Require SSO for the configured company domain.
  • Save the policy and test again in a private browser window.

Keep a tested tenant-owner recovery account before requiring SSO. SSO users follow the 2-step verification policy configured in Okta; CloudAEye's password-login 2-step verification challenge is not added to an SSO session.

Troubleshooting

Okta Reports a Redirect URI Error

Copy the active CloudAEye connection's Redirect URI and enter it as an exact Okta Sign-in redirect URI. Confirm the scheme, hostname, path, tenant ID, and trailing slash. Avoid wildcard redirect URIs.

Okta Reports invalid_client

Confirm that the Okta integration is a Web Application and that the client ID and secret in CloudAEye match the active Okta credentials. Recreate the CloudAEye connection after rotating the secret.

OIDC Discovery Fails

  • Open <issuer>/.well-known/openid-configuration from the CloudAEye authentication service's network.
  • Confirm that its issuer value exactly matches the CloudAEye Issuer URL.
  • If using a custom authorization server, confirm that its access policy permits the CloudAEye client.

CloudAEye rejects private, loopback, non-HTTPS, malformed, and mismatched OIDC issuer endpoints.

Okta Displays an Assignment Error

Assign the CloudAEye app integration to the user or to a group containing the user. Confirm that the assignment uses the expected Okta username and email.

CloudAEye Reports That Sign-In Could Not Be Completed

  • Confirm that the Okta profile contains the user's email address.
  • Confirm that the email suffix exactly matches the configured company domain.
  • For OIDC, confirm that the email and profile scopes are available.
  • For SAML, preview the assertion and confirm that it contains one email attribute or an email-formatted Name ID.
  • Confirm that cookies are accepted throughout the redirect. Starting a second sign-in attempt can invalidate the first flow's state.

SAML Audience or Destination Validation Fails

Confirm that Audience URI (SP Entity ID) is the generated CloudAEye Entity ID and that Single sign-on URL, Recipient, and Destination use the generated ACS URL.

SAML Signature Validation Fails

Confirm that Okta signs the assertion with the active SHA-2 certificate stored in CloudAEye. After an Okta signing-certificate rotation, reconfigure the CloudAEye connection with the new certificate.

SAML Response Contains Duplicate Attributes

Remove duplicate Okta attribute statements. Keep only one email, firstName, and lastName attribute.

Reconfigure or Disable Is Unavailable

Disable Require SSO in Settings > OAuth Config first. Then return to Single Sign On and select Reconfigure or Disable. Reconfiguring deletes the existing connection and creates a new one.

Security Notes

  • Never place the Okta client secret, SAML signing private key, tokens, or assertions in tickets or application logs.
  • Use an OIDC Web Application with the authorization-code flow.
  • Restrict Okta redirect URIs to the exact generated CloudAEye URI.
  • Keep Okta signing certificates and OIDC client secrets on a documented rotation schedule.
  • CloudAEye supports SP-initiated SAML sign-in. IdP-initiated SAML, SAML single logout, encrypted assertions, and IdP role mapping are not part of this flow.