mirror of
https://codeberg.org/forgejo/forgejo.git
synced 2026-05-12 22:10:25 +00:00
48218c654b
Authorized Integrations is a new feature to allow users to define external systems which can generate JSON Web Tokens (JWTs) that Forgejo will trust in order to perform API access on behalf of that user. This is an authentication mechanism that requires zero preconfiguration of shared secrets, and instead establishes trust through short-lived secrets (JWTs) that are signed by the issuer, signatures are validated by comparison with published public keys, and a public-keys retrieved through well-known HTTP endpoints secured with TLS verification. The primary goal of Authorized Integrations is to support a mechanism for Forgejo Actions to receive elevated, but controlled, additional access to Forgejo. More details as to what the end result will look like are available in the [design proposal](https://codeberg.org/forgejo/forgejo/issues/3571#issuecomment-13268004) on #3571. This PR adds the core database storage and authentication verification for Authorized Integrations, with these capabilities: - An Authorized Integration is resolved by a unique key of an "issuer" and an "audience". The value of "issuer" is defined by the remote integration, and the value of "audience" will incorporate a unique identifier generated by Forgejo. - Example issuer: `https://token.actions.githubusercontent.com/` is the issuer for GitHub JWTs - Example audience: `https://forgejo.example.org/-/mfenniak/authorized-integration/6cc55ba0` is the expected format for a random audience field that Forgejo will generate. - JWTs can contain any number of claims, which are represented as a JSON object; Forgejo can validate these with a flexible policy. - eg. a claim may be `{"sub": "repo:coolguy/forgejo-runner-testrepo:pull_request"}` indicating that an OIDC token was received from an Actions execution in a specific repo on a specific event. - Authorized Integrations support a `ClaimRules` system which allows claim equal, glob, and nested object inspection. - `{"claim":"sub","comparison":"eq","value":"repo:mfenniak/forgejo-runner-testrepo:pull_request"}` -- would validate that `sub` exactly equals the specific value - `{"claim":"sub","comparison":"glob","value":"repo:mfenniak/forgejo-runner-testrepo:*"}` -- would validate that `sub` matches the given string prefix but allow any event - When a JWT is received on an incoming API call, Forgejo retrieves the Authorized Integration from the DB (if present), validates the token signature against a remote JWKS, validates the claims, and grants API access as the user with a permission scope defined on the Authorized Integration. In addition to the unit testing provided here, this PR has been manually integration tested against three JWT issuing systems: Forgejo Actions, GitHub Actions, and AWS STS GetWebIdentityToken. Careful consideration has been made of these security concerns: - SSRF attacks against Forgejo are prevented by: - having a blocklist on remote HTTP validation requests which prevent access to internal network resources, - ensuring that authorized integrations are created by users with matching issuers, before attempting to validate tokens - Resource utilization attacks against Forgejo are reduced by limiting the possible size of external metadata requests; when fetching `/.well-known/openid-configuration` and `jkws_uri`'s from remote, untrusted servers, a maximum response size of 16 kB is enforced - Only well-known secure assymmetric JWT signing algorithms are supported -- in particular, the sketchy `none` JWT algorithm isn't supported. - JWT validation is covered by extensive unit tests, covering validation of all JWT timestamps, validation of the issuers, validation of the issuer's documented supported signing algorithms. This PR serves as a core, and many enhancements are required for this to be a usable system for users. ## Checklist The [contributor guide](https://forgejo.org/docs/next/contributor/) contains information that will be helpful to first time contributors. All work and communication must conform to Forgejo's [AI Agreement](https://codeberg.org/forgejo/governance/src/branch/main/AIAgreement.md). There also are a few [conditions for merging Pull Requests in Forgejo repositories](https://codeberg.org/forgejo/governance/src/branch/main/PullRequestsAgreement.md). You are also welcome to join the [Forgejo development chatroom](https://matrix.to/#/#forgejo-development:matrix.org). ### Tests for Go changes - I added test coverage for Go changes... - [x] in their respective `*_test.go` for unit tests. - [ ] in the `tests/integration` directory if it involves interactions with a live Forgejo server. - I ran... - [ ] `make pr-go` before pushing ### Documentation - [ ] I created a pull request [to the documentation](https://codeberg.org/forgejo/docs) to explain to Forgejo users how to use this change. - Documentation updates for new config entries will be authored. - [ ] I did not document these changes and I do not expect someone else to do it. ### Release notes - [ ] This change will be noticed by a Forgejo user or admin (feature, bug fix, performance, etc.). I suggest to include a release note for this change. - [x] This change is not visible to a Forgejo user or admin (refactor, dependency upgrade, etc.). I think there is no need to add a release note for this change. - Marking not visible as there's no mechanism to interact with this backend yet. Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/12261 Reviewed-by: Andreas Ahlenstorf <aahlenst@noreply.codeberg.org> |
||
|---|---|---|
| .. | ||
| actions | ||
| agit | ||
| asymkey | ||
| attachment | ||
| auth | ||
| authz | ||
| automerge | ||
| context | ||
| contexttest | ||
| convert | ||
| cron | ||
| doctor | ||
| externalaccount | ||
| f3 | ||
| federation | ||
| feed | ||
| forgejo | ||
| forms | ||
| gitdiff | ||
| indexer | ||
| issue | ||
| lfs | ||
| mailer | ||
| markup | ||
| migrations | ||
| mirror | ||
| moderation | ||
| notify | ||
| org | ||
| packages | ||
| pull | ||
| redirect | ||
| release | ||
| remote | ||
| repository | ||
| secrets | ||
| shared/automerge | ||
| stats | ||
| task | ||
| uinotification | ||
| user | ||
| webhook | ||
| wiki | ||