Enterprise SSO API

Enterprise SSO (Single Sign-On) allows organization members to authenticate using their company’s existing identity provider rather than a username and password. Auris supports both SAML 2.0 and OIDC protocols, backed by Keycloak IdP brokering under the hood.

The SSO flow works as follows:

1. An admin creates an SSO connection for an organization, providing their IdP configuration (SAML metadata or OIDC discovery URL).
2. The admin adds and verifies one or more email domains (e.g., acme-corp.com) via DNS TXT records.
3. Once the connection is activated, users with a verified domain email are automatically redirected to the IdP when they attempt to log in.
4. On first SSO login, Auris performs Just-In-Time (JIT) provisioning — creating the user account, linking it to the organization, and issuing Auris tokens — all transparently.

All admin SSO endpoints require the x-tenant header and a valid Bearer token.

SSO Connections

Query parameters

Success response

{
  "ok": true,
  "data": [
    {
      "id": "sso_abc123",
      "type": "saml",
      "name": "Acme Corporate IdP",
      "status": "ACTIVE",
      "keycloakIdpAlias": "acme-saml-abc123",
      "domains": ["acme-corp.com", "acme.io"],
      "createdAt": "2025-01-20T09:00:00Z",
      "updatedAt": "2025-02-01T14:30:00Z"
    }
  ]
}

SSO connection statuses:

SAML 2.0 Configuration

For SAML-based SSO, provide the Identity Provider’s metadata. You can supply either a metadataUrl (recommended — Auris will fetch and parse it automatically) or provide the individual fields manually.

Request body — SAML with metadata URL

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "metadataUrl": "https://idp.acme-corp.com/federationmetadata/2007-06/federationmetadata.xml"
  }
}

Request body — SAML with manual configuration

{
  "type": "saml",
  "name": "Acme Corporate SAML",
  "config": {
    "entityId": "https://idp.acme-corp.com",
    "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAX...\n-----END CERTIFICATE-----"
  }
}

OIDC Configuration

For OIDC-based SSO, provide the discovery URL and the client credentials issued by the IdP.

Request body — OIDC

{
  "type": "oidc",
  "name": "Acme OIDC Provider",
  "config": {
    "discoveryUrl": "https://login.acme-corp.com/.well-known/openid-configuration",
    "clientId": "auris-sp-client-id",
    "clientSecret": "auris-sp-client-secret"
  }
}

Success response

{
  "ok": true,
  "data": {
    "id": "sso_def456",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "PENDING",
    "keycloakIdpAlias": "acme-saml-def456",
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "entityId": "https://api.altovar.net",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Error codes

Success response

{
  "ok": true,
  "data": {
    "id": "sso_abc123",
    "type": "saml",
    "name": "Acme Corporate SAML",
    "status": "ACTIVE",
    "keycloakIdpAlias": "acme-saml-abc123",
    "config": {
      "entityId": "https://idp.acme-corp.com",
      "ssoUrl": "https://idp.acme-corp.com/saml2/sso",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpD..."
    },
    "acsUrl": "https://api.altovar.net/api/auth/sso/callback",
    "spEntityId": "https://api.altovar.net",
    "domains": ["acme-corp.com"],
    "createdAt": "2025-01-20T09:00:00Z",
    "updatedAt": "2025-02-01T14:30:00Z"
  }
}

Request body

{
  "name": "Acme Corporate SAML (Updated)",
  "config": {
    "ssoUrl": "https://new-idp.acme-corp.com/saml2/sso",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIEnD..."
  }
}

Success response

{
  "ok": true,
  "data": {
    "id": "sso_abc123",
    "type": "saml",
    "name": "Acme Corporate SAML (Updated)",
    "status": "ACTIVE",
    "updatedAt": "2025-02-18T11:00:00Z"
  }
}

Success response

{
  "ok": true,
  "data": { "deleted": true }
}

Activate and Deactivate

Request: No body required.

Success response

{
  "ok": true,
  "data": {
    "activated": true,
    "status": "ACTIVE"
  }
}

Error codes

Request: No body required.

Success response

{
  "ok": true,
  "data": {
    "deactivated": true,
    "status": "DISABLED"
  }
}

Domain Verification

Domain verification proves that you control an email domain before SSO-based auto-redirect is enabled for that domain. Verification is performed via a DNS record (TXT or CNAME). Once a domain is verified, any user who logs in with an email address on that domain is automatically redirected to the organization’s SSO provider.

Success response

{
  "ok": true,
  "data": [
    {
      "id": "dom_abc123",
      "domain": "acme-corp.com",
      "status": "ACTIVE",
      "verificationMethod": "TXT",
      "verificationToken": "auris-verify-abc123def456",
      "verifiedAt": "2025-01-22T14:00:00Z",
      "createdAt": "2025-01-20T10:00:00Z"
    },
    {
      "id": "dom_def456",
      "domain": "acme.io",
      "status": "PENDING",
      "verificationMethod": "CNAME",
      "verificationToken": "auris-verify-ghi789jkl012",
      "verifiedAt": null,
      "createdAt": "2025-02-10T08:00:00Z"
    }
  ]
}

Domain verification statuses:

Request body

{
  "domain": "acme-corp.com"
}

Success response

{
  "ok": true,
  "data": {
    "id": "dom_ghi789",
    "domain": "acme-corp.com",
    "status": "PENDING",
    "verificationMethod": "TXT",
    "verificationToken": "auris-verify-mno345pqr678",
    "dnsRecord": {
      "type": "TXT",
      "host": "_auris-verify.acme-corp.com",
      "value": "auris-verify-mno345pqr678"
    }
  }
}

Add the DNS record shown in dnsRecord at your domain registrar, then call the check endpoint to verify.

Error codes

Request: No body required.

Success response — verified

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "ACTIVE",
    "verifiedAt": "2025-02-18T15:00:00Z"
  }
}

Success response — not yet propagated

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "PENDING",
    "message": "TXT record not found yet. DNS propagation can take up to 48 hours."
  }
}

Success response — failed

{
  "ok": true,
  "data": {
    "domain": "acme-corp.com",
    "status": "FAILED",
    "message": "DNS lookup completed but the verification token was not found in any TXT records."
  }
}

Public SSO Endpoints

These endpoints are used by the Auris Hosted Login page and SDK to perform the SSO flow. They do not require authentication.

Request body

{
  "email": "[email protected]"
}

Response — SSO available

{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/acme-saml-abc123"
  }
}

Response — no SSO

{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

The response is always 200 OK regardless of whether the domain has SSO configured, to prevent information leakage about which organizations use SSO.

This endpoint is a browser redirect, not an API call. The typical flow:

1. Client detects SSO via POST /api/auth/sso/detect
2. Client redirects the browser to the loginUrl from the detection response
3. Auris redirects to the IdP’s login page
4. User authenticates at the IdP
5. IdP redirects back to Auris’s callback endpoint
6. Auris issues tokens and redirects to the application’s callback URL

Query parameters

This endpoint is called by the Identity Provider, not by your application directly.

JIT (Just-In-Time) Provisioning

When a user authenticates via SSO for the first time and does not yet have an Auris account, Auris automatically:

1. Creates a new user account using attributes from the SSO assertion (email, first name, last name)
2. Links the user to the organization that owns the SSO connection
3. Assigns the default member role (MEMBER)
4. Issues standard Auris access and refresh tokens

On subsequent logins, the existing user record is matched by email and tokens are issued directly.

Redirect on success

After successful authentication, the user is redirected to the application’s registered callback URL with an authorization code:

https://app.yourdomain.com/callback?code=auth_code_xxx&state=original_state

The authorization code can then be exchanged for tokens using the standard POST /api/auth/token endpoint with grant_type=authorization_code.

Error handling

If the SSO assertion is invalid or the IdP returns an error, the user is redirected to the application callback with error parameters:

https://app.yourdomain.com/callback?error=sso_failed&error_description=SAML+assertion+validation+failed&state=original_state

Permissions Reference

Implementation Notes

Keycloak IdP Brokering: Under the hood, Auris creates and manages Keycloak Identity Provider configurations. Each SSO connection corresponds to a Keycloak IdP with a unique alias. The Keycloak realm for the connection is determined by the keycloakRealm field on the connection record. This is an implementation detail — your application interacts only with the Auris API.

Certificate Rotation: For SAML connections, update the certificate field in the connection config when the IdP rotates its signing certificate. Auris does not automatically detect certificate changes. During rotation, you can temporarily keep both old and new certificates by updating the connection before the old certificate expires.

OIDC Discovery Caching: When using OIDC, Auris caches the discovery document. If the IdP changes its endpoints, update the discoveryUrl or wait for the cache to expire (approximately 1 hour).

Related

• Enterprise SSO Guide — Set up SAML 2.0 and OIDC connections
• Single Sign-On — SSO integration walkthrough
• Enterprise SSO — Configure SSO connections from the Console
• Organizations API — Organization endpoints that SSO connections belong to