Tested Nextcloud compatibility: maintained Nextcloud major releases plus the newest available RC/Beta
Tested PHP compatibility: maintained PHP 8.2+ releases
Use Nextcloud as a SAML 2.0 Identity Provider. People sign in to connected services with their existing Nextcloud account; administrators manage those services in one place.
- Signs SAML Responses and Assertions with RSA-SHA256.
- Supports service-provider initiated sign-in and a user-facing launcher.
- Provides IdP metadata for straightforward onboarding.
- Lets administrators configure a Service Provider’s Entity ID, ACS URL, NameID format, attributes, certificate, and request-signing policy.
- Includes a real browser end-to-end test against Kimai.
Before production use: test every connected service with a normal user account before disabling another login method. This app implements SAML Web Browser SSO; it does not expose Single Logout.
-
Place the
saml_providerapp directory in a configured Nextcloud app directory, commonlycustom_apps/. -
Enable it:
sudo -u www-data php occ app:enable saml_provider
-
Open Administration settings → SAML Provider.
-
Choose Generate certificate. Keep the private key in Nextcloud; share only the public certificate.
-
Add a connected service with its name, Entity ID, and ACS URL.
-
Import the metadata URL in the connected service, or enter the IdP data manually.
-
Start a login from the connected service and confirm the returned user identity.
For each connected service, select the NameID format it requests. The requested format must match the format configured for that service; unsupported or mismatched requests are rejected.
| NameID format | Value sent by Nextcloud | Typical use |
|---|---|---|
| Email address | The user’s configured email address | Services that identify users by email |
| Persistent | An installation-specific, per-user and per-service HMAC value | Privacy-preserving stable identifiers |
| SAML 1.1 unspecified | The Nextcloud username | Services that request the SAML 1.1 unspecified URI |
| SAML 2.0 unspecified | The Nextcloud username | Kimai and services that request the SAML 2.0 unspecified URI |
Use attribute mapping to decide which available user values are included in a response. The built-in values are uid (Nextcloud username), displayName, and mail (email address when configured for the user). Configure the receiving service to consume the attribute names you map.
Replace cloud.example.com with the public Nextcloud host.
| Purpose | URL |
|---|---|
| Metadata | https://cloud.example.com/apps/saml_provider/saml/metadata |
| SSO | https://cloud.example.com/apps/saml_provider/saml/sso |
| User launcher | https://cloud.example.com/apps/saml_provider/ |
| IdP-initiated login | https://cloud.example.com/apps/saml_provider/saml/login/{service-provider-id} |
These screenshots are captured by the Kimai browser end-to-end workflow after it creates a certificate and registers a service through the normal Nextcloud administration interface.
| Nextcloud 33 | Nextcloud 34 |
|---|---|
 |
 |
This example connects Kimai at https://kimai.example.com to Nextcloud at https://cloud.example.com. Complete the Nextcloud steps first, then configure Kimai. Keep a local Kimai administrator account until you have tested SAML login with a normal user.
Open Administration settings → SAML Provider and generate the signing certificate if you have not done so.
Under Connect a new service, enter:
| Nextcloud field | Value for Kimai |
|---|---|
| Name | Kimai |
| Entity ID | https://kimai.example.com/auth/saml/metadata |
| ACS URL | https://kimai.example.com/auth/saml/acs |
After creating the service, open Show/edit details for “Kimai” and set How the user is identified (NameID) to Nextcloud username (urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified). Kimai requests this NameID format in its metadata.
Copy these values from the Nextcloud SAML Provider page:
| Kimai setting | Nextcloud value |
|---|---|
| IdP Entity ID | https://cloud.example.com/apps/saml_provider/saml/metadata |
| IdP SSO URL | https://cloud.example.com/apps/saml_provider/saml/sso |
| IdP certificate | Certificate (single line – for services like Kimai) |
The app sends uid, displayName, and mail when those user-profile values are available. Kimai requires an email mapping, so ensure every user who should use Kimai has an email address in Nextcloud.
Create or update config/packages/local.yaml on the Kimai server. Replace all example hosts and the certificate value. The certificate must be one base64 line without BEGIN CERTIFICATE / END CERTIFICATE markers or line breaks.
kimai:
saml:
provider: nextcloud
activate: true
title: Sign in with Nextcloud
mapping:
- { saml: $mail, kimai: email }
- { saml: $displayName, kimai: alias }
connection:
idp:
entityId: 'https://cloud.example.com/apps/saml_provider/saml/metadata'
singleSignOnService:
url: 'https://cloud.example.com/apps/saml_provider/saml/sso'
binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
x509cert: 'PASTE_THE_SINGLE_LINE_NEXTCLOUD_CERTIFICATE_HERE'
sp:
entityId: 'https://kimai.example.com/auth/saml/metadata'
assertionConsumerService:
url: 'https://kimai.example.com/auth/saml/acs'
binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'
singleLogoutService:
url: 'https://kimai.example.com/auth/saml/logout'
binding: 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect'
baseurl: 'https://kimai.example.com/auth/saml/'
strict: true
security:
authnRequestsSigned: false
wantAssertionsSigned: false
wantMessagesSigned: falseReload Kimai’s production cache after changing local.yaml (for example bin/console cache:clear --env=prod in the Kimai container or installation). If Kimai runs behind a reverse proxy, configure its trusted proxies and forward the original HTTPS protocol, host, and port; otherwise the ACS URL can be detected incorrectly.
- Open
https://kimai.example.com/auth/saml/metadataand confirm that Kimai exposes its metadata. - Start at
https://kimai.example.com/auth/saml/login. - Sign in with a non-administrator Nextcloud user that has an email address.
- Confirm that Kimai opens an authenticated session.
- Only after this succeeds, consider changing Kimai’s local-login policy.
For additional Kimai-specific deployment guidance, see the Kimai SAML documentation.
The user interface is shipped in these ten broadly used Nextcloud languages: English (en), German (de, including de_DE), French (fr), Spanish (es), Italian (it), Portuguese — Brazil (pt_BR), Polish (pl), Russian (ru), Japanese (ja), and Chinese — Simplified (zh_CN). Nextcloud documents all of these locale families in its own multilingual user documentation. The selection is an intentionally practical coverage set; Nextcloud does not publish a global, comparable language-usage ranking for all self-hosted instances.
The application keeps JSON, JavaScript, and PHP catalogs in lockstep. Some explanatory copy is deliberately concise in the additional languages; SAML names, protocol tokens, URLs, and certificate identifiers remain unchanged because they are configuration values, not prose.
- Use HTTPS for Nextcloud and every connected service.
- Keep server clocks synchronized. AuthnRequests may be at most five minutes old.
- Enable Require signed AuthnRequests only after adding the Service Provider’s signing certificate.
- Persistent NameIDs are installation-specific HMAC values; they are stable per user and service without exposing a predictable hash of the user ID.
- HTTP-Redirect AuthnRequests are limited to 1 MiB after decoding and decompression.
- Redirect signatures use the original query string as required by SAML. Reverse proxies must preserve it unchanged.
A scheduled compatibility check discovers maintained PHP and Nextcloud versions. Every fully successful Unit → integration → Kimai E2E chain for the current main commit, including regular pushes and scheduled compatibility checks, is a patch-release candidate.
- The Unit workflow discovers maintained PHP 8.2+ releases and enforces the 80% production-coverage gate.
- The integration workflow discovers maintained Nextcloud majors plus the newest Apache RC/Beta and runs each target with SQLite, MariaDB, and PostgreSQL.
- Kimai E2E runs the full real-browser SAML journey for every discovered Nextcloud target and captures one populated administration screenshot per successful target.
- After a completely green
mainchain, the release workflow confirms that the tested commit is still the currentmaincommit and refreshes the recorded PHP and Nextcloud compatibility metadata. - If
appinfo/info.xmlwas not changed in the tested commit, the workflow increments the patch version. If that file was already changed in the tested commit, it preserves the existing version instead, preventing a second automatic increment. It then refreshes compatibility metadata, signs the runtime-only archive, tags the commit, and creates the GitHub and Nextcloud App Store release.
A release is intentionally not created when the tested commit is no longer current on main, the commit message contains [skip automated release], or the required release secrets are unavailable. The protected release environment must provide:
NEXTCLOUD_SIGNING_PRIVATE_KEYNEXTCLOUD_SIGNING_CERTIFICATENEXTCLOUD_APPSTORE_TOKEN
If any required secret is missing, the release preflight fails before it creates an archive, tag, or GitHub release.
The release archive contains only runtime app files. It never contains test code, CI configuration, build directories, signing keys, or placeholder signatures.
- Languages: the app ships complete catalogs for English, German, French, Spanish, Italian, Brazilian Portuguese, Polish, Russian, Japanese, and Simplified Chinese. Technical SAML values remain untranslated.
- Development dependencies: review Composer dependencies before release; no Composer audit command is currently configured in CI. A reviewed
composer.lockshould be committed when generated in a Composer-capable environment. - Issue reports: include the Nextcloud version, app version, browser/service-provider details, and relevant non-sensitive logs.