rucio / rucio/documentation

Add screenshots/diagrams to OIDC authentication documentation

Open
#706 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Discussion needed enhancement
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:

  1. Run rucio whoami → get URL
  2. Open browser → authenticate at IdP
  3. Browser redirects → copy authorization code
  4. 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
  1. docs/user/using_the_client.md - Add workflow screenshots
  2. docs/operator/oidc.md - Add sequence diagram
  3. Create docs/user/assets/oidc-flow/ folder for images

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.