PRD: Operators must request the OIDC scopes their configuration depends on
- Dominant language
- TypeScript
- Stars
- 21
- Forks
- 11
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 3
Description
## Problem Statement
The Harbor and Gitea operators configure their applications to read identity claims that they never ask the issuer to send.
Harbor is configured to take its username from the email claim and team membership from the groups claim, but requests only the `openid` scope. Worse, the scope is hardcoded in the operator: it is parsed from the ConfigMap into the configuration object and then ignored, so the value the platform supplies has no effect. Gitea is registered with a group claim name but its authentication source is created without any scope list at all.
This worked against Keycloak, which attaches those claims through a protocol mapper regardless of what the client requests. It does not work against an issuer that emits a claim only when its scope is requested. Harbor then fails to onboard a user at all, reporting that it cannot recover a username, and Gitea places every user outside their teams.
## Problem in context
This is the operator-side half of a change already made in `apl-core`, where the platform now supplies the correct scope list. That value currently reaches Harbor and is discarded.
## Solution
Have both operators request the scopes their configuration depends on.
Harbor should use the scope value it is given rather than a hardcoded one, so the platform stays the single place that decides which claims are needed. The same applies to the display name of the identity provider, which is likewise hardcoded and now names the wrong system.
Gitea should pass an explicit scope list when it creates or updates its authentication source, including the scope that carries group membership.
## Acceptance Criteria
1. **GIVEN** a scope list supplied in the Harbor operator's configuration, **WHEN** the operator applies its OIDC configuration, **THEN** Harbor is configured with that list rather than a hardcoded value.
2. **GIVEN** no scope list is supplied, **WHEN** the operator applies its OIDC configuration, **THEN** it falls back to the previous behaviour so an older platform is unaffected.
3. **GIVEN** an identity provider display name supplied in configuration, **WHEN** the operator applies its OIDC configuration, **THEN** Harbor shows that name on its login page.
4. **GIVEN** Harbor is configured with a scope list that includes email and groups, **WHEN** a user logs in through an issuer that honours scopes, **THEN** onboarding succeeds and the user's team membership is applied.
5. **GIVEN** the Gitea operator creates or updates its authentication source, **WHEN** the command is issued, **THEN** it includes an explicit scope list containing the scope that carries group membership.
6. **GIVEN** Gitea is configured that way, **WHEN** a user logs in, **THEN** their group membership is present and team mapping is applied.
7. **GIVEN** either operator runs against an unchanged platform, **WHEN** it reconciles, **THEN** the resulting application configuration is unchanged.
## Testing
- Unit tests asserting the configuration each operator sends, including the fallback when no scope list is supplied. The Harbor operator has an established test suite that is the prior art.
- Criteria 4 and 6 need a cluster with an issuer that honours scopes, since the failure is in the claims of a real token rather than in the configuration.
## Out of Scope
- Any change to how the operators authenticate to Harbor or Gitea themselves.
- Existing accounts that were created under a different issuer. Those are affected by a change of issuer, not by this change.
- Other hardcoded values in these operators that are not related to scopes.
## Further Notes
- Harbor's failure is loud but misleading: it reports that it cannot recover a username, which points at the username claim rather than at the missing scope that caused the claim to be absent.
- Gitea's failure is silent. Authentication succeeds and the user simply has no teams, which is easy to mistake for a mapping problem.
## Dependencies
Depends on linode/apl-core#3537 — the platform only supplies the correct scope list once the issuer is selectable. Until then this change is inert, because the value it consumes is not yet produced.
Contributor guide
Research direction
Start by locating the Harbor operator's OIDC configuration path and established unit tests, then find the Gitea authentication-source creation or update entry point. Verify the supplied scope and display-name values, fallback behavior, and explicit group scope in unit tests; completion also requires issuer-backed cluster checks for Harbor onboarding and Gitea team mapping.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes, typescript
- Domain
- authentication, devops
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100