Single Sign-On (SSO)

Single Sign-On (SSO) lets your enterprise customers authenticate through their existing identity provider (IdP) — Okta, Azure AD, Google Workspace, OneLogin, PingIdentity, and others. Instead of managing separate credentials in your application, your users sign in once through their corporate IdP and are automatically authenticated in yours.

Supported Protocols

Banata Auth supports the two industry-standard SSO protocols:

Both protocols achieve the same result: the user authenticates at their organization's IdP, and Banata Auth receives a verified identity assertion that maps to a user in your system.

How SSO Works

Organization-Scoped Connections

Every SSO connection belongs to an organization. This gives you fine-grained control over which identity providers serve which customers:

• Each connection belongs to exactly one organization.
• An organization can have multiple connections (for example, SAML for the main workforce and OIDC for contractors).
• Connections are scoped to your project and cannot be shared across projects.

Domain-Based Routing

When a user initiates SSO login, Banata Auth uses their email domain to determine which identity provider to route them to:

1. User enters their email address (e.g., alice@acme.com)
2. Banata Auth extracts the domain (acme.com)
3. Banata Auth looks up SSO connections with a matching domain
4. User is redirected to the organization's IdP (e.g., Okta)
5. User authenticates at the IdP
6. IdP sends an assertion back to Banata Auth
7. Banata Auth validates the assertion and creates/updates the user
8. User is signed into your application

You can associate multiple domains with a single connection. For example, if an organization owns both acme.com and acme.io, users from either domain are routed to the same IdP.

Just-in-Time (JIT) Provisioning

When a user authenticates via SSO for the first time and no matching account exists, Banata Auth automatically:

1. Creates a new user record with the identity attributes from the IdP assertion (name, email).
2. Adds the user as a member of the associated organization.
3. Assigns the default member role (configurable per organization).

This eliminates the need for administrators to pre-provision user accounts. Users are created on their first successful SSO login.

Dashboard Setup

The fastest way to set up SSO is through the Banata Auth dashboard.

Creating an SSO Connection

1. Navigate to the SSO section in the dashboard.
2. Click Create Connection.
3. Select the organization that this connection belongs to.
4. Choose the protocol: SAML 2.0 or OIDC.
5. Provide a name for the connection (e.g., "Acme Corp Okta").
6. Enter one or more email domains that should route to this connection.

Configuring SAML 2.0

After creating a SAML connection, you need to exchange metadata between Banata Auth and the IdP.

From the IdP (you'll enter these in the dashboard):

• Entity ID — The IdP's unique identifier (e.g., http://www.okta.com/exkxxxxxx)
• SSO URL — The IdP's sign-on endpoint where users are redirected
• Certificate — The X.509 certificate used to verify SAML assertion signatures

From Banata Auth (you'll provide these to the IdP):

• ACS URL — The Assertion Consumer Service URL where the IdP sends SAML responses
• SP Entity ID — Your application's unique identifier as a Service Provider
• Metadata URL — An XML document containing both values above (some IdPs accept this directly)

Configuring OIDC

For OIDC connections, you'll need the following from the IdP:

• Issuer — The IdP's issuer URL (e.g., https://accounts.google.com)
• Client ID — The OAuth 2.0 client identifier
• Client Secret — The OAuth 2.0 client secret
• Authorization URL — The endpoint where the OAuth flow begins
• Token URL — The endpoint where authorization codes are exchanged for tokens

Most OIDC providers support discovery via /.well-known/openid-configuration, which auto-populates the authorization and token URLs from the issuer.

SDK Usage

You can also manage SSO connections programmatically with the Banata Auth SDK.

Initialize the Client

import { BanataAuth } from "@banata-auth/sdk";
 
const client = new BanataAuth({ apiKey: "sk_..." });

List SSO Connections

Retrieve all SSO connections for your project:

const connections = await client.sso.listConnections();
 
for (const conn of connections) {
  console.log(conn.id, conn.type, conn.organizationId, conn.domains);
}

Get a Specific Connection

Fetch details for a single connection by ID:

const connection = await client.sso.getConnection("conn_xxx");
 
console.log(connection.type);           // "saml" | "oidc"
console.log(connection.organizationId); // "org_xxx"
console.log(connection.domains);        // ["acme.com", "acme.io"]
console.log(connection.active);         // true

Create a Connection

const newConnection = await client.sso.createConnection({
  organizationId: "org_xxx",
  type: "saml",
  name: "Acme Corp Okta",
  domains: ["acme.com"],
  samlConfig: {
    idpEntityId: "http://www.okta.com/exkxxxxxx",
    idpSsoUrl: "https://acme.okta.com/app/xxxxx/sso/saml",
    idpCertificate: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  },
});

Initiate SSO Login

Redirect the user to their IdP for authentication:

const { url } = await client.sso.getAuthorizationUrl({
  connectionId: "sso_xxx",
  redirectUri: "https://myapp.com/auth/callback",
});
 
// Redirect the user to url

Connection Field Reference

Each protocol requires different configuration fields. Use these tables as a reference when setting up connections.

SAML 2.0

OIDC

Fields marked as provided by Banata Auth (acsUrl, spEntityId) are generated when the connection is created and must be configured in the IdP.

Security

Project Scoping

SSO connections are scoped to your project. A connection created in one project cannot be accessed or used by another project, even within the same account. This ensures tenant isolation in multi-project deployments.

Domain Verification

When you associate domains with an SSO connection, Banata Auth enforces that only users with matching email domains are routed through that connection. This prevents unauthorized domain claims and ensures users are directed to the correct IdP.

Signature Validation

For SAML connections, Banata Auth validates the XML signature on every assertion using the X.509 certificate you provided during setup. Assertions with invalid, expired, or missing signatures are rejected.

For OIDC connections, tokens are validated against the IdP's published JWKS (JSON Web Key Set), ensuring that tokens were issued by the expected provider and have not been tampered with.

Additional Safeguards

• Replay protection — SAML assertions include a unique ID and timestamp. Banata Auth rejects assertions that have already been consumed or that fall outside the allowed time window.
• Audience restriction — Assertions are validated to ensure they were intended for your application (matching the SP Entity ID or Client ID).
• Encrypted assertions — Banata Auth supports receiving encrypted SAML assertions for environments that require end-to-end confidentiality of identity attributes.

Next Steps

• Organizations — Learn how to create and manage the organizations that SSO connections belong to.
• Authentication — See how SSO fits into the broader Banata Auth authentication flow.
• API Keys — Set up the project API key your SDK client needs to manage SSO connections.