> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bbrands.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth e Identidad (IdP)

> Proveedor de identidad OAuth 2.1 / OpenID Connect centralizado para el holding B Brands. Autentica usuarios y máquinas en todas las plataformas desde una única fuente de verdad.

<Info>
  Esta sección documenta el **IdP de B Brands** — la plataforma de autenticación
  centralizada expuesta a través de `auth.bbrands.io`. Es el único lugar donde el
  holding demuestra **quién es un usuario** y **si está habilitado** para una
  plataforma dada (ERP, CRM, analytics, futuros SaaS, partners).
</Info>

## Qué es esto

El IdP de B Brands es el proveedor de identidad estándar del holding. Cualquier plataforma —
existente o futura — autentica a sus usuarios vía **OAuth 2.1 / OpenID Connect**
contra B Brands, en lugar de mantener su propia base de datos de usuarios.

El protocolo lo maneja un **motor OAuth 2.1 / OIDC administrado**, envuelto
por completo detrás del origen `auth.*` por entorno. Los clientes nunca ven el
motor subyacente: el registro de clientes, el ciclo de vida de la identidad, la auditoría y cada
endpoint público viven en la capa de identidad de B Brands. El motor es un
detalle de implementación reemplazable.

```mermaid theme={null}
flowchart LR
    subgraph clients["OAuth clients"]
        erp["ERP platform"]
        crm["CRM platform"]
        more["Future platforms"]
    end
    subgraph authorigin["auth.bbrands.io (identity origin)"]
        oauth["/api/v3/oauth/*"]
        wellknown["/.well-known/*"]
        consent["/oauth/consent (UI)"]
    end
    subgraph gateway["api.bbrands.io (API backend)"]
        impl["OAuth implementation"]
        exchange["/api/v3/oauth/exchange"]
        resource["Resource APIs (RBAC)"]
    end
    subgraph identity["Identity & governance"]
        am["Identity admin console<br/>(source of truth)"]
        supa["Managed OIDC engine<br/>(OAuth 2.1)"]
    end

    clients -->|OIDC| oauth
    clients -->|OIDC| wellknown
    oauth --> impl
    wellknown --> impl
    impl --> supa
    exchange --> am
    resource --> am
    supa --> am
```

## La regla de oro: el IdP autentica, no autoriza

Este es el concepto más importante para cada equipo que se integra con el
IdP. Tenlo presente mientras lees el resto de la sección.

<CardGroup cols={2}>
  <Card title="Lo que el IdP hace" icon="circle-check">
    Demuestra la **identidad** de un usuario (`sub`, `email`, perfil), entrega
    su **contexto de cuenta de negocio** (`https://bbrands.io/profile`: cuenta
    primaria y su id de sistema externo) y si está **habilitado** para una
    plataforma (`active` / `suspended` / `revoked`).
  </Card>

  <Card title="Lo que el IdP NO hace" icon="circle-xmark">
    No gestiona los permisos de las aplicaciones. Cada aplicación cliente decide
    qué puede hacer un usuario **dentro de ella**. No existe un catálogo central de permisos.
  </Card>
</CardGroup>

Hay **dos direcciones** de llamadas, tratadas de forma diferente:

<Steps>
  <Step title="Un usuario inicia sesión en una app cliente vía B Brands">
    El IdP solo autentica. La app cliente autoriza a sus propios usuarios con sus
    propios roles/grupos.
  </Step>

  <Step title="Una app cliente consume las APIs de B Brands">
    B Brands protege sus propios datos con el RBAC interno existente. El cliente
    actúa con un **JWT interno de B Brands** obtenido a través del
    [intercambio de tokens](/es/oauth/token-exchange) (contexto de usuario) o con una
    **API key** existente (máquina a máquina, sin usuario).
  </Step>
</Steps>

<Warning>
  El token OAuth ES256 **nunca** llega a las APIs de negocio de B Brands. Esas APIs
  siguen validando el JWT interno HS256 exactamente como lo hacen hoy. El Resource
  Server no cambia.
</Warning>

## Dos formatos de token coexisten

| Token                          | Algoritmo                 | Emitido por                       | Consumido por                     | Transporta                    |
| ------------------------------ | ------------------------- | --------------------------------- | --------------------------------- | ----------------------------- |
| **Token de acceso / ID OAuth** | ES256 (asimétrico, P-256) | IdP (motor + hook)                | La app cliente, validado vía JWKS | Identidad + profile de cuenta |
| **JWT interno de B Brands**    | HS256 (simétrico)         | Endpoint de intercambio de tokens | APIs de recursos de B Brands      | Contexto de usuario para RBAC |

Los dos nunca se mezclan: **ES256 para la identidad hacia los clientes**, **HS256 para consumir
las APIs de B Brands**. Consulta [Seguridad](/es/oauth/security) para el modelo de tokens completo.

## Quién debería leer qué

<CardGroup cols={2}>
  <Card title="Integradores (nueva plataforma)" icon="plug" href="/es/oauth/client-integration">
    Configura tu cliente OAuth, el discovery, las redirect URIs y (opcionalmente) el
    intercambio de tokens para llamar a las APIs de B Brands.
  </Card>

  <Card title="Backend / arquitectos" icon="sitemap" href="/es/oauth/architecture">
    Las capas de componentes, el facade del motor, los ADRs y el hook de token de acceso.
  </Card>

  <Card title="Backend / integradores" icon="code" href="/es/oauth/endpoints">
    El contrato de los endpoints OAuth / OIDC: discovery, authorize, token, userinfo,
    revoke.
  </Card>

  <Card title="Seguridad / compliance" icon="shield-halved" href="/es/oauth/security">
    Modelo de tokens, gestión de secretos, modelo de amenazas, niveles de revocación y auditoría.
  </Card>

  <Card title="Datos / ciclo de vida" icon="database" href="/es/oauth/data-model">
    Las entidades de identidad, el ciclo de vida de habilitación y el kill switch.
  </Card>

  <Card title="Equipos de frontend" icon="users" href="/es/oauth/social-login">
    El inicio de sesión social para usuarios finales, separado, a través del motor administrado.
  </Card>
</CardGroup>

## Entornos

El IdP se ejecuta en múltiples entornos. Cada uno tiene su propio motor aislado, su propio
issuer y sus propios clientes OAuth registrados. Un token acuñado en un entorno
**nunca** es válido en otro, porque los clientes validan el `iss` de su propio
entorno.

| Entorno       | Issuer canónico (`iss`)                 | URL de discovery                                                         |
| ------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| Development   | `https://development.auth.bbrands.io`   | `https://development.auth.bbrands.io/.well-known/openid-configuration`   |
| Certification | `https://certification.auth.bbrands.io` | `https://certification.auth.bbrands.io/.well-known/openid-configuration` |
| Production    | `https://auth.bbrands.io`               | `https://auth.bbrands.io/.well-known/openid-configuration`               |

Cada superficie OAuth/OIDC — discovery, JWKS, authorize, token, userinfo, revoke
**y** la UI interactiva de consentimiento/login — vive bajo el mismo origen
`auth.*` por entorno. Ese origen es el issuer canónico incrustado en cada token
emitido.

<Note>
  Un único origen de identidad de cara al usuario, a propósito: **`auth.*`** es el
  issuer canónico y sirve cada endpoint del protocolo más la UI de consentimiento
  (con la misma forma que `accounts.google.com`). El dominio `api.*` aloja la
  implementación subyacente y las APIs de negocio de B Brands, pero **no** es
  el issuer anunciado — los clientes solo configuran `auth.*`. Consulta
  [Arquitectura](/es/oauth/architecture) para el registro de decisiones.
</Note>

## Convención de nombres de clientes

Los identificadores de cliente OAuth siguen el patrón `<platform>-<environment>`, p. ej.
`erp-prod`, `erp-cert`, `erp-dev`. Registra siempre un cliente distinto por
entorno.