Apéndice G — OAuth2/OIDC conceptual

Objetivo del apéndice

OAuth2 y OIDC sin jerga. Lo justo para entender qué pasa cuando haces login en Backstage y qué decisiones tomar como admin.

Roles

  • Resource Owner: el developer (dueño de su identidad).

  • Client: la app que pide datos (Backstage).

  • Authorization Server / IdP: emite tokens (GitHub, Keycloak, Okta).

  • Resource Server: la API que valida el token.

Flujo Authorization Code (el que usa Backstage)

  1. Developer hace clic en "Login with GitHub".

  2. Backstage redirige al IdP.

  3. IdP muestra consentimiento; developer acepta.

  4. IdP redirige a :code:`https://backstage/auth/github/handler?code=XXX`.

  5. Backstage intercambia el code por un access_token (server-to-server).

  6. Backstage pide :code:`/userinfo` con el token.

  7. Backstage crea la sesión (cookie) y devuelve 200.

Tokens

  • Access token: corta duración (minutos). Para llamar a APIs.

  • Refresh token: larga duración. Para renovar el access token.

  • ID token (OIDC): JWT con claims de identidad (sub, email, name).

Claims típicas

{
  "sub": "user:default/tester",
  "email": "tester@sazon-foods.com",
  "preferred_username": "tester",
  "name": "Maite Tester",
  "groups": ["platform-sazon", "engineering"],
  "iss": "https://keycloak.sazon-foods.com/realms/sazon",
  "aud": "backstage",
  "exp": 1720003200
}

Scopes

Definen qué puede pedir el client:

  • :code:`openid` — mínimo OIDC.

  • :code:`profile` — nombre, username.

  • :code:`email` — email.

  • :code:`groups` — grupos (en Keycloak con mapper).

Mejores prácticas

  • Usa Authorization Code with PKCE (no Implicit).

  • Access tokens de corta vida (< 1 h).

  • Refresh tokens en storage seguro del client.

  • Claims de grupos para mapear a Group del catalog.

Para más