Skip to content

Document the API exception for SSO setups that protect the whole site - #1362

Open
ljuergenliemke wants to merge 1 commit into
mainfrom
docs/1339-sso-api-access-apache-exception
Open

Document the API exception for SSO setups that protect the whole site#1362
ljuergenliemke wants to merge 1 commit into
mainfrom
docs/1339-sso-api-access-apache-exception

Conversation

@ljuergenliemke

Copy link
Copy Markdown
Contributor

Fixes #1339

Problem

The SSO guides that place the whole installation behind the web server with <Location /> also cover the JSON-RPC API at /src/jsonrpc.php. An API client cannot follow the redirect to the identity provider, so following these guides silently breaks all API access (the reporter saw Apache answer HTTP 302 instead of the API response).

Change

Adds a second <Location> block plus a warning admonition to the affected guides, in EN and DE:

# Exclude the JSON-RPC API from SSO: an API client cannot follow
# the redirect to the identity provider.
<Location /src/jsonrpc.php>
    AuthType None
    Require all granted
</Location>
Guide EN DE
OpenID: Google
SAML: ADFS
SAML: Azure AD / Entra ID

Scope: why GSSAPI and Kerberos are not changed

Those two guides scope authentication with <Directory> instead of <Location />. Apache merges Directory → Files → Location, and i-doit's own shipped .htaccess contains:

## …except some PHP files in src/:
<Files "jsonrpc.php">
    Require all granted
</Files>

Because Files is merged after Directory, that rule already exempts the API in a <Directory>-based setup, but it is overridden by a <Location /> block, which is merged last. Confirmed by test: a <Directory>-based setup keeps serving the API with no change at all, so adding this block there would document a fix for a problem those setups do not have.

Verification

Tested against i-doit 38 / Apache 2.4.58, using the block exactly as it now appears in the articles (extracted from the file, byte-identical across all three). Basic auth stood in for the identity provider, since the exemption is an Apache-level mechanism and independent of the auth module. 16 checks, all passed:

Finding Result
<Location /> without the block: API refused ✅ reproduces the report
With the documented block: API returns real JSON-RPC
UI stays SSO-protected (401 without login, 200 with)
API not left public: missing apikey rejected ✅ i-doit auth error
API not left public: wrong apikey rejected ✅ i-doit auth error
No path leakage: /src/, /src/index.php, /index.php, /src/jsonrpc.php.bak, /src/classes/, /src/tools/ ✅ all still protected
<Directory> style unaffected without the block ✅ justifies the scope above

Limitation, stated plainly: we have no OIDC or SAML identity provider here, so the genuine 302-to-provider flow was not exercised. What was verified is the exemption mechanism itself, which lives in Apache and behaves the same regardless of which auth module sets AuthType.

Also worth noting: AllowOverride appears inside <Location /> in the existing examples. Apache 2.4.58 accepts it, but it has no effect there (it only applies in <Directory> context), so I did not repeat it in the new block. Existing lines were left untouched.

Possible follow-up (not in this PR)

While testing I noticed that with <Directory>-based auth and AllowOverride All, /index.php was reachable without logging in. That traces to i-doit's .htaccess, which only requires a valid user for index.php when mod_auth_kerb is loaded, whereas the GSSAPI guide uses mod_auth_gssapi. i-doit's own login still stands in front of the data, so this is "SSO not enforced at the web server" rather than open access. I have not investigated it properly and it is out of scope here. Happy to open a separate issue if you want it looked at.

The SSO guides that put the entire installation behind the web server via
<Location /> also cover the JSON-RPC API at /src/jsonrpc.php. An API client
cannot follow the redirect to the identity provider, so enabling SSO as
documented silently breaks all API access.

Add a second <Location /src/jsonrpc.php> block (AuthType None, Require all
granted) plus a warning admonition to the three affected guides in EN and DE:
Google OpenID, ADFS (SAML) and Azure AD/Entra ID (SAML).

Verified against i-doit 38 on Apache 2.4.58 with the block exactly as
documented (Basic auth standing in for the identity provider, since the
exemption is an Apache-level mechanism and module independent):

- without the block, an API POST is refused by the web server; with it, the
  same request returns a normal JSON-RPC response
- the UI stays protected (unauthenticated 401, authenticated 200)
- the API does not become public: missing or wrong apikey still fails with
  i-doit's own authentication error
- no neighbouring path is exposed (/src/, /src/index.php, /index.php,
  /src/jsonrpc.php.bak, /src/classes/, /src/tools/ all stay protected)

The GSSAPI and Kerberos guides are deliberately left unchanged: they scope
auth with <Directory>, and because Apache merges Directory before Files,
i-doit's shipped .htaccess (<Files "jsonrpc.php"> Require all granted)
already exempts the API there. Confirmed by test: that setup keeps working
without any change.

Fixes #1339

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@ljuergenliemke
ljuergenliemke requested a review from a team as a code owner July 31, 2026 15:39
@ljuergenliemke ljuergenliemke self-assigned this Jul 31, 2026
@ljuergenliemke ljuergenliemke linked an issue Jul 31, 2026 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOC BUG] SSO prevents API access

1 participant