Features

One sign-in flow for your apps

Configure sign-in once in Shellui. The shell manages login, session renewal, and the return to the requested page. Your embedded apps receive the signed-in account through the software development kit (SDK). Choose identity-service, or connect an existing Supabase Auth project.

How sign-in works

With identity-service, you sign in with OAuth 2.0, OpenID Connect, Security Assertion Markup Language (SAML) 2.0, or a magic link. An embedded app calls shellui.login() to start the flow in the main browser window. After sign-in and account confirmation, identity-service returns the session to the shell.

If you do not enable an OAuth method, the login page sends a magic link. It shows "Check your email" and waits 60s before another send. Sign-in mail can go through email-service, on a queue that bulk mail does not share.

Flow

Follow sign-in from your app to the account provider and back. identity-service confirms the account and company access before returning a session to Shellui.

Loading authentication diagram…

Point at a box, or tab to it, to highlight what it talks to. Arrow keys pan, + and - zoom, 0 fits the view.

Exchange in this view

  1. Your app → the shell Start sign-in in the main browser window
  2. the shell → identity-service Request sign-in for the configured company
  3. identity-service → Provider Redirect to the selected account provider
  4. Provider → identity-service Verify the account, then ask for confirmation
  5. identity-service → the shell Return the session to the shell login callback
  6. the shell → Your app Share account details and an access token through the SDK

Related details: The diagram shows the identity-service sign-in flow; Company access rules apply before identity-service issues a session.

15 OAuth providers

You can turn on 15 OAuth 2.0 and OpenID Connect providers. Company owners add each one from the catalog in Administration. Register the identity-service callback at the provider, not your shell's login URL.

Social and developer accounts

You sign in with an account you already have at one of these providers:

  • Apple
  • GitHub
  • GitLab
  • Google
  • Line
  • LinkedIn
  • Microsoft
  • Reddit
  • Shopify
  • Slack
  • Twitch
  • … and more to come

Company identity providers

These providers belong to the company, such as its Okta org or Keycloak realm. identity-service does not link these sign-ins to an existing account by email. The OpenID Connect entry accepts any standards-compliant issuer. Choose from these providers:

  • Auth0
  • Keycloak
  • Okta
  • OpenID Connect

Enterprise sign-in

Workforce sign-in can use SAML single sign-on (SSO) and System for Cross-domain Identity Management (SCIM). You configure both per company, alongside the OAuth providers above.

SAML 2.0 single sign-on

A company can register several SAML identity providers. Each one has metadata, a callback, login, and optional logout at /api/v1/saml/your_organization_slug/.

SCIM provisioning

Company owners create a SCIM token in Administration, see the secret once, and can revoke it. Your identity provider uses that token to provision and deprovision members of the company.

Choose an authentication backend

The identity-service backend checks who you are and whether you can access a company. A company groups the accounts and access rules for your product or organization. Use it for the company access features below, or choose Supabase Auth for an existing Supabase project.

OAuth providers

Connect any of the 15 providers, including Okta, Auth0, Keycloak, and OpenID Connect. Company owners store the credentials on identity-service.

Signed session tokens

identity-service issues JSON Web Tokens (JWTs) for access and session renewal. In production, it signs tokens with an RSA key and publishes a JSON Web Key Set (JWKS). Your services verify tokens with that key set.

Company access rules

Choose open registration, approved email domains, or owner approval. Access applies per company, so the same account can have different memberships.

Approved return addresses

Register the provider callback on identity-service and approve the addresses your shell can return to after sign-in. The authentication guide covers both settings.

Account administration

Staff and company owners manage members, invitations, groups, and provider connections in the administration panel.

Supabase Auth

If you already use Supabase, connect it as your authentication backend. The sign-in methods you get depend on that project's settings.

Connect a backend and guard routes

Connect your authentication backend and mark navigation items with requiresAuth. Shellui asks signed-out visitors to sign in before loading those apps, then returns them to the requested page.

1. Connect a backend

Set backend in shellui.config.json and enable the login methods you want on the page.

2. Protect routes

Set requiresAuth on the navigation items that need a session. Your backend must also check authentication and permissions for its data.

3. Sign in from your app

From an embedded app, call init from @shellui/sdk first, then shellui.login().

shellui.config.json
{
  "backend": {
    "type": "shellui",
    "url": "http://localhost:8000",
    "companyId": 1,
    "login": {
      "methods": ["oauth"],
      "oauthProviders": ["github", "google"]
    }
  },
  "navigation": [
    {
      "label": "Billing",
      "path": "billing",
      "url": "https://app.example.com/billing",
      "requiresAuth": true
    }
  ]
}

Choose who can join

A successful provider login confirms an account's identity. Your company access policy decides whether that account can enter your product. Choose a policy in the administration panel's Organization settings.

Public

Anyone who signs in can join with access enabled. Use this mode when registration is open to everyone.

Approved email domains

Accounts with an approved email domain join with access enabled. Other accounts wait for approval, and company owners receive a notification.

Invitation only

New accounts wait for a staff member or company owner to enable their membership. They cannot receive a session for that company while approval is pending.

Email invitations

Staff and company owners can invite someone by email, then list, revoke, or delete that invitation. Revoking it blocks sign-in for that address until you send a new invitation. identity-service can email the invitation itself, or a webhook rule can take that send over.

Manage your own account

In Settings, under your user account, you can edit your display name and delete your account. Deletion removes you from the current company. Shellui deletes the account when no company link remains. You cannot remove a company's last owner.

Staff and company owners still manage groups and personal access tokens in Administration. OAuth and SAML sign-in do not overwrite a name you already set.

Keep an event log

identity-service stores catalog events and sign-ins in one event log. Each company sets data_retention_days, and a scheduled job deletes older rows. Administration lists the log for identity, storage, and hosting, and it warns when stored events are past that period.

Keep sign-in details private

A magic-link webhook never includes the sign-in link or the token. identity-service always sends that email itself, and only to the address that requested it. Access logs record the path without the query string, so tokens and codes stay out of the log.

Staff and superuser accounts do not get a magic link. They receive a short notice to sign in with their usual method.

A company metrics response includes only that company's series. Platform-wide series stay on the staff metrics endpoint. Webhook rules, delivery logs, and the event log are on Administration.

Next, see how Administration manages members, email, webhooks, and company access.