feat: JWT bearer assertions for client authentication #146

New Issue

AtHeartEngineer · 2025-07-08T08:41:00-04:00

AtHeartEngineer commented

2025-07-08 08:41:00 -04:00

Originally created by @ItalyPaleAle on 5/25/2025

Fixes #361

TLDR

Implements support for authenticating OAuth2 clients using JWT bearer client assertions in lieu of a client secret
Complies with RFC 7523

Goals

Full discussion is in #361, but to recap...

We want to enable confidential clients (OAuth2 applications) to perform a token exchange without having to use a client secret, because client secrets are long-lived shared secrets and are not the best solution for security.

When clients (apps) exchange an auth code for an access token, by invoking the /api/oidc/token endpoint, normally they include a client ID and client secret. With this change, instead of a client secret they can include client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer (this is a constant defined in the RFC) and a client_assertion=... containing a JWT signed by an external identity server, which is issued to the application to identify itself
For example, apps that run on cloud services could use things like Azure managed identities or AWS IAM service roles. Apps that run on Kubernetes can use a (bound) service account token. Or it could be a token issued with SPIRE. (Note: doesn't mean Pocket ID must run on the cloud or on K8s, it's independent from where Pocket ID is hosted)

References

RFC 7523, specifically section 2.2 ("Using JWTs for client authentication"), and additional requirements in section 3
Additional context from IETF draft for Workload Identity Practices
Used the Microsoft Entra ID implementation as reference implementation (docs)

How this works

Users should be able to add one or more federated identities for each app in Pocket ID. For each federated identity they'll need to provide:

The issuer (Required), which is the iss for the external identity service
The subject, which defaults to the client ID for the OAuth client (but can be set to a different value, e.g. could be a SPIFFE ID when using SPIFFE/SPIRE)
The audience for the token, which by default is the URL of the Pocket ID server
The URL of the JWKS, which by default is <iss>/.well-known/jwks.json

Then, OAuth2 apps will be able to present as client_assertion JWTs that are signed by the issuer above, and which have the subject and audience configured as per above.

How you can test this

Credentials:

Issuer: https://alessandrosegala.blob.core.windows.net/
JWKS URI: https://alessandrosegala.blob.core.windows.net/$root/jwks.json

To test it:

Create a new OAuth application in Pocket ID. Use the values above for Issuer and JWKS URI. Use api://PocketIDTokenExchange for audience and 123456abcdef for subject.
Start the OAuth authorization flow (I've used oauth.tools but any other way works) and obtain an access code
When you get the access code, you can use one of the tokens below and curl to exchange it for an auth token:

CODE=your-access-code
CLIENT_ID=your-client-id
REDIRECT_URI=your-redirect-uri
curl -Ss -X POST \
http://localhost:1411/api/oidc/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code&redirect_uri='${REDIRECT_URI}'code&code='${CODE}'&client_id='${CLIENT_ID}'&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion='${CLIENT_ASSERTION}

Use one of these values for CLIENT_ASSERTION:

# Valid token
CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiIxMjM0NTZhYmNkZWYiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vUG9ja2V0SURUb2tlbkV4Y2hhbmdlIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.ZBTPYFxe4X2qHic4t-P09kfgfCf0x9FfMSlH2zc_2dadAQ9rZDKGTekAuSZ9sL7FofrxzElh_tUKAYV0ScpKcnQJY-t7gB1bT6jdevndmTUmBOa8NcFfSSAxMyBxzuD-OAzhQG78JMk_Gf4LJVLwyXL7Ngz_feM7o3zxI0TRPBlurfE500PPwpfhZB90ggEiMtxBLHFws0rbUat98FBOcsKdjqkp9p0NsLuzDtxM2W1nOJ_LXk9rOKPb5naTKHzgajWOV9yg1PSx_vxqkFVH9BV9byimgLc1BKXRxKfm79YrRo3CWmJ-FvcIkpvAkgOdqi6KiZ2KpZSPJjH8sCYKXw

# Fails - invalid subject
CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiJCQUQiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vUG9ja2V0SURUb2tlbkV4Y2hhbmdlIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.RtpSGnJ0w45Epr8p6nRrA0dLe-V69HU3RwRfEvjffApYkM3ln-rkyeVWjzJIZ-qpe4yQG5UtkkOk4mMrb-L0_WRDP25p_bdCu42UTa_B3OpAATkTfWlGI2HWBr4w3ExUkLFK7UXfs0l5A11huEbbSQwqsBuk3rTkeWwlE8pq8RAjZbVTkpezMHBt-L9L-eeDmiX71ZxYFuUnQ557geyhh0guO17OcVaTbDiSKNkkQZQHOZhs2Yy8aVjeJgBoUDAJwlIdRI4O_JhqdlZgk88HHFl47akNom4sLfyFmo8ez3BD89-IINuQnY27LWT9sHiTNi0o3-6bA_bilNgpwHsFXw

# Fails - invalid audience
CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiIxMjM0NTZhYmNkZWYiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vQkFEIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.S3gAzBKH9JPF0bbr2qgI6WI29YCXtipsVTNhIKMlgwzPHIILR3maDM2e8_jQyuayZhpHeGXa7eTrNyVhKBksmfhkM6Js_Vmv-L1Q6Oc0FkTjMJvTWC_H7G6a1O5eo3jlWICVfSk6sHOG8mosCBNA0B3xZVrs5H5MPm5Of9AEIrtAo6VbtRo6fkwCmDxm6fzeTtws3g7WlWrHjQZcGrKbXo44Hzsp6WPwmCF8Xp9GgkRbympshizJSewRQsBnoWE0xQ7KFmTLhvmBTrwiQ-ifWrre1VoqCOjuoGOoMEnxPlVYcHBurdeK5VHsxgm9BwgmxThjrt2KVc2SQ-DvWLkEpw

# Fails - signed by an invalid key
CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiIxMjM0NTZhYmNkZWYiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vUG9ja2V0SURUb2tlbkV4Y2hhbmdlIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.EnrllAAKlOSv_3odLItIQHx28HwbV84RhHY5Hfh95eb8gzvUWYHR_vAuIj91hY5oyEtOn6qM3WQRRdWAWPoOcuxbVSW09TG6MXA6DZo7Pd43_IkWAovH5qen7uIb0wiv_3Vf3dls_YRzuHd5Mo2wdIKVmYJSrg22Qd5x6clcDXhwrfO_5B1H8WLlV-KaiEMBjN-7YFh59Eb4wbHrNaXrFyYWjuD-PZeG1NH9aSFBNeOq0KArjYIvn96mjhlKiE_DT15CK1zPjndikbK_SwAovOgGCV4Jnazm0_XF9AOCuPNEJlKwb0MhhcNcsr3Aelo9_3zxLKbe8DbEgI0I4ZjWYw

*Originally created by @ItalyPaleAle on 5/25/2025* Fixes #361 ## TLDR - Implements support for authenticating OAuth2 clients using JWT bearer client assertions in lieu of a client secret - Complies with [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523) ## Goals Full discussion is in #361, but to recap... We want to enable confidential clients (OAuth2 applications) to perform a token exchange without having to use a client secret, because client secrets are long-lived shared secrets and are not the best solution for security. - When clients (apps) exchange an auth code for an access token, by invoking the `/api/oidc/token` endpoint, normally they include a client ID and client secret. With this change, instead of a client secret they can include `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer` (this is a constant defined in the RFC) and a `client_assertion=...` containing a JWT signed by an **external** identity server, which is issued to the application to identify itself - For example, apps that run on cloud services could use things like Azure managed identities or AWS IAM service roles. Apps that run on Kubernetes can use a (bound) service account token. Or it could be a token issued with SPIRE. (Note: doesn't mean Pocket ID must run on the cloud or on K8s, it's independent from where Pocket ID is hosted) ## References - RFC 7523, specifically [section 2.2](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2) ("Using JWTs for client authentication"), and additional requirements in section 3 - Additional context from [IETF draft for Workload Identity Practices](https://www.ietf.org/archive/id/draft-ietf-wimse-workload-identity-practices-00.html) - Used the Microsoft Entra ID implementation as reference implementation ([docs](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow#request-an-access-token-with-a-certificate-credential)) ## How this works Users should be able to add one or more federated identities for each app in Pocket ID. For each federated identity they'll need to provide: - The issuer (Required), which is the `iss` for the external identity service - The subject, which defaults to the client ID for the OAuth client (but can be set to a different value, e.g. could be a SPIFFE ID when using SPIFFE/SPIRE) - The audience for the token, which by default is the URL of the Pocket ID server - The URL of the JWKS, which by default is `<iss>/.well-known/jwks.json` Then, OAuth2 apps will be able to present as `client_assertion` JWTs that are signed by the issuer above, and which have the subject and audience configured as per above. ## How you can test this Credentials: - Issuer: `https://alessandrosegala.blob.core.windows.net/` - JWKS URI: `https://alessandrosegala.blob.core.windows.net/$root/jwks.json` To test it: 1. Create a new OAuth application in Pocket ID. Use the values above for Issuer and JWKS URI. Use `api://PocketIDTokenExchange` for audience and `123456abcdef` for subject. 2. Start the OAuth authorization flow (I've used [oauth.tools](https://oauth.tools/) but any other way works) and obtain an access code 3. When you get the access code, you can use one of the tokens below and curl to exchange it for an auth token: ```sh CODE=your-access-code CLIENT_ID=your-client-id REDIRECT_URI=your-redirect-uri curl -Ss -X POST \ http://localhost:1411/api/oidc/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code&redirect_uri='${REDIRECT_URI}'code&code='${CODE}'&client_id='${CLIENT_ID}'&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion='${CLIENT_ASSERTION} ``` Use one of these values for `CLIENT_ASSERTION`: ```sh # Valid token CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiIxMjM0NTZhYmNkZWYiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vUG9ja2V0SURUb2tlbkV4Y2hhbmdlIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.ZBTPYFxe4X2qHic4t-P09kfgfCf0x9FfMSlH2zc_2dadAQ9rZDKGTekAuSZ9sL7FofrxzElh_tUKAYV0ScpKcnQJY-t7gB1bT6jdevndmTUmBOa8NcFfSSAxMyBxzuD-OAzhQG78JMk_Gf4LJVLwyXL7Ngz_feM7o3zxI0TRPBlurfE500PPwpfhZB90ggEiMtxBLHFws0rbUat98FBOcsKdjqkp9p0NsLuzDtxM2W1nOJ_LXk9rOKPb5naTKHzgajWOV9yg1PSx_vxqkFVH9BV9byimgLc1BKXRxKfm79YrRo3CWmJ-FvcIkpvAkgOdqi6KiZ2KpZSPJjH8sCYKXw # Fails - invalid subject CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiJCQUQiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vUG9ja2V0SURUb2tlbkV4Y2hhbmdlIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.RtpSGnJ0w45Epr8p6nRrA0dLe-V69HU3RwRfEvjffApYkM3ln-rkyeVWjzJIZ-qpe4yQG5UtkkOk4mMrb-L0_WRDP25p_bdCu42UTa_B3OpAATkTfWlGI2HWBr4w3ExUkLFK7UXfs0l5A11huEbbSQwqsBuk3rTkeWwlE8pq8RAjZbVTkpezMHBt-L9L-eeDmiX71ZxYFuUnQ557geyhh0guO17OcVaTbDiSKNkkQZQHOZhs2Yy8aVjeJgBoUDAJwlIdRI4O_JhqdlZgk88HHFl47akNom4sLfyFmo8ez3BD89-IINuQnY27LWT9sHiTNi0o3-6bA_bilNgpwHsFXw # Fails - invalid audience CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiIxMjM0NTZhYmNkZWYiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vQkFEIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.S3gAzBKH9JPF0bbr2qgI6WI29YCXtipsVTNhIKMlgwzPHIILR3maDM2e8_jQyuayZhpHeGXa7eTrNyVhKBksmfhkM6Js_Vmv-L1Q6Oc0FkTjMJvTWC_H7G6a1O5eo3jlWICVfSk6sHOG8mosCBNA0B3xZVrs5H5MPm5Of9AEIrtAo6VbtRo6fkwCmDxm6fzeTtws3g7WlWrHjQZcGrKbXo44Hzsp6WPwmCF8Xp9GgkRbympshizJSewRQsBnoWE0xQ7KFmTLhvmBTrwiQ-ifWrre1VoqCOjuoGOoMEnxPlVYcHBurdeK5VHsxgm9BwgmxThjrt2KVc2SQ-DvWLkEpw # Fails - signed by an invalid key CLIENT_ASSERTION=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkZaU1Z3WkU3aUxTek1jcnhRb2lOOWRjcEphS2VNUzdTQnE5eFN6SVhLLTQifQ.eyJzdWIiOiIxMjM0NTZhYmNkZWYiLCJpc3MiOiJodHRwczovL2FsZXNzYW5kcm9zZWdhbGEuYmxvYi5jb3JlLndpbmRvd3MubmV0LyIsImlhdCI6MTc0ODE0NzI1NiwiYXVkIjoiYXBpOi8vUG9ja2V0SURUb2tlbkV4Y2hhbmdlIiwiZXhwIjoxNzQ5MjQ3MjU2fQ.EnrllAAKlOSv_3odLItIQHx28HwbV84RhHY5Hfh95eb8gzvUWYHR_vAuIj91hY5oyEtOn6qM3WQRRdWAWPoOcuxbVSW09TG6MXA6DZo7Pd43_IkWAovH5qen7uIb0wiv_3Vf3dls_YRzuHd5Mo2wdIKVmYJSrg22Qd5x6clcDXhwrfO_5B1H8WLlV-KaiEMBjN-7YFh59Eb4wbHrNaXrFyYWjuD-PZeG1NH9aSFBNeOq0KArjYIvn96mjhlKiE_DT15CK1zPjndikbK_SwAovOgGCV4Jnazm0_XF9AOCuPNEJlKwb0MhhcNcsr3Aelo9_3zxLKbe8DbEgI0I4ZjWYw ```

AtHeartEngineer closed this issue

2025-07-08 08:41:00 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/pocket-id#146