Identity provider

From v0.19, trex is the identity provider of Data2Evidence. New installations use trex alone. Installations that already have users in Logto keep them: Logto stays available as an upstream sign-in option of trex.

The mode is stored in the env file as D2E_IDP_MODE:

Mode	Used by	Sign-in
trex	New installations	Data2Evidence username or email and password
logto-federated	Installations upgraded from v0.18 or earlier	Sign in with Logto

The d2e CLI sets the mode once, the first time it runs against an env file. You do not need to set it yourself.

Upgrading an installation that uses Logto

d2e start detects that the env file predates trex, records D2E_IDP_MODE=logto-federated and adds the trex settings the env file lacks. From then on the stack starts with the additional docker-compose-logto-federation.yml file:

• Logto keeps running as an upstream sign-in option of trex.
• The sign-in page shows only Sign in with Logto and redirects to Logto automatically. To stop on the sign-in page instead, open /d2e-login/?manual.
• Users carried over from Logto have no trex password, so the Data2Evidence password form is switched off. To bring the form back, for example to let a trex admin in while Logto is down, set TREX_NATIVE_PASSWORD_LOGIN_ENABLED=true in the env file.
• Logto users that have only a username and no email address can sign in too.
• On every start, trex migrates the Logto users. Each Data2Evidence user gets a trex account linked to their Logto identity, and their Data2Evidence roles are copied to trex.

Users sign in exactly as before, through Logto. Nothing needs resetting.

warning

Take a database backup before upgrading. Rolling back is only possible by restoring that backup.

Users keep their identity

A migrated user's trex account has the same ID as their Logto user. Everything Data2Evidence stores per user carries over unchanged, including cohorts, portal artifacts, flows, analyses and concept mappings.

Database credentials for the migration

The migration reads the Logto users as Logto's own database role, using PG__LOGTO_MANAGER_USER (default logto_postgres) and PG__LOGTO_MANAGER_PASSWORD. These are the same values the Logto container uses. Make sure both are set in your env file. Otherwise, the migration cannot read any Logto users.

Checking the migration

Show the outcome of the last migration run:

./d2e migrate-idp-roles --report

The report lists each step and every user that was skipped, with one of the following reasons:

Reason	Meaning
duplicate_email	Two users resolve to the same email address.
email_linked_elsewhere	The Logto identity is already linked to a different trex user, or its email address belongs to one. The report names that user.
no_email	The Logto user has neither an email address nor a username.
logto_origin_missing	The user's Logto ID no longer exists in Logto.
link_failed	trex could not link the Logto identity to the account.
subject_would_change	trex would give the user a new ID, so they would lose access to their work. The user is not linked and gets no roles. Upgrade trex and restart.
role_failed	The user's Data2Evidence roles could not be copied to trex.
rekey_failed	The Data2Evidence user record could not be aligned with the trex user ID.

Fix the data, then restart Data2Evidence or run the migration again:

./d2e migrate-idp-roles --run

--run restarts trex, which signs out every active user. --report never restarts anything.

If the link step is marked failed with no users listed, the migration could not read any Logto users. Check the database credentials.

Managing users after the upgrade

• Roles: manage roles in Data2Evidence user management. Changing a role in Logto has no effect.
• New users: create new users in Data2Evidence user management, not directly in Logto. A user created only in Logto is never linked and cannot sign in.
• Suspending users: Logto stays the source of truth for suspension. If you un-suspend a user only in trex, the next restart suspends them again while they are still suspended in Logto. Un-suspend them in Logto instead.

Mapping groups to roles

When users sign in through an upstream identity provider such as Microsoft Entra ID, IDP__GROUP_ROLE_MAPPING maps the provider's groups to Data2Evidence roles. See Environment variables for the format.

Leaving Logto

To switch to trex only:

1. Set D2E_IDP_MODE=trex in the env file.
2. Restart D2E.

Logto stops and the Sign in with Logto button disappears. Users who have no trex password need one: an administrator sets it in user management. Account links are kept, so setting the mode back to logto-federated restores Logto sign-in.

Integrations that call trex directly

The trex OIDC endpoints moved in v0.19. The old paths now return 404:

Old path	New path
/trex/oidc/authorize	/trex/oidc/oauth2/authorize
/trex/oidc/token	/trex/oidc/oauth2/token
/trex/oidc/session/end	/trex/oidc/oauth2/end-session

The issuer, the discovery document (/trex/oidc/.well-known/openid-configuration) and the signing keys are unchanged. Integrations that read their configuration from the discovery document need no change. Update any external integration that hard-codes the old paths.

Sign-out with internal certificates

If Caddy serves an internal certificate (tls internal), add Caddy's root certificate to TLS__EXTRA__CA_CRTS so that sign-out completes. When the public hostname is localhost, sign-out with an ID token cannot complete. See TLS.