Skip to content

docs(sso): cover Okta dashboard sign-in and new OIDC groups - #16430

Merged
Maffooch merged 1 commit into
devfrom
docs/oidc-okta-tile-and-new-groups
Oct 19, 2026
Merged

Maffooch merged 1 commit into
devfrom
docs/oidc-okta-tile-and-new-groups

Conversation

@Maffooch

Copy link
Copy Markdown
Contributor

Description

A follow-up to #16420, covering what further testing against a live Okta org and a local DefectDojo Pro stack turned up while working through a customer support ticket about OIDC group mapping.

Changes to docs/content/admin/sso/PRO__oidc.md, English only:

  • New groups start with no permissions. A group that group mapping creates has no product, product type or global permissions, so its members see nothing new until someone grants the group access. A troubleshooting bullet now points at it.
  • Groups don't need an app assignment. A group in the claim does not have to be assigned to the Okta application. Membership plus a name the claim filter matches is enough.
  • Issuer, not Metadata URI. Step 1 of the Okta section now says the endpoint is the server's issuer (the Issuer URI column in the server list), not the Metadata URI on the server's Settings tab.
  • New section, "Signing in from the Okta dashboard". A callback without state logs AuthMissingParameter: Missing needed parameter state and sends the user back to the login page. It does not affect group mapping. The section gives the Okta login settings that make the dashboard tile start the sign-in through DefectDojo.

This PR does not touch the restart step or the restart troubleshooting bullet that #16424 rewrites. It merges cleanly with #16424 in either order (checked with git merge-tree).

Test results

  • Docs production build: cd docs && hugo --minify --gc --config config/production/hugo.toml passed, and the new section and text render on the built page. Lychee was not run locally; the diff adds no links.
  • Checked against a live Okta org and a local DefectDojo Pro stack:
    • Two new Okta groups (not assigned to the app) arrived in the ID token, and DefectDojo created both with the user as Reader. Each had 0 product grants, 0 product type grants and no global role.
    • A request to /complete/oidc/ without state raised AuthMissingParameter and redirected to /login.
    • With the tile set to "Either Okta or App", "Redirect to app to initiate login (OIDC Compliant)" and an Initiate login URI of /login/oidc/, clicking it went through /login/oidc/?iss=... and then /complete/oidc/?code=...&state=.... The sign-in succeeded with no AuthMissingParameter.

Documentation

This PR is the documentation change.

Checklist

  • Make sure to rebase your PR against the very latest dev.
  • Submit all PRs, features and bug fixes alike, against the dev branch.
  • Give a meaningful name to your PR, as it may end up being used in the release notes.
  • Your code is Ruff compliant (see ruff.toml). (N/A, docs only)
  • Your code is python 3.13 compliant. (N/A, docs only)
  • If this is a new feature and not a bug fix, you've included the proper documentation in the docs at https://github.com/DefectDojo/django-DefectDojo/tree/dev/docs as part of this PR. (N/A, docs only)
  • Model changes must include the necessary migrations in the dojo/db_migrations folder. (N/A)
  • Add applicable tests to the unit tests. (N/A, docs only)
  • Add the proper label to categorize your PR.

🤖 Generated with Claude Code

Explain that groups created by OIDC group mapping start with no
permissions, that a group only needs a matching name and its members
in Okta (not an application assignment) to appear in the claim, and
that DefectDojo needs the authorization server's issuer, not its
metadata URI.

Add a section on signing in from the Okta dashboard: why a callback
without state logs AuthMissingParameter, and the Okta login settings
that make the tile start the sign-in through DefectDojo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Maffooch
Maffooch requested a review from blakeaowens as a code owner October 19, 2026 21:01
@Maffooch Maffooch added this to the 3.4.300 milestone Oct 19, 2026
@Maffooch Maffooch added the docs label Oct 19, 2026
@Maffooch
Maffooch added this pull request to the merge queue Oct 19, 2026
Merged via the queue into dev with commit 6cb710b Oct 19, 2026
31 checks passed
@Maffooch
Maffooch deleted the docs/oidc-okta-tile-and-new-groups branch October 19, 2026 21:52
@defectdojo-release-tracker defectdojo-release-tracker Bot modified the milestones: 3.4.300, 3.4.201 Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants