Single Sign-On and Provisioning

Let your users sign in to Resourcecloud with your identity provider: through OpenID Connect (Authorization Code Flow with PKCE) for Microsoft Entra ID, Keycloak, Okta, Google Workspace and others — or through SAML 2.0 for ADFS, Keycloak in SAML mode and older corporate IdPs. And have the identity provider create, change and deactivate the accounts — and place people in teams — automatically, through SCIM.

Overview

Single sign-on is configured by an RC Admin in RC Settings. Once it is switched on, the login page shows a sign-on button below the password form. Password login stays available next to it, so a wrong setting can never lock you out.

Separately from signing in, automatic provisioning (SCIM) lets the identity provider manage the accounts themselves: create, change, deactivate (never delete), and assign to teams through groups.

Both can be configured and switched on side by side; the login page then shows one button each. Which account a person is, and signing it in, works the same way for both — see How accounts are matched.

What happens when a user clicks the button of an OpenID Connect provider (the SAML flow is described further down):

1. Resourcecloud sends the browser to your provider. The request carries a one-time state, a nonce and a PKCE challenge (S256) that only this browser session can answer.
2. The user signs in at the provider — with whatever it requires: password, MFA, conditional access.
3. The provider sends the browser back to /oidc_callback.php with a short-lived authorization code.
4. Resourcecloud exchanges the code for an ID token, directly with the provider (server to server, with the PKCE verifier and the client secret), and checks the token's signature and claims.
5. Resourcecloud finds the user's account — or, if you allowed it, creates one — and signs the user in. If the account uses a passkey as second factor, the passkey step still follows.

Before you start

OpenID Connect · Quick start

1. Open RC Settings → External Services and find the panel Single Sign-On (OpenID Connect). Copy the redirect URI it shows, for example https://rc.example.com/oidc_callback.php.
2. At your provider, register Resourcecloud as an application (a web / confidential client) with exactly that redirect URI. Note the client ID, create a client secret, and note the provider's issuer URL. Entra ID is walked through below.
3. Enter issuer, client ID and client secret in the panel. Check the claim mapping and choose how existing accounts are found.
4. Switch Enable Single Sign-On on and press Submit. Resourcecloud asks the provider for its configuration first and refuses to save if the issuer does not answer — the message names the problem.
5. Open the login page in a private window. The sign-on button is there. Sign in with a test user.
6. Check the result: you should land on your usual start page. The first sign-on of an account links it to the identity at the provider (see How accounts are matched).

OpenID Connect · Microsoft Entra ID

These steps use the Microsoft Entra admin center (entra.microsoft.com). Menu names can shift slightly between releases.

1 · Register the application

1. Go to Entra ID → App registrations → New registration.
2. Name: for example Resourcecloud.
   Supported account types: Accounts in this organizational directory only (single tenant).
3. Redirect URI: platform Web, and the URI from the Resourcecloud panel. Press Register.
4. On the Overview page, copy the Application (client) ID and the Directory (tenant) ID.
5. Open Certificates & secrets → Client secrets → New client secret. Choose an expiry and press Add. Copy the Value right away — not the Secret ID. Entra shows the value only once.

2 · Claims in the ID token

An Entra ID token contains sub, name and preferred_username (the user principal name, such as [email protected]) by default. First and last name and the e-mail address are optional claims.

1. Open Token configuration → Add optional claim, choose token type ID.
2. Tick email, given_name and family_name and press Add. When Entra offers to add the Microsoft Graph email permission, accept.

Resourcecloud also asks the provider's userinfo endpoint for a claim that is missing from the token, so the match usually works even without this step — but putting the claims into the token is the dependable way.

3 · Decide who may sign in

By default every user of your tenant can sign in to a new application. To limit it, open Entra ID → Enterprise applications → Resourcecloud → Properties, set Assignment required? to Yes, and assign the users or groups under Users and groups. Everybody else is stopped by Entra before Resourcecloud sees them.

If your tenant does not allow users to consent to applications, an administrator grants consent once under API permissions → Grant admin consent. The permissions needed are the delegated Microsoft Graph permissions openid, profile and email.

4 · Settings in Resourcecloud

Switch the feature on, press Submit, and continue with step 5 of the Quick start.

OpenID Connect · Other providers

Any provider that publishes an OpenID Connect discovery document at <issuer>/.well-known/openid-configuration and signs ID tokens with RS256/384/512, PS256/384/512 or ES256/384/512 can be used. Register a confidential web client with the redirect URI from the panel and the authorization code flow. If the provider lets you choose, require PKCE with S256.

OpenID Connect · Settings reference

All fields are in RC Settings → External Services → Single Sign-On (OpenID Connect).

OpenID Connect · What is verified

The sign-on only works if all of these hold; otherwise the user is returned to the login page with a short reason.

• The answer belongs to this login. The callback must present the state this very browser session was given, within 10 minutes, and only once — a replayed or foreign callback is refused.
• PKCE (S256) binds the code to the browser session that started the login; a stolen code is useless without the verifier.
• The ID token is signed by the provider. The signature is checked against the keys published at the provider's jwks_uri. Only RS*, PS* and ES* algorithms are accepted; none and the HS* algorithms are rejected. A rotated signing key is picked up automatically.
• The claims fit. Issuer equals the configured issuer, audience contains this client ID, azp (when present) is this client, the token has not expired, and its nonce is the one of this login.
• The discovery document is about the issuer asked for. All provider URLs must be https. (For a test provider on plain http, the server environment variable rc_sso_allow_http=1 (the older name rc_oidc_allow_http=1 still works) permits it; never set it in production.)
• Userinfo is only trusted for the same person — its sub must equal the token's.

SAML 2.0 · How it works

For identity providers that do not speak OpenID Connect — ADFS, Keycloak in SAML mode, Shibboleth and older corporate IdPs. Resourcecloud acts as the service provider (SP) and takes the signed assertion your identity provider (IdP) issues.

1. Resourcecloud sends the browser to the IdP with an AuthnRequest (HTTP-Redirect binding). It remembers that request, so only an answer to it will be accepted.
2. The user signs in at the IdP — password, MFA, whatever the IdP requires.
3. The IdP posts its signed answer to the assertion consumer service, /saml_acs.php (HTTP-POST binding).
4. Resourcecloud checks the answer: signature, issuer, audience, destination, recipient, the request it answers, and its validity window — see What is verified.
5. The browser is sent on to /saml_complete, which hands the result only to the browser that started the login, finds or creates the account and signs it in. A passkey as second factor is still asked for.

SAML 2.0 · Quick start

1. Open RC Settings → External Services and find the panel Single Sign-On (SAML). It shows three values for the IdP: the Entity ID, the Assertion Consumer Service URL and the Metadata URL (https://rc.example.com/saml_metadata).
2. At the IdP, register Resourcecloud as a relying party / client. The easy way is to let the IdP import the metadata URL; otherwise enter Entity ID and ACS URL by hand. Make sure the IdP
   • signs the assertion or the response (either is fine; the assertion is the stronger choice) with SHA-256 or better — SHA-1 is refused;
   • sends a persistent NameID, and the attributes you want to map (e-mail, names);
   • does not require signed requests or encrypt the assertion — Resourcecloud does neither (see Limitations).
3. Back in the panel, paste the IdP's metadata URL — or its metadata XML — into Import IdP Metadata and press Submit. Entity ID, single sign-on URL and signing certificate(s) are filled in from it. (You can also type them in.)
4. Check the attribute mapping: the names must equal what the IdP sends. Typical names are listed below.
5. Choose how existing accounts are found and whether accounts are created, switch Enable SAML Single Sign-On on and press Submit.
6. Open the login page in a private window and sign in with a test user — see the warning in the OpenID Connect quick start: keep your RC Admin session open in the other window.

SAML 2.0 · Keycloak

This is the setup the automated interoperability test builds against a real Keycloak (26.x) — it is the tested path. Menu names are those of the Keycloak admin console.

1. Select your realm, then Clients → Import client. Upload the Resourcecloud SP metadata (save https://rc.example.com/saml_metadata as a file). Keycloak fills in Client ID (= the Entity ID), the ACS URL and the redirect URI. Press Save.
2. Settings → Signature and Encryption: Sign assertions on (recommended) — Sign documents may stay on as well. Signature algorithm RSA_SHA256.
3. Keys: set Client signature required to Off. This one matters: Keycloak's default expects signed requests, Resourcecloud sends unsigned ones, and Keycloak then answers with an error page instead of a login form.
4. Settings → Name ID format: username or persistent. Leave Force name ID format off.
5. Client scopes → <client>-dedicated → Add mapper → By configuration → User Property, once for each of:

   Name	User Property	SAML Attribute Name	Name Format
   email	email	email	Basic
   firstName	firstName	firstName	Basic
   lastName	lastName	lastName	Basic
   username	username	username	Basic

6. In Resourcecloud, import the IdP metadata from https://<keycloak>/realms/<realm>/protocol/saml/descriptor. The attribute names in the panel (username, email, firstName, lastName) already match the mappers above.

SAML 2.0 · ADFS

1. AD FS Management → Relying Party Trusts → Add Relying Party Trust → Claims aware → Start. Choose Import data about the relying party published online or on a local network and enter the Resourcecloud metadata URL — or Import from a file with the saved XML. (Entering the data by hand works too: enable SAML 2.0 WebSSO, ACS URL as the URL, the Entity ID as the identifier, and skip the certificate.)
2. Pick an access control policy that fits (for example Permit everyone) and finish. Leave Configure claims issuance policy ticked.
3. Edit Claim Issuance Policy → Add Rule → Send LDAP Attributes as Claims. Attribute store Active Directory, mapping:

   LDAP attribute	Outgoing claim type
   E-Mail-Addresses	E-Mail Address
   Given-Name	Given Name
   Surname	Surname
   User-Principal-Name	UPN

4. Add Rule → Transform an Incoming Claim: incoming claim type UPN (or E-Mail Address), outgoing claim type Name ID, outgoing name ID format Persistent Identifier, pass through all claim values. Not Transient — a transient NameID is different at every sign-on and is refused.
5. Open the trust's Properties. Advanced: secure hash algorithm SHA-256. Encryption: no certificate (Resourcecloud cannot decrypt). Signature: nothing needed. ADFS signs the assertion by default.
6. In Resourcecloud, import https://<adfs>/FederationMetadata/2007-06/FederationMetadata.xml into Import IdP Metadata. This fills in the entity ID (http://<adfs>/adfs/services/trust — note: http), the single sign-on URL (https://<adfs>/adfs/ls/) and the token-signing certificate.
7. Set the attribute names to ADFS's claim types (see the table below).

SAML 2.0 · Settings reference

All fields are in RC Settings → External Services → Single Sign-On (SAML). The panel's own lines, Entity ID, ACS URL and Metadata URL, are what you give the IdP.

SAML 2.0 · Attribute names

The names must match what the IdP puts into the assertion exactly (upper and lower case count). With ADFS and Entra ID these are long claim-type URIs.

SAML 2.0 · What is verified

The sign-on only works if all of these hold; otherwise the user is returned to the login page with a short reason.

• The answer is signed by the IdP. The XML signature over the Response or the Assertion must verify against one of the configured certificates. Unsigned answers, answers signed with another key and answers altered after signing are refused. Exactly one assertion may be present, which defeats signature-wrapping attacks.
• No SHA-1. A signature or digest using SHA-1 anywhere in the answer is refused.
• The content fits. Issuer equals the IdP Entity ID, Audience our Entity ID, Destination and Recipient our ACS URL exactly, the status is Success, and the answer is within its NotBefore/NotOnOrAfter window (clocks may differ by up to 3 minutes).
• It answers our request. InResponseTo must be the AuthnRequest Resourcecloud sent. Unsolicited (IdP-initiated) answers are refused. A login can be answered once, within 10 minutes; a repeated answer is refused.
• It is for this browser. The IdP's answer is a cross-site POST, which the browser sends without the session cookie. Resourcecloud therefore keeps the pending login on the server, and the redirect that follows (which does carry the cookie) hands the result only to the session that started the login. Without that, anybody could post their own valid answer from a victim's browser and log the victim in as the attacker.
• The person has a stable id. A transient NameID is refused unless an attribute is named as Stable Person ID.
• The document is well-formed SAML (validated against the SAML schema; external entities are not loaded). All IdP URLs must be https — for a test IdP on plain http the server environment variable rc_sso_allow_http=1 permits it; never set it in production.

SAML 2.0 · Certificates and rollover

Everything the IdP signs is checked against the certificate(s) stored in the panel, so an IdP certificate that is replaced, or expires, breaks the sign-on until Resourcecloud knows the new one.

1. Before the cutover, get the new certificate: re-import the IdP's metadata (it lists both while they overlap), or paste the new PEM below the old one in IdP Signing Certificate(s). Submit.
2. After the cutover, once the IdP signs with the new certificate, remove the old one from the box.

The panel prints each certificate's expiry date; an expired one is shown in red. Note the dates of your IdP's certificates in a calendar — nothing in Resourcecloud can warn you earlier than you look at the panel.

How accounts are matched

The rules are the same for OpenID Connect and SAML — one implementation serves both; each protocol has its own matching and account-creation settings. At every sign-on Resourcecloud works through these steps and uses the first that applies:

1. The identity is already linked to an account. That account signs in. Its e-mail address, name or login name may have changed at the provider or in Resourcecloud since — the link does not care. A deactivated account is refused.
2. No link yet — look for an account by the chosen method: login name against ad_name, and/or e-mail against the account's mail address. Exactly one active account must match. It is then linked to the identity, and signs in.
3. No account found. If Create the account is on, one is created. Otherwise the user sees “there is no ResourceCloud account for you”.

Refused matches

• An e-mail address the provider marks as not verified (email_verified: false) is never used to find an account.
• If two accounts share the matching e-mail address or login name, the sign-on is refused as ambiguous — fix the duplicate in Resourcecloud.
• An account that is deactivated stays deactivated; single sign-on does not reactivate it.

Accounts created at the first sign-on

An account is not created when the login name or e-mail address is missing or longer than 45 characters, when the default team or the Worker role does not exist, or when the new account would collide with an existing one. Anything beyond Worker in the default team — a different team, extra roles — is assigned by an RC Admin afterwards, as for any other user.

Automatic provisioning (SCIM)

With single sign-on, people can sign in through your identity provider. With SCIM 2.0 the identity provider also creates, changes and deactivates their accounts here and puts them in the right teams — so a new colleague in your directory has an account on day one, and a leaver loses access without anybody remembering to switch it off.

Quick start

1. Open RC Settings → External Services → Automatic Provisioning (SCIM). It shows the Tenant URL, https://rc.example.com/scim/v2.
2. Press Generate new token. The token is shown once, in a window — copy it before you close it. Resourcecloud keeps only a fingerprint of it and cannot show it again.
3. Choose the Team for new users (empty: the Default Support Team), switch Accept provisioning requests on and press Save. SCIM cannot be switched on before a token exists.
4. At the identity provider, enter the Tenant URL and the token — for Entra ID see below — and start provisioning.
5. When the IdP has sent its groups, they appear in the table Groups in the same panel. Choose for each the team its members belong in and/or a secondary role they get, and press Save. The members are placed at once.

Microsoft Entra ID

1. In the Entra admin center: Enterprise applications → New application → Create your own application, name it (for example Resourcecloud provisioning), choose Integrate any other application you don't find in the gallery (Non-gallery). (You can also use the application you already created for single sign-on.)
2. Provisioning → Get started. Provisioning Mode: Automatic. Under Admin Credentials enter Tenant URL = the URL from Resourcecloud and Secret Token = the token. Press Test Connection — it must succeed — and Save.
3. Mappings → Provision Microsoft Entra ID Users. These are the attributes Resourcecloud understands; the rest can be removed:

   Entra ID attribute	SCIM attribute	Becomes
   userPrincipalName	userName	login name (ad_name) — required
   Switch([IsSoftDeleted], , "False", "True", "True", "False")	active	active / deactivated
   mail	emails[type eq "work"].value	e-mail address (if empty and the userName looks like one: the userName)
   givenName	name.givenName	first name
   surname	name.familyName	last name
   jobTitle	title	job title
   mobile	phoneNumbers[type eq "mobile"].value	mobile phone
   objectId	externalId	the IdP's own id of the person — change the default mailNickname to objectId, it never changes

4. Mappings → Provision Microsoft Entra ID Groups: displayName → displayName, members → members, objectId → externalId.
5. Settings → Scope: Sync only assigned users and groups. Under Users and groups assign the people and the groups you want pushed. (Entra does not follow nested groups.)
6. Set Provisioning Status to On and save. To try it on one person first, use Provision on demand: pick a user, run it, and look at the result in Resourcecloud. Entra's first cycle can take a while; later ones run roughly every 40 minutes.

What Entra does when somebody leaves: removing the assignment (or disabling the account) makes it send active = False — Resourcecloud deactivates the account. When the user is finally deleted in Entra, after its retention period, Entra sends a delete — Resourcecloud deactivates again; the account stays, inactive. If the same person ever returns, Entra finds the account by its userName and re-enables it instead of creating a second one.

Groups: what they do

A group is only a name the IdP sends. What membership means is your decision, made in the table Groups:

Mapping, changing the mapping and clearing it all take effect immediately for the members already in the group. Prepare a group by name lets you create the mapping before the IdP has sent the group.

What provisioning never touches

• What an administrator did by hand. Provisioning remembers exactly what it handed out. A team membership, a home team or a role that was already there is not recorded as its own and is never removed when the person leaves the group; a home team an admin chose is never moved.
• When a person leaves a group, what the group gave is taken back — and if the group's team was their home team, they are handed to their next group's team, or back to the starting team.
• RC Admin cannot be handed out through a group: the panel does not offer it and the server ignores it even if a mapping says so — otherwise whoever controls a group at the IdP, or holds the token, could make themselves an administrator. Primary roles (Worker, Teamlead …) are not offered either.
• Accounts that hold the RC Admin role are read-only to provisioning: the IdP can read them, but not change, deactivate or delete them, and a group does not place them. A leaked token therefore cannot lock out or rewrite an administrator.
• Customer logins are not part of the directory and are invisible to provisioning.

Operating it

• Seats. A licensed seat is an active, non-customer login. Creating, deactivating and re-enabling accounts through SCIM updates the seat count the same way the user administration does.
• Rotating the token. Generate new token makes the old one stop working at once. Enter the new one at the IdP right away; until you do, provisioning fails with “authentication failed” (the IdP retries). Revoke token switches provisioning off.
• See that it works. The panel shows when the token was made and when it was last used. Each request leaves a line in the application log, SCIM POST /scim/v2/Users -> 201 (never the token or the person's data).
• New accounts have no password anybody knows. They sign in through your identity provider (an admin can still set a password in the user administration, or the person uses Forgot password). Each new account also gets the usual welcome task.
• Switching it off. Untick Accept provisioning requests (or revoke the token); accounts that were created stay as they are. In an emergency: UPDATE global_settings SET scim_enabled = 0 WHERE id = 1;

Troubleshooting provisioning

Entra shows failed operations under Provisioning → Provisioning logs. The status and message there, and the line in Resourcecloud's application log, tell the story:

Limits of provisioning

• One identity provider per instance. Users and groups only: no bulk operations, sorting or ETags; the list endpoints return at most 200 per page.
• A group maps to one team and one secondary role. Roles with wider reach (RC Admin) and primary roles are assigned in the user administration.
• Attributes Resourcecloud has no field for — manager, department, address, the enterprise extension — are accepted and ignored.
• No password is synchronised, and there is no “change password” through SCIM.
• Deleting never deletes: a person who left stays as an inactive account (so their history stays), and so does a person whose account you want gone — remove those in the user administration.
• Entra ID's provisioning service has to reach the Tenant URL over the internet (see above).
• Not verified against a live Entra ID tenant: the automated tests drive the interface exactly as Entra documents its requests (look-up before create, capitalised Replace, active as the text "False", filtered paths, enterprise-extension attributes). Use Provision on demand for a first real run.

Operating it

Password login stays — and is your fallback

Single sign-on adds a way in; it never removes one. Users with a password can still use the form, and so can you. Keep at least one RC Admin account with a password you know, and do not rely on an account that exists only through the provider.

If single sign-on is misconfigured and you cannot even reach the settings page, sign in with the password of an RC Admin. If that is not possible either, switch the feature off in the database:

UPDATE global_settings SET oidc_enabled = 0, saml_enabled = 0 WHERE id = 1;

Releasing the link of an account

When a person gets a new identity at the provider (a new directory, a rebuilt user), the account refuses it with “linked to a different identity”. There is no screen for this yet; an administrator with database access releases the link, and the next sign-on links the account anew:

UPDATE login SET oidc_subject = NULL WHERE ad_name = '<login name>';

Rotating the client secret (OpenID Connect)

Create the new secret at the provider, paste it into the panel and press Submit, then delete the old secret at the provider. The sign-on keeps working throughout.

Changing the issuer or IdP, or moving between protocols

A different issuer — or a different SAML IdP, or moving from OpenID Connect to SAML — means different identities: accounts linked to the old one will not be recognised and fall back to matching by e-mail or login name — and are then refused, because they are still linked to the old identity. Release the links first (UPDATE login SET oidc_subject = NULL) if you move to a new provider.

Caching (OpenID Connect)

The provider's configuration and signing keys are kept for one hour in the server's temporary directory, per issuer. Saving the settings with single sign-on enabled refreshes them at once.

Where to see what went wrong

The login page shows only a short, fixed sentence. The detail goes to the application log, as a line starting with OIDC login failed (<code>): … or SAML login failed (<code>): …. In a Docker installation that is docker logs rescloud-web.

Multi-tenant (SaaS) installations

Each tenant configures its own provider. The redirect URI (OpenID Connect) and the Entity ID, ACS URL and metadata URL (SAML) of a tenant are built from its address, and its client secret or IdP certificates are stored in the tenant's own database. A customer registers their own application at their own provider.

Troubleshooting

Messages on the login page (both protocols)

OpenID Connect: details in the log (code provider)

OpenID Connect: messages at Entra ID

SAML: details in the log

The log line is SAML login failed (<code>): <detail>. The detail of a rejected answer starts with answer rejected: and comes from the XML-signature and SAML checks.

Limitations

• One OpenID Connect provider and one SAML identity provider per instance; both may be switched on side by side.
• Password login cannot be switched off; there is no “single sign-on only” mode.
• Roles and teams are not taken from provider groups or claims; they are assigned in Resourcecloud.
• Name and e-mail are read from the provider only when an account is created; later changes at the provider do not update the account.
• Signing out of Resourcecloud does not sign the user out at the provider (no single logout), so the next click on the button may sign in without a prompt.
• Releasing the link of an account is a database operation.
• For Entra ID (OpenID Connect), only tenant-specific issuers are supported.
• The client secret is stored in the database like the other credentials in the global settings (SMTP password, API keys).

SAML only

• Service-provider-initiated sign-on only; IdP-initiated answers are refused by design. The AuthnRequest goes by HTTP-Redirect, the answer comes by HTTP-POST; there is no artifact binding.
• Resourcecloud holds no key pair of its own: it does not sign AuthnRequests and cannot decrypt assertions. An IdP that requires either (Keycloak: Client signature required; ADFS: an encryption certificate on the trust) must be told not to.
• SHA-1 signatures are refused, and the clocks of IdP and server may differ by 3 minutes at most.
• No single logout: signing out of Resourcecloud does not end the session at the IdP.
• The IdP's signing certificate is stored when the metadata is imported; a rollover at the IdP needs a re-import (the panel shows the expiry dates).
• An account is linked to one identity: the same person cannot use OpenID Connect and SAML identities on one account without releasing the link in between.

Technical reference