OIDC Integration

last updated: 2026-03-19

DTZ Identity is a standards-compliant OpenID Connect (OIDC) provider. Any service that supports OIDC can delegate authentication to DTZ, allowing your users to sign in with their existing DTZ credentials.

Prerequisites

  • A DTZ account and at least one context (context-{id})
  • A service or application that supports OIDC / OAuth 2.0 authorization code flow

Discovery endpoint

DTZ publishes a standard OIDC discovery document:

https://identity.dtz.rocks/.well-known/openid-configuration

Most OIDC client libraries accept an issuer URL and fetch this document automatically to configure themselves. Set the issuer to https://identity.dtz.rocks and let the library handle endpoint discovery.

Client credentials

DTZ uses the context ID as both client_id and client_secret. No separate application registration is required.

Parameter Value
client_id Your context ID, e.g. context-abc123
client_secret Same context ID
issuer https://identity.dtz.rocks

Configuration reference

The following environment variables demonstrate a typical integration:

OIDC_ISSUER=https://identity.dtz.rocks
OIDC_CLIENT_ID={YOUR_CONTEXT_ID}
OIDC_CLIENT_SECRET={YOUR_CONTEXT_ID}
OIDC_REDIRECT_URI=https://yourapp.example.com/login

Variable names will differ between libraries and frameworks; the values above are what matters.

ID token claims

After a successful token exchange, the ID token and userinfo endpoint return the following claims:

Claim Example value Description
sub identity-12345678 Unique identity identifier
iss dtz.rocks Token issuer — always dtz.rocks for DTZ-issued tokens
contexts ["abc124"] Context IDs the user belongs to
roles ["https://dtz.rocks/context/admin/abc123"] Concrete role URIs assigned to the user

Access control via claims

Use claim values to restrict who may access your service after a successful OIDC login.

Restrict to any DTZ user — check that iss equals dtz.rocks:

OIDC_ALLOWED_CLAIM=iss
OIDC_ALLOWED_VALUES=dtz.rocks

Restrict to users in a specific context — check the contexts array:

OIDC_ALLOWED_CLAIM=scope
OIDC_ALLOWED_VALUES={YOUR_CONTEXT_ID}}

Restrict to users with a specific role — check the roles array for a concrete role URI.

The exact mechanism for evaluating these checks depends on your OIDC library or middleware.

Authorization code flow

  1. Redirect the unauthenticated user to the DTZ authorize endpoint (resolved via discovery).
  2. User authenticates at https://identity.dtz.rocks. Already-logged-in users are redirected back immediately.
  3. Exchange the returned authorization code for tokens at the token endpoint.
  4. Validate the ID token’s iss claim and any additional access-control claims.
  5. Grant or deny access based on your claim policy.

Userinfo endpoint

GET https://identity.dtz.rocks/api/2021-02-21/oauth/userinfo
Authorization: Bearer <access_token>

Returns the same claims as the ID token. Use this endpoint when you need to re-fetch up-to-date claim values after the initial login.