Skip to content

Add private key jwt auth #1241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
julien-nc wants to merge 23 commits into
base: main
Choose a base branch
from
Draft

Add private key jwt auth #1241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
9cf10c2
gen ssl key pair and convert the public key to JWK
julien-nc Oct 1, 2025
e99a79e
store pem priv key in appconfig, gen JWK from public ssl key, test cr…
julien-nc Oct 9, 2025
533f5eb
use EC signature key with P-384 curve
julien-nc Oct 28, 2025
9f18e30
generate/store/refresh encryption key
julien-nc Oct 29, 2025
99539a2
add lint-eslint action
julien-nc Oct 29, 2025
7b0d1f3
add new boolean setting to enable private key jwt auth
julien-nc Oct 29, 2025
24ea405
implement private jwt login flow by passing the client assertion to t…
julien-nc Oct 29, 2025
e14cf8f
adjust README and settings UI
julien-nc Oct 29, 2025
e720bc6
increase key lifetime to one hour, add comments on when/why we refresh
julien-nc Nov 3, 2025
131388a
implement small signature key tests
julien-nc Nov 4, 2025
0f69435
implement small encryption key tests
julien-nc Nov 4, 2025
06c2f0f
implement JWE encryption + decryption with algos working with singpass
julien-nc Nov 6, 2025
643dd5f
implement JWE tests
julien-nc Nov 6, 2025
a718c6a
polish
julien-nc Nov 6, 2025
bac451a
tests
julien-nc Nov 19, 2025
d353179
last part: detect if a JWT is in a JWE on login
julien-nc Nov 24, 2025
4d5a8ce
make it possible to force-enable PKCE
julien-nc Nov 26, 2025
e9f2a84
add error description in 403 template, use it in code controller method
julien-nc Nov 26, 2025
603d46c
add regexp mechanism to parse user IDs from tokens
julien-nc Nov 27, 2025
394ed41
make debug endpoints private
julien-nc Dec 22, 2025
730caac
handle errors when parsing JWT header at the end of the code flow
julien-nc Dec 22, 2025
3521cba
include leading and trailing / in the userId regexp
julien-nc Dec 22, 2025
5db9242
implement encryption key rotation for JWE decryption
julien-nc Dec 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions .github/workflows/lint-eslint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# This workflow is provided via the organization template repository
#
# https://github.com/nextcloud/.github
# https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization
#
# SPDX-FileCopyrightText: 2021-2024 Nextcloud GmbH and Nextcloud contributors
# SPDX-License-Identifier: MIT

name: Lint eslint

on: pull_request

permissions:
contents: read

concurrency:
group: lint-eslint-${{ github.head_ref || github.run_id }}
cancel-in-progress: true

jobs:
changes:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read

outputs:
src: ${{ steps.changes.outputs.src}}

steps:
- uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
id: changes
continue-on-error: true
with:
filters: |
src:
- '.github/workflows/**'
- 'src/**'
- 'appinfo/info.xml'
- 'package.json'
- 'package-lock.json'
- 'tsconfig.json'
- '.eslintrc.*'
- '.eslintignore'
- '**.js'
- '**.ts'
- '**.vue'

lint:
runs-on: ubuntu-latest

needs: changes
if: needs.changes.outputs.src != 'false'

name: NPM lint

steps:
- name: Checkout
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
with:
persist-credentials: false

- name: Read package.json node and npm engines version
uses: skjnldsv/read-package-engines-version-actions@06d6baf7d8f41934ab630e97d9e6c0bc9c9ac5e4 # v3
id: versions
with:
fallbackNode: '^20'
fallbackNpm: '^10'

- name: Set up node ${{ steps.versions.outputs.nodeVersion }}
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
with:
node-version: ${{ steps.versions.outputs.nodeVersion }}

- name: Set up npm ${{ steps.versions.outputs.npmVersion }}
run: npm i -g 'npm@${{ steps.versions.outputs.npmVersion }}'

- name: Install dependencies
env:
CYPRESS_INSTALL_BINARY: 0
PUPPETEER_SKIP_DOWNLOAD: true
run: npm ci

- name: Lint
run: npm run lint

summary:
permissions:
contents: none
runs-on: ubuntu-latest
needs: [changes, lint]

if: always()

# This is the summary, we just avoid to rename it so that branch protection rules still match
name: eslint

steps:
- name: Summary status
run: if ${{ needs.changes.outputs.src != 'false' && needs.lint.result != 'success' }}; then exit 1; fi
47 changes: 47 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,28 @@ The OpenID Connect backend will ensure that user ids are unique even when multip
id to ensure that a user cannot identify for the same Nextcloud account through different providers.
Therefore, a hash of the provider id and the user id is used. This behaviour can be turned off in the provider options.

### Parsing user IDs from claims

If your ID tokens do not contain the user ID directly in an attribute/claim,
you can configure user_oidc to apply a regular expression to extract the user ID from the claim.

```php
'user_oidc' => [
'user_id_regexp' => '/u=([^,]+)/'
]
```

This regular expression may or may not contain parenthesis. If it does, only the selected block will be extracted.
Examples:

* `'/[a-zA-Z]+/'`
* `'123-abc-123'` will give `'abc'`
* `'123-abc-345-def'` will give `'abc'`
* `'/u=([^,]+)/'`
* `'u=123'` will give `'123'`
* `'anything,u=123,anything'` will give `'123'`
* `'anything,u=123,anything,u=345'` will give `'123'`

## Commandline settings
The app could also be configured by commandline.

Expand Down Expand Up @@ -202,6 +224,22 @@ parameter to the login URL.
sudo -u www-data php var/www/nextcloud/occ config:app:set --type=string --value=0 user_oidc allow_multiple_user_backends
```

### Private key JWT authentication

This app supports private key JWT authentication.
See the `private_key_jwt` authentication method in https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication
This can be enabled for each provider individually in their settings
(in Nextcloud's admin settings or with the `occ user_oidc:provider` command`).

If you enable that for a provider, you must configure the client accordingly on the IdP side.
In the IdP client settings, you should be able to make it accept a signed JWT and set the JWKS URL.

The JWKS URL you should set in your IdP's client settings is `https://<your-nextcloud-url>/index.php/apps/user_oidc/jwks`.
The exact URL is displayed in the user_oidc admin settings.

In Keycloak, you can set the JWKS URL in the "Keys" tab of the client settings. Then you can choose "Signed Jwt"
as the "Client Authenticator" in the "Credentials" tab.

### PKCE

This app supports PKCE (Proof Key for Code Exchange).
Expand All @@ -215,6 +253,15 @@ You can also manually disable it in `config.php`:
],
```

You can also force the use of PKCE with:
``` php
'user_oidc' => [
'use_pkce' => 'force',
],
```
This will make user_oidc use PKCE even if the `code_challenge_methods_supported` value of the provider's discovery endpoint
is not defined or does not contain `S256`.

### Single logout

Single logout is enabled by default. When logging out of Nextcloud,
Expand Down
1 change: 1 addition & 0 deletions appinfo/info.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
<bugs>https://github.com/nextcloud/user_oidc/issues</bugs>
<repository>https://github.com/nextcloud/user_oidc</repository>
<dependencies>
<php min-version="8.2"/>
<nextcloud min-version="29" max-version="34"/>
</dependencies>
<settings>
Expand Down
3 changes: 3 additions & 0 deletions appinfo/routes.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@

['name' => 'api#createUser', 'url' => '/user', 'verb' => 'POST'],
['name' => 'api#deleteUser', 'url' => '/user/{userId}', 'verb' => 'DELETE'],
['name' => 'api#getJwks', 'url' => '/jwks', 'verb' => 'GET'],
['name' => 'api#debugJwk', 'url' => '/debug-jwk', 'verb' => 'GET'],
['name' => 'api#debugJwe', 'url' => '/debug-jwe', 'verb' => 'GET'],

['name' => 'id4me#showLogin', 'url' => '/id4me', 'verb' => 'GET'],
['name' => 'id4me#login', 'url' => '/id4me', 'verb' => 'POST'],
Expand Down
4 changes: 3 additions & 1 deletion composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,9 @@
"require": {
"id4me/id4me-rp": "^1.2",
"firebase/php-jwt": "^7",
"bamarni/composer-bin-plugin": "^1.4"
"bamarni/composer-bin-plugin": "^1.4",
"web-token/jwt-library": "^4.1",
"spomky-labs/aes-key-wrap": "^7.0"
},
"require-dev": {
"nextcloud/coding-standard": "^1.0.0",
Expand Down
Loading
Loading