SSO Provider Integration

OpenBoxes Lift uses Keycloak as its identity broker, allowing you to connect your organization's existing identity provider (IdP) for single sign-on. Users authenticate through your IdP and are automatically granted access to OpenBoxes --- no separate passwords to manage.

Supported Protocols and Tiers

Protocol Supported Providers Tier Required
OpenID Connect (OIDC) Okta, Azure AD, Google Workspace, Auth0 Dedicated+
SAML 2.0 Any SAML-compliant IdP (ADFS, PingFederate, Shibboleth) Enterprise

Note: The Shared tier uses Keycloak-managed accounts with email/password authentication. SSO with external identity providers requires a Dedicated or Enterprise plan.

How SSO Works

User --> Your Identity Provider --> Keycloak (OpenBoxes Lift) --> OpenBoxes
  1. The user navigates to your OpenBoxes instance (e.g., yourorg.openboxes.cloud).
  2. They are redirected to your organization's identity provider login page.
  3. After authenticating, the IdP sends an assertion back to Keycloak.
  4. Keycloak maps the user's identity and provisions access to OpenBoxes.
  5. The user is logged into OpenBoxes with the appropriate role.

Setting Up Okta (OIDC)

Tier required: Dedicated or Enterprise

In Okta

  1. Log in to your Okta admin console.
  2. Go to Applications > Create App Integration.
  3. Select OIDC - OpenID Connect and Web Application.
  4. Configure the following:
    • App name: OpenBoxes Lift
    • Sign-in redirect URI: https://auth.openboxes.cloud/realms/openboxes-cloud/broker/okta/endpoint
    • Sign-out redirect URI: https://auth.openboxes.cloud/realms/openboxes-cloud/broker/okta/endpoint/logout_response
  5. Note the Client ID and Client Secret.
  6. Under Assignments, assign the users or groups that should have access.

In OpenBoxes Lift

  1. Contact your OpenBoxes Lift support team or submit a configuration request through the portal.
  2. Provide:
    • Okta Client ID
    • Okta Client Secret
    • Okta domain (e.g., yourorg.okta.com)
  3. The Lift team will configure the Keycloak identity provider and notify you when ready.

Setting Up Azure AD (OIDC)

Tier required: Dedicated or Enterprise

In Azure Portal

  1. Go to Azure Active Directory > App registrations > New registration.
  2. Configure:
    • Name: OpenBoxes Lift
    • Redirect URI (Web): https://auth.openboxes.cloud/realms/openboxes-cloud/broker/azure-ad/endpoint
  3. After registration, note the Application (client) ID and Directory (tenant) ID.
  4. Go to Certificates & secrets > New client secret and note the secret value.
  5. Under API permissions, ensure openid, profile, and email are granted.

In OpenBoxes Lift

  1. Contact support or submit a configuration request.
  2. Provide:
    • Application (Client) ID
    • Client Secret
    • Directory (Tenant) ID
  3. The Lift team will complete the Keycloak configuration.

Setting Up SAML 2.0

Tier required: Enterprise

SAML integration supports any standards-compliant identity provider. You will exchange metadata with the OpenBoxes Lift team.

What You Provide

  • IdP Metadata XML or the metadata URL (e.g., https://idp.yourorg.com/metadata)
  • Entity ID of your IdP
  • Signing certificate (if not included in metadata)
  • Attribute mappings for email, first name, and last name

What We Provide

  • SP Metadata URL: https://auth.openboxes.cloud/realms/openboxes-cloud/broker/saml/endpoint/descriptor
  • Entity ID: https://auth.openboxes.cloud/realms/openboxes-cloud
  • ACS URL: https://auth.openboxes.cloud/realms/openboxes-cloud/broker/saml/endpoint

Attribute Mapping

SAML Attribute Maps To Required
email or NameID User email Yes
firstName / givenName First name Yes
lastName / surname Last name Yes
groups Role assignment Optional

Testing Your SSO Configuration

After setup is complete:

  1. Open a private/incognito browser window.
  2. Navigate to your OpenBoxes instance URL.
  3. You should see your IdP's login page (or a button to select it).
  4. Log in with a test account.
  5. Verify you land on the OpenBoxes dashboard with the correct role.

Tip: Always test with a non-admin account first. If role mapping is misconfigured, you do not want to accidentally lock out admin access.

Troubleshooting

Symptom Likely Cause Fix
Redirect loop after login Incorrect redirect URI in IdP Verify the redirect URI matches exactly, including trailing slashes
User authenticated but "access denied" Missing role mapping or user not assigned Check IdP group assignments and Keycloak role mappings
"Invalid signature" error Certificate mismatch Re-export the IdP signing certificate and provide it to the Lift team
Users prompted for password after SSO Keycloak session timeout Adjust session timeout settings (contact support)
New users not appearing in OpenBoxes Auto-provisioning disabled Contact support to enable just-in-time user provisioning

Security Considerations

  • All SSO communication happens over TLS (HTTPS).
  • Keycloak validates all tokens and assertions cryptographically.
  • User sessions have configurable idle and absolute timeouts.
  • Disabling a user in your IdP immediately prevents new logins. Existing OpenBoxes sessions expire based on timeout settings.