Add OAuth2 Client Management in Settings

[KillianCourvoisier]

Summary

Users currently need to create OAuth2 clients via manual curl calls to the /auth/register endpoint.
This is error-prone, hard to discover, and offers no way to review or revoke existing clients.

The proposal is to introduce an "OAuth2 Clients" section inside Twake instance Settings (under "Security & data access") where users can create, list and revoke OAuth2 clients using mechanisms already provided by the stack.

---

Context

This need came from a previous project for a custom N8N node for TwakeDrive. Today, for a user to create an OAuth2 client typically requires:

• Calling the /auth/register endpoint manually.
• Crafting JSON payloads and HTTP headers.
• Reading documentation outside the platform (for example, n8n integration guides).

Problems in practice:

• Users must rely on external documentation.
• Manual JSON and HTTP crafting is error-prone.
• There is no UI to:
  • view existing OAuth2 clients,
  • revoke a client,
  • inspect redirect URIs or other metadata.
• OAuth clients are sensitive security objects that users logically expect to manage like “Connected apps”.

On the stack side:

• Dynamic Client Registration endpoints already exist:
  POST /auth/register, PUT /auth/register/:id, DELETE /auth/register/:id.
• OAuth clients are stored as documents of type io.cozy.oauth.clients.
• Cozy-stack-client exposes OAuthClientsCollection, which uses /settings/clients to list and delete clients.

In short: the backend building blocks already exist, they just are not surfaced in Settings.

---

Proposal

Add a new section in Settings:

Settings → Security & data access → OAuth2 clients

1. UI: Create client

A minimal creation form:

• Client name (required)
• Redirect URI (required)
• Client kind (dropdown ?, any case by default "web")
• Software ID (optional but recommended I suppose ?)

On submit:

• The UI sends a POST to /auth/register using the same fields as manual curl usage.
• The response shows:
  • the generated client_id,
  • and the client_secret if applicable (visible once).
• Provide copy-to-clipboard helpers.

Editing is intentionally out of scope for MVP.
If the redirect URI needs to change, the user deletes and recreates the client.

---

2. UI: List existing clients

Using OAuthClientsCollection.all() (backed by /settings/clients), the UI displays:

• Client name
• Redirect URI(s)
• Software ID
• Client kind
• Creation or update timestamp (whatever is exposed)

A simple table layout is sufficient.

---

3. UI: Revoke client

Each entry includes a Delete / Revoke action:

• Internally calls OAuthClientsCollection.destroy(doc) (DELETE on /settings/clients/:id).
• Tokens associated with the client are invalidated according to stack behavior.
• The entry disappears after confirmation.

---

Technical implementation

Creation:

• Reuse existing Dynamic Client Registration:
  • POST /auth/register
  • Payload includes: client_name, redirect_uris, client_kind, software_id

Listing and deletion:

• Reuse OAuthClientsCollection:
  • GET /settings/clients
  • DELETE /settings/clients/:id

No new backend endpoints are strictly required for MVP in my opinion.

---

Open questions

1. Recommended payload for /auth/register
   Are client_kind and software_id required, optional, or recommended?
   Any fields that should be exposed or hidden in the UI?

2. Secret handling
   Should client_secret be shown only once?
   Should the UI prevent redisplay?
   I vote for a display at creation, but never after a "confirmation" that the user has saved his client_secret, but open to discussion.

3. Revocation semantics
   When a client is deleted, are its refresh tokens always invalidated?
   Any UX messaging the UI should include?

---

Out of scope for MVP

• Editing existing clients
• Multiple redirect URIs
• Scopes management ? For now with the N8N project, we only need access to io.cozy.files, but for other services we may need other permissions
• Anything beyond “create / list / revoke” that comes in mind ?

[Crash--]

Is the goal really to create OAuth clients (meaning each "app" would then need to perform the OAuth dance/flow), or is the goal to provide a token directly for them to use?

[KillianCourvoisier]

First option, the app would need to perform the OAuth dance. Providing a token could be an option, but as I say above, this client generation feature for settings was asked during the N8N custom node for TwakeDrive development. The custom node is using Oauth2 dance to connect to the instance, so I had to give users a curl request in the node doc for them to create a client to get the needed data. So the point is to make this client creation available easily in the instance settings for users

[zatteo]

For points 2. UI: List existing clients and 3. UI: Revoke client, I wonder if the existing device list has already the ability to list and revoke OAuth clients and we just hide some OAuth client. So maybe it could be easily extended to suit your needs.

[KillianCourvoisier]

It could be nice indeed, I'll check that, thank you 👌

[Crash--]

Should client_secret be shown only once?

I think you'll have access only once to this value. Just after the call for creation. After that, you'll never be able to fetch it from the backend.

And yes, as suggested by @zatteo you should use the already existing "Connected Devices" page.

You just need to add a Create button and ask the few informations and do the creation. That's it.

[KillianCourvoisier]

Perfect then, I'll begin this feature tomorrow or next week, depending on how I manage to satisfy you guys in the Imports PR ahah.

Thank you both 🙏

[zatteo]

Maybe it could be all on Connected Devices page and a flag could:

• display the create button
• show all clients instead of the filtered list

Like a "expert mode".

[KillianCourvoisier]

@zatteo as you think its better, I can do that 👍

[Crash--]

@nono @taratatach @shepilov : To be able to create a client from the settings app, we need to add preflight cors request to /auth/register. Is this an issue ? (cf cozy/cozy-stack@master...feat/preflightAuth)

[nono]

cozy/cozy-stack#1610. In short, I don't think there is an issue, but I'm not totally sure about that.

Maybe you can add a new route to register an OAuth2 client that can be only called by the settings app.

[Crash--]

Thanks @nono, I'll do that.