Skip to content

Add client credentials bound to a user's WebID (for scripts, services and agents) - #234

Open
chefboyrdave21 wants to merge 2 commits into
pdsinterop:mainfrom
smilinTux:feat/client-credentials-for-agents
Open

chefboyrdave21 wants to merge 2 commits into
pdsinterop:mainfrom
smilinTux:feat/client-credentials-for-agents

Conversation

@chefboyrdave21

Copy link
Copy Markdown

Builds on #229 (client_secret_basic at the token endpoint); the first commit here is that PR. Review #229 first, or just the last commit.

Problem

A client without a browser (a script, a background service, an AI agent) has no way to get a Solid access token from this server. The discovery document advertises the client_credentials grant, but a token from that grant carries no WebID, so it gives access to nothing. Other servers (CSS, ESS) let a user create client credentials that are bound to their WebID; this is also how the conformance test harness authenticates.

Proposal

Let a signed-in user create client credentials that are bound to their own WebID:

Method Route Purpose
GET /apps/solid/client-credentials list your credentials (no secrets)
POST /apps/solid/client-credentials create (optional name)
DELETE /apps/solid/client-credentials/{clientId} revoke
  • The user signs in with a session or a Nextcloud app password. The routes keep the CSRF check, so API clients send OCS-APIRequest: true.
  • When such a client uses grant_type=client_credentials (client_secret_basic, DPoP), the token endpoint issues the access token and ID token for the bound WebID, after the authorization server has validated the secret.
  • A client from dynamic registration, credentials without the client_credentials grant, or credentials whose user no longer exists get no WebID.
  • docs/client-credentials.md documents the routes and use with @inrupt/solid-client-authn-node.

Happy to change the shape (for example a settings page section instead of, or in addition to, the routes) if you prefer another approach.

Tests

ClientCredentialsControllerTest (create, list only own, revoke own, cannot revoke someone else's) and ServerControllerTest (token bound to the WebID; three unbound cases).

Verification

Nextcloud 35.0.2 (PHP 8.5), behind a TLS-terminating proxy, with @inrupt/solid-client-authn-node 5.0.3:

  • app password, then POST, gives 201 with client_id, client_secret, webid; Session.login({clientId, clientSecret, oidcIssuer, tokenType: "DPoP"}) logs in as that WebID; PUT/GET in the user's private container: 201/200;
  • another user grants that WebID read/write on one resource with universalAccess.setAgentAccess; the client then reads and writes it; it gets 403 on resources it was not granted;
  • wrong secret: 401; without OCS-APIRequest: 412; wrong app password: 401; revoking another user's credentials: 404; revoked credentials: 401;
  • a dynamically registered client using client_credentials gets no WebID and 403 on private data.
  • The Solid conformance test harness authenticates its two test users with these credentials.

🤖 Generated with Claude Code

Lumina and others added 2 commits November 15, 2026 15:10
The discovery document advertises client_secret_basic, but the token
endpoint only looked for client_id in the request body. A confidential
client that authenticates with an HTTP Basic Authorization header (the
default for openid-client, which @inrupt/solid-client-authn-node uses)
therefore got an ID token with "aud": null, which the client rejects, and
its registration was never loaded, so the client_credentials grant always
failed with 401.

Read the client_id from the Basic header (form-urlencoded per RFC 6749
section 2.3.1) when it is not in the body, both for loading the client
registration and for the audience of the issued tokens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A client without a browser (a script, a background service or an AI
agent) has no way to get a Solid access token today. The discovery
document advertises the client_credentials grant, but a token from that
grant carries no WebID, so it gives no access to anything.

Let a signed-in user create client credentials that are bound to their
own WebID:

  GET    /apps/solid/client-credentials             list (no secrets)
  POST   /apps/solid/client-credentials             create
  DELETE /apps/solid/client-credentials/{clientId}  revoke

The user signs in with a session or a Nextcloud app password; the routes
keep the CSRF check, so API clients send OCS-APIRequest: true. When such a
client uses the client_credentials grant (client_secret_basic, DPoP), the
token endpoint issues the access token and ID token for the bound WebID,
after the authorization server has validated the client secret. A client
from dynamic registration, or one whose user no longer exists, still gets
no WebID.

docs/client-credentials.md describes the routes and how to use them with
@inrupt/solid-client-authn-node.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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.

1 participant