Document restoring the OpenBao JWT audience

What does this MR do and why?

  • Part of #608230 (closed)
  • Reconfigure authentication with a recovery key could not work. It needs a root token, and generating one needs the same JSON Web Token (JWT) login that is broken
  • Recover OpenBao authentication now covers the 2 ways the JWT login breaks, and how to fix each one without losing secrets
  • JWT audience mismatch, after the OpenBao URL changed: find the stored audience, then set global.openbao.jwt_audience to it
  • JWT issuer mismatch, after the GitLab URL changed: change the GitLab host settings back
  • If neither works, the section points to Reset OpenBao data. That section belongs to !258991 (merged), so this MR leaves it alone, except for dropping one paragraph that linked to the removed section
  • Adds an aud: keyword to GlobalSecretsManagerJwt for the Rails console check of a candidate audience
  • JWT authentication fails in troubleshooting now lists both error messages and links to the fixes
  • This MR and !258991 (merged) both drop that same paragraph. Whichever merges second keeps the reset MR version of those lines

References

Testing

Audience mismatch, end to end on a cloud native install, following the steps as written:

  • Set global.openbao.jwt_audience to a wrong value, and confirmed OpenBao rejected the JWT with invalid audience (aud) claim
  • The Helm history loop listed the stored audience, and the Rails console check accepted it and rejected a wrong one
  • Setting global.openbao.jwt_audience to the stored audience fixed the login

Issuer mismatch, on the GitLab Development Kit (GDK):

  • A JWT with a different iss is rejected with error validating token: invalid issuer (iss) claim, on the root auth mount and on a project auth mount. The same JWT with the current GitLab URL works
  • I did not run a full GitLab domain change end to end

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Jayakrishnan Mallissery

Merge request reports

Loading
Loading