Overview

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

Identity Entity Relationship Diagram

Core concepts

Context

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

Identities

Una Identidad es un principal (usuario humano o cuenta de servicio). Vincularás asignaciones de roles a identidades.

Roles (Abstract vs. Concrete)

  • Los roles abstractos son conjuntos de permisos reutilizables definidos por cada servicio DTZ (ej., “containers admin”, “objectstore admin”, “billing admin”).
  • Los roles concretos son roles abstractos vinculados a un ámbito (ya sea un Contexto o una Identidad) y expresados como un URI de rol. Estos son los que realmente asignas.

Ejemplos de URIs de rol concretos:

  • Con ámbito de contexto: https://dtz.rocks/containers/admin/{context_id}
  • Con ámbito de identidad: https://dtz.rocks/identity/admin/{identity_id}

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

Role scopes

Identity-scoped roles

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

Ejemplos comunes:

  • 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, almacenamiento de objetos, etc.).

Ejemplos comunes:

  • 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 roles y ámbitos; los URIs anteriores son representativos.

How permissions are evaluated

  1. Autenticarse (quién eres).
  2. Resolver roles concretos para el llamante (URIs de rol en la identidad).
  3. Autorizar basándose en si un URI de rol requerido coincide con el ámbito objetivo (contexto o identidad) y la acción.

Example: assigning and using a role

  1. Asigna el rol abstracto “containers admin” a un contexto específico → obtienes un rol concreto:

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

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

Authentication

DTZ soporta 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 Identidad y están limitadas a un contexto y una identidad.
  • Enviar vía encabezado:

X-API-KEY: YOUR_API_KEY

  • Algunas integraciones de terceros que no pueden establecer encabezados pueden pasar apiKey como parámetro de consulta (usar solo cuando sea inevitable).

Bearer tokens (password login)

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

Solicitud de token:

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

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

Uso del 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. La autenticación básica está soportada para algunos endpoints (apikey:apikey-1234).

Getting started checklist

  • Crea o selecciona un Contexto para tu app.
  • Decide qué roles abstractos necesita tu app y vincúlalos a roles concretos en los ámbitos adecuados (Contexto vs Identidad).
  • Asigna esos roles concretos a las identidades (usuarios/cuentas de servicio) que los requieran.