Understand the pieces
Imagine you are building a project-management app. People sign in, join a company, and work on that company's projects. These are the pieces that connect the identity service to your product.
Your service configuration
| Term | In your project-management app |
|---|---|
| Tenant | The user directory and sign-in policy for your product |
| Application | An OAuth2 client registration for your web app, mobile app, or backend service |
| Issuer | The trusted identity-service URL that issues credentials |
| Identity provider | An external sign-in connection, such as Google or your configured OIDC provider |
| Administrator | A person with permission to configure your Udibo tenant |
A development application and a production application can share a tenant, but then they share its user directory. Use separate tenants if you need separate test users or different tenant-wide policy.
Your customers
A user is a person in your tenant. An organization groups those users into a customer company or team. One user can belong to several organizations. A consumer app can have users without using organizations at all.
Use the validated identity's subject (sub) as an identity key. If your app
accepts more than one issuer, key the external identity by both issuer and
subject. An email address can change; it is not a durable authorization key.
An organization's Owner, Admin, and Member membership tiers manage the
organization. Your application's roles bundle the permission strings you
define, such as projects:read and projects:archive. Keep those concepts
separate: being an organization admin does not automatically make someone an
administrator of your Udibo tenant.
A login creates more than one session
The browser visits the tenant's sign-in pages. The tenant establishes its identity session.
The browser returns an authorization code to your application's callback.
Your backend exchanges the code for tokens and creates its own application session. The browser carries an HttpOnly session cookie for your app.
An access token authorizes requests to an API. A refresh token lets the backend obtain a new access token. An ID token describes an authentication result; it is not a substitute for an API access token.
Your application's session and the tenant's SSO session have separate lifecycles. Clearing your app's cookie does not necessarily sign the person out of the identity service. Decide which outcome your sign-out button promises, and test that outcome.
Authentication is the first check
Suppose Alice belongs to Acme and Bob belongs to Beacon. Both can sign in. That does not give Bob permission to read an Acme project.
Your backend should establish the caller, find the project's actual organization from trusted application data, and check authority for that organization or resource. A browser-supplied organization ID is a requested target, not proof of membership.
The permissions guide covers three useful questions:
Tenant-wide: may this person use a capability throughout my product?
Organization-specific: may this person act in this named company?
Resource-specific: may this person act on this particular document?
The active organization in a credential answers for one organization. It does not confer authority over all organizations a browser can name. A React guard can hide a button; the backend must still refuse an unauthorized request.
Choose the right source for each answer
| What you need | Read it from |
|---|---|
| Session presentation in the browser | Your BFF's session response |
| The caller of a protected API request | Validated access-token information |
| Profile and email verification | UserInfo with the relevant scopes |
| Current access to a named organization or resource | The permission mechanism described in the public permissions guide |
| Application records and their owners | Your application's database |
A cached session projection is useful for rendering. It can be older than the permissions resolved during token introspection. Do not make a backend access decision from the browser's copy.
Next: Choose a starter, or add organizations to a connected application.
Last verified 2026-09-06.