Skip to content

docs: rewrite OAuth2 / OIDC / JWT reference#1739

Draft
netroms wants to merge 16 commits into
masterfrom
oauth2-docs-refresh-2.44
Draft

docs: rewrite OAuth2 / OIDC / JWT reference#1739
netroms wants to merge 16 commits into
masterfrom
oauth2-docs-refresh-2.44

Conversation

@netroms
Copy link
Copy Markdown
Contributor

@netroms netroms commented Apr 23, 2026 •
edited
Loading

Summary

  • Full rewrite of src/sysadmin/reference/oauth.md (290 → 910 lines) covering the authorization server, OAuth2 client CRUD, dynamic client registration with the Android enrollment walkthrough, OIDC login (Google / Azure / generic / private_key_jwt / internal DHIS2 provider / linked accounts), JWT bearer authentication, a full dhis.conf and system-settings reference, troubleshooting, and 2.41 → 2.42 upgrade notes.
  • Targets 2.42, 2.43, and 2.44 uniformly. Version-diff mentions between 2.42 / 2.43 / 2.44 are deliberately absent; the 2.41 → 2.42 delta is documented at the end.
  • All config keys, endpoints, tables, and authorities verified against dhis2-core master and the 2.41 branch.

AI Assisted

DO NOT MERGE YET!

@netroms @claude
docs: rewrite OAuth2 / OIDC / JWT reference
6a42ea8 
Full rewrite of src/sysadmin/reference/oauth.md. Covers the
authorization server, OAuth2 client CRUD, dynamic client
registration (including the Android enrollment walkthrough), OIDC
login (Google, Azure, generic, private_key_jwt, internal DHIS2
provider, linked accounts), JWT bearer authentication, full
configuration and troubleshooting reference, and 2.41 to 2.42
upgrade notes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@netroms netroms force-pushed the oauth2-docs-refresh-2.44 branch from abaf482 to 6a42ea8 Compare April 23, 2026 16:23
@netroms netroms mentioned this pull request Apr 24, 2026
Closed
netroms added 2 commits April 24, 2026 15:58
@netroms
Update OAuth documentation for issuer URI handling
8c38c8c 
Clarify how the authorization server reads the issuer URI from server.base.url and its impact on token issuance.
@netroms
Update OAuth documentation for token invalidation
194ca42 
Clarify that server restart invalidates tokens for devices but not clients.
This was referenced Apr 24, 2026
Merged
Merged
Merged
@netroms netroms marked this pull request as draft May 5, 2026 13:38
teleivo and others added 13 commits May 11, 2026 22:19
@teleivo @netroms
docs: link 2.43 release note from tracker performance section [DHIS2-…
0dbb272 
…20965] (#1743)

* docs: link 2.43 release note from tracker performance section

Adds a pointer from the tracker Performance section to the per-release
tracker performance changes, starting with 2.43.

DHIS2-20965

* docs: reword to emphasize improvements over previous releases
@karolinelien @claude @netroms
docs: update system settings docs - enable/disable period types, week…
45855b7 
…ly relative start day and more (#1744)

* docs: update analytics system settings for DHIS2 2.43 features

- Add Period types available in analytics apps (DHIS2-20520): new v2.43
  multi-select control for enabling/disabling period types, replacing
  the individual hide-period checkboxes for instances on v2.43+
- Add Weekly relative period start day (DHIS2-20839): new v2.43 setting
  for choosing the weekly relative period start day (Mon–Sun)
- Update Financial year relative start month (DHIS2-20840): document
  February, August and September as new options from v2.43
- Add missing Hide biweekly periods setting (was in app, not in docs)
- Add Use centroids for organisation unit polygons in event analytics
  (was in app, not in docs)
- Fix dashboard item settings labels: item → items (4 rows) to match
  the actual UI labels

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: note that Hide x periods settings were removed in v2.43

The individual Hide daily/weekly/biweekly/monthly/bimonthly periods
settings were removed in DHIS2 2.43 (maximumApiVersion: 42) and
replaced by the new Period types available in analytics apps setting.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update system-settings.md

* Update system-settings.md

* docs: table rendering fixes and API docs for 2.43 analytics changes

system-settings.md:
- Fix <br><br> to <br> <br> to match file convention
- Fix double space in Hide daily/weekly/... row
- Fix pre-existing missing closing | on Enable embedded dashboards row

settings-and-configuration.md:
- Add analyticsWeeklyStart system setting (new in 2.43)
- Update analyticsFinancialYearStart to list all valid options
  including new 2.43 values (FINANCIAL_YEAR_FEBRUARY/AUGUST/SEPTEMBER)
- Update all keyHide*Periods entries to note removal in 2.43
  and point to dataOutputPeriodTypes as replacement

overview.md:
- Update financialYearStart parameter to include new 2.43 options

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update overview.md

* Update settings-and-configuration.md

* Update settings-and-configuration.md

* Update settings-and-configuration.md

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
@ameenhere @netroms
fix: Typo and grammar in configure programs
9fa690f
@ameenhere @enricocolasante @netroms
Update src/user/configure-programs-in-the-maintenance-app.md
7208e0a 
Co-authored-by: Enrico Colasante <enrico@dhis2.org>
@ameenhere @netroms
doc: [DHIS2-16911] Schedule event with PR (#1746)
d4d31bf
@walid-mashal @netroms
Fix typos and grammar (#1742)
1b900ca 
* Fixed grammar

* Fix typos and grammatical issues in metadata documentation

Corrected typos and grammatical errors throughout the document.

* Fix encoding issues in configure-metadata.md
@dayures @netroms
chore: added doris.catalog.connection.url in the dhis.conf documentat…
79b62af 
…ion (#1740)
@d-rita @netroms
docs: add user docs for custom theme color selection (#1747)
8b0e4a3 
* docs: add theme color selection images

* docs: add user docs for custom theme color selection

* docs: update system settings docs

- remove outdated style (android) setting
- replace with new theme color setting that updates the look of the DHIS2 interface

---------

Co-authored-by: Diana Nanyanzi <diana@dhis2.com>
@iambodo @netroms
correct heading levels for program disagg mappings (#1697)
417eeba 
h1 headings (#) in this section had abridged the toc, removing important sections like the program rules
@DavidCKen @Philip-Larsen-Donnelly
@KaiVandivier @d-rita @cjmamo @dayures @larshelge @tomzemp @jason-p-pickering @netroms @karolinelien @maikelarabori
David c ken patch 1 (#1682)
6f61604 
* docs: DE app is no longer "beta" for v42/master (#1570)

* docs: update datastore management app docs 2.42 (#1572) (#1576)

* docs: update datastore management app docs

* fix: grammar fix and remove redundant image prop

* docs: formatting, mostly bullet points

* docs: some suggestions

* docs: add more images

* docs: adjust search palette image width

---------

Co-authored-by: Diana Nanyanzi <31903212+d-rita@users.noreply.github.com>

* docs: auth type description correction

* chore: add default

* fix: Update tracker API docs (#1584)

(cherry picked from commit 4bcacae)

* fix: Update tracker API guide (#1586)

(cherry picked from commit d22c9f2)

* fix: update tracked entity type authority names [DHIS2-15942] (#1588)

* fix: Update tracker API docs (#1590)

(cherry picked from commit 2ce5e8c)

* fix: Improve tracker docs (#1592)

(cherry picked from commit 0504639)

* fix: Tracker API guide improvements (#1593)

(cherry picked from commit 0847792)

* fix: Tracker API guide improvements

* fix: Remove code format for table values (#1595)

(cherry picked from commit c88cca3)

* fix: Update tracker docs (#1597)

(cherry picked from commit cc26e96)

* fix: Update tracker API docs (#1598)

(cherry picked from commit c9fb12e)

* fix: Update tracker JSON responses (#1599)

(cherry picked from commit 734b751)

* fix: Update inclusionStrategy parameter in metadata import export (#1601)

(cherry picked from commit a43e853)

* fix: Update pgBadger article (#1602)

(cherry picked from commit 0279981)

* docs(system-settings): link to more details about Global Shell in developer portal (#1596) (#1605)

* chore: remove config settings endpoint

* fix: change title introduction order [DHIS2-19366] (#1620)

* [DHIS2-16081} Add bi-weeks in relative period docs (v42)

[DHIS2-16081} Add bi-weeks in relative period docs (v42)

* Update overview.md

* docs: Update relative periods in API guide (#1636)

(cherry picked from commit 7f0843c)

* fix: Incorrect markdown in analytics guide (#1640)

(cherry picked from commit 74c953f)

* chore: v42 update default value lastYears parameter for analytics in scheduler

* fix: Improve API overview (#1647)

(cherry picked from commit de8ce34)

* chore: style

* add TEA in PRA assign value + clarification on how to trigger  (v42)

add TEA in PRA assign value + clarification on how to trigger

* Update configure-programs-in-the-maintenance-app.md

* docs(routes): backport docs and add security consideration (DHIS2-18860) (#1661)

* Update configure-programs-in-the-maintenance-app.md

* Update configure-programs-in-the-maintenance-app.md

* Add files via upload

* Add files via upload

---------

Co-authored-by: Philip-Larsen-Donnelly <35666657+Philip-Larsen-Donnelly@users.noreply.github.com>
Co-authored-by: Kai Vandivier <49666798+KaiVandivier@users.noreply.github.com>
Co-authored-by: Diana Nanyanzi <31903212+d-rita@users.noreply.github.com>
Co-authored-by: cjmamo <823038+cjmamo@users.noreply.github.com>
Co-authored-by: Carlos Tejo Alonso <1654811+dayures@users.noreply.github.com>
Co-authored-by: Lars Helge Øverland <lars@dhis2.org>
Co-authored-by: Thomas Zemp <tom@dhis2.org>
Co-authored-by: Jason Pickering <jason@dhis2.org>
Co-authored-by: Morten Svanaes <msvanaes@dhis2.org>
Co-authored-by: Karoline Tufte Lien <karoline@dhis2.org>
Co-authored-by: Maikel Arabori <51713408+maikelarabori@users.noreply.github.com>
@KaiVandivier @Philip-Larsen-Donnelly @netroms
docs: custom translations and theme color tweak (#1748)
1128a2f 
* docs: custom translations and theme color tweak

* Apply suggestion from @Philip-Larsen-Donnelly

---------

Co-authored-by: Philip-Larsen-Donnelly <35666657+Philip-Larsen-Donnelly@users.noreply.github.com>
@d-rita @netroms
docs: remove extra custom colors page (#1749)
1b77109 
* docs: fix custom color docs formatting

* docs: remove separate custom colors docs page
@netroms @claude
docs: document OIDC signed-JWT userinfo (eSignet) [DHIS2-20043]
7830e8a 
Adds user_info_response_type and user_info_jws_algorithm to the generic
provider reference table, plus a new "Signed-JWT userinfo (eSignet)"
section describing when to use the JWT path, a full configuration
example, the asymmetric algorithm allow-list, and the interplay with
private_key_jwt client authentication.

AI Assisted

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@david-mackessy david-mackessy david-mackessy approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.