Add screenshots/diagrams to OIDC authentication documentation
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 4
- Forks
- 71
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 11
Description
Problem
OIDC authentication involves multi-step browser interactions that are not obvious from text alone:
- Run
rucio whoami→ get URL - Open browser → authenticate at IdP
- Browser redirects → copy authorization code
- Paste code → complete authentication
Current documentation: Text-only, no visual guidance
Result: Users get confused, especially at redirect step
Proposed Solution
Add annotated screenshots to docs/user/using_the_client.md:
Visual Workflow Example
Step 1: CLI prompts for authentication
$ rucio whoami
Please authenticate via browser:
https://ri-scale-server.rucioit.cern.ch/auth/oidc_redirect?...
[Screenshot: Terminal with URL]
Step 2: Browser authentication at IdP
[Screenshot: Sample login page with arrows pointing to username/password fields]
Step 3: Authorization code in redirect URL
[Screenshot: Browser URL bar with code parameter highlighted]
https://ri-scale-server.rucioit.cern.ch/auth/oidc_code?
state=...&code=abc123... ← Copy this code
Step 4: Paste code in CLI
Enter the code: [paste code here]
status : ACTIVE
account : root
[Screenshot: Successful authentication output]
Additional Diagrams
Sequence Diagram (for operator docs):
User → CLI: rucio whoami
CLI → Browser: Open auth URL
Browser → IdP: Authenticate
IdP → Browser: Redirect with code
Browser → User: Display code
User → CLI: Paste code
CLI → Rucio: Exchange code (+PKCE)
Rucio → CLI: Return JWT
Advantages
- Reduces confusion: Visual guidance prevents common mistakes
- Faster onboarding: New users succeed on first try
- International: Screenshots transcend language barriers
- Debugging aid: Operators can point users to "this should look like..."
Files to Update
docs/user/using_the_client.md- Add workflow screenshotsdocs/operator/oidc.md- Add sequence diagram- Create
docs/user/assets/oidc-flow/folder for images
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading docs/user/using_the_client.md and docs/operator/oidc.md, then review the proposed four-step OIDC workflow. Add annotated screenshots under docs/user/assets/oidc-flow/ and a sequence diagram for the operator documentation; done means both guides visually explain the authentication flow and code handoff.
Written by the indexing model from the issue text.
Assessment
- Domain
- authentication, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100