Resumen

DTZ Identity gestiona tres cosas: Roles, Identidades y Autenticaciones para cada recurso que vive dentro de un Context. Los Contexts son las unidades organizativas en DTZ; cada entidad pertenece a uno, y el control de acceso fluye a través de él.

Diagrama de relaciones entre entidades de Identity

Core concepts

Context

Un Context (context-…) es el contenedor para tus aplicaciones, servicios y facturación. El creador se asigna automáticamente como Context Admin, y se provisiona una identidad de servicio como admin@{context_id}.dtz.rocks para la automatización.

Identities

Una Identity es un principal (usuario humano o cuenta de servicio). Vincularás asignaciones de roles a las identities.

Roles (Abstract vs. Concrete)

  • Abstract roles son conjuntos de permisos reutilizables definidos por cada servicio DTZ (p. ej., “containers admin”, “objectstore admin”, “billing admin”).
  • Concrete roles son abstract roles vinculados a un scope (ya sea un Context o una Identity) y expresados como un role URI. Estos son los que realmente asignas.

Examples of concrete role URIs:

  • Context-scoped: https://dtz.rocks/containers/admin/{context_id}
  • Identity-scoped: https://dtz.rocks/identity/admin/{identity_id}

Esta separación mantiene la lógica de permisos consistente mientras hace que las asignaciones sean conscientes del contexto.

Role scopes

Identity-scoped roles

Afectan acciones sobre la propia identity (p. ej., quién puede establecer una contraseña o crear claves API para una identity).

Common examples:

  • https://dtz.rocks/identity/admin/{identity_id}
  • https://dtz.rocks/billing/admin/{identity_id}
  • https://dtz.rocks/identity/assume/{identity_id}

Context-scoped roles

Afectan acciones dentro de un contexto (despliegues, registros, object store, etc.).

Common examples:

  • https://dtz.rocks/context/admin/{context_id}
  • https://dtz.rocks/containers/admin/{context_id}
  • https://dtz.rocks/objectstore/admin/{context_id}
  • https://dtz.rocks/observability/admin/{context_id}
  • https://dtz.rocks/containerregistry/admin/{context_id}
  • https://dtz.rocks/rss2email/admin/{context_id}

Cada servicio DTZ puede definir sus propios nombres de rol y alcances; los URIs anteriores son representativos.

How permissions are evaluated

  1. Autenticar (quién eres).
  2. Resolver roles concretos para el llamante (URIs de rol en la identity).
  3. Autorizar en función de si un URI de rol requerido coincide con el scope objetivo (contexto o identity) y la acción.

Example: assigning and using a role

  1. Asigna el abstract “containers admin” a un contexto específico → obtendrás un concrete role:

https://dtz.rocks/containers/admin/context-abc123

  1. Vincula ese rol a la identity alice@example.com.
  2. Cuando Alice llama a la API de Containers dentro de context-abc123, el role URI coincide y la acción está autorizada. El mismo rol no otorga derechos en otros contextos.

Authentication

DTZ admite múltiples métodos de autenticación; usa el que se adapte a tu cliente y entorno.

API Keys

  • Las claves se crean en la UI de Identity y están scopeadas a un context y a una identity.
  • Envíalas vía cabecera:

X-API-KEY: YOUR_API_KEY

  • Algunas integraciones de terceros que no pueden establecer cabeceras pueden pasar apiKey como parámetro de consulta (úsalo solo cuando sea imprescindible).

Bearer tokens (password login)

Obtén un JWT haciendo un POST con usuario/contraseña, luego envía Authorization: Bearer ….

Request token:

POST https://identity.dtz.rocks/api/2021-02-21/token/auth
Content-Type: application/json

{
"username": "user",
"password": "password"
}

Use token:

curl -H "Authorization: Bearer eyJhb..." \
  https://identity.dtz.rocks/api/2021-02-21/me

También puedes usar el JWT como una cookie llamada dtz-auth. El auth básico está soportado para algunos endpoints (apikey:apikey-1234).

Getting started checklist

  • Crea o selecciona un Context para tu app.
  • Decide qué abstract roles necesita tu app y vincúlalos como concrete roles en los alcances correctos (Context vs. Identity).
  • Asigna esos concrete roles a las identities (usuarios/cuentas de servicio) que los necesiten.