👤 Admin: Users, Roles & SSO

Overview

The Users, Roles & SSO area gives workspace admins full control over who can access Oryn and what they can do. From here you can create and manage user accounts, assign realm roles, organise teams into groups, and pull identities in bulk from an LDAP or Active Directory provider. All identity operations are backed by Keycloak, so every change is durable and immediately reflected across the workspace.

How it works

Oryn's backend exposes identity management through two API controllers — IdentityController (user, role, and LDAP endpoints at /api/v1/identity) and OrganisationsController (org lifecycle at /api/v1/organisations) — both of which delegate to a KeycloakAdminClient. The client authenticates to Keycloak's Admin REST API using the configured admin credentials, caches the resulting bearer token until it nears expiry, and then issues signed requests against the configured realm. Every endpoint first checks the caller's X-Oryn-Admin-Role header; only requests carrying the owner, security, or org-admin role value are allowed through. Tenant-scoped requests can also be validated by decoding an org_id claim from the caller's JWT, ensuring users see only their own organisation's data unless they hold an admin role.

What you can do

How to use it

1. Confirm you hold an admin role
   Every identity and organisation endpoint checks the X-Oryn-Admin-Role request header. Your token must carry the value owner, security, or org-admin. If you receive a 401 workspace-admin-required error, contact whoever issued your credentials to have the correct role assigned.
2. List existing users
   Send GET /api/v1/identity/users with your bearer token and the X-Oryn-Admin-Role header. You will receive an array of user objects — each with an id, username, email, firstName, lastName, and enabled flag — up to a maximum of 200 entries.
3. Create a new user
   POST /api/v1/identity/users with a JSON body containing email, firstName, lastName, and optionally tempPassword. If tempPassword is provided, Keycloak marks it as temporary so the user is forced to set their own password at first login. On success you receive the new user's Keycloak UUID.
4. Assign a role to the user
   POST /api/v1/identity/users/{userId}/roles/{roleName} using the UUID returned in the previous step and the exact Keycloak realm role name you want to grant. The backend fetches the role definition from Keycloak and applies it as a realm role mapping in one call.
5. Organise users into groups
   Create a group via POST /api/v1/identity/groups (name in the body) to get a group ID. Then add members with PUT /api/v1/identity/users/{userId}/groups/{groupId}. Groups are logical containers; access policies based on groups are configured in Keycloak directly.
6. Sync from LDAP / Active Directory
   If you have an LDAP user-storage provider configured in Keycloak, trigger a full sync with POST /api/v1/identity/ldap/{providerId}/sync. The response body contains a synced count representing the total accounts added or updated in this run.
7. Create an organisation
   POST /api/v1/organisations with a JSON body containing name, slug, and an optional billingEmail. Only callers with an admin role can create organisations; the new record is immediately persisted and returned with a generated UUID.

Example

Admin notes

Related