Authenticate users

JWT

Most identity providers issue JWTs: Auth0, Microsoft Entra ID, Keycloak, Okta, Google. Install jose next to the server (the container image already has it), then set the issuer, the audience and one key source:

MIOT_DASHBOARD_JWT_ISSUER=https://your-company.auth0.com/
MIOT_DASHBOARD_JWT_AUDIENCE=miot-dashboards
MIOT_DASHBOARD_JWT_JWKS_URL=https://your-company.auth0.com/.well-known/jwks.json
MIOT_DASHBOARD_JWT_USER_CLAIM=email

Set exactly one. The server accepts only that algorithm.

MIOT_DASHBOARD_JWT_USER_CLAIM names the claim that identifies the person. It defaults to sub. Whatever it holds is the ID you use in memberships and in dashboard permissions, so pick one that is readable and stable, such as email.

Callers send the token as Authorization: Bearer <token>.

Opaque ticket

If your system issues opaque tickets, the server can check each one with the issuer and cache the answer:

MIOT_DASHBOARD_TICKET_HEADER=x-ticket
MIOT_DASHBOARD_TICKET_VALIDATE_URL=https://auth.internal/tickets/{ticket}
MIOT_DASHBOARD_TICKET_USER_PATH=entry.id

The other ticket settings, such as caching and how to present the ticket, are in Configuration. JWT and tickets can run together because they read different headers.

Membership file

For a few dozen people, list them in a JSON file and point MIOT_DASHBOARD_SEED at it. The shape is organization, then scope, then person, then role:

{
  "memberships": {
    "acme": {
      "operations": {
        "ana@acme.example": "Coordinator",
        "luis@acme.example": "Editor",
        "sofia@acme.example": "Consumer"
      },
      "finance": {
        "ana@acme.example": "Consumer"
      }
    }
  }
}

A person may act in an organization when they appear in any of its scopes. The server reads the file at startup, so a change needs a restart.

Directory service

If a directory already knows who belongs where, the server can ask it on every request. A change there applies at once, with no restart and no new token.

MIOT_DASHBOARD_TENANTS_URL='https://directory.internal/people/{userId}/organizations/{tenantId}'
MIOT_DASHBOARD_SCOPES_URL='https://directory.internal/people/{userId}/groups/{scopeId}'
MIOT_DASHBOARD_SCOPES_ROLE_PATH=role
MIOT_DASHBOARD_SCOPES_ROLE_MAP='admin=Coordinator,editor=Editor,reader=Consumer'
MIOT_DASHBOARD_SCOPES_SERVICE_HEADER=authorization
MIOT_DASHBOARD_SCOPES_SERVICE_VALUE="Bearer $DIRECTORY_TOKEN"

A GET URL must contain {userId} and the organization or scope placeholder. Otherwise one answer would apply to everyone, and the server refuses to start. Answers are cached: yes for 60 seconds, no for 30, by default.

The full list of TENANTS_* and SCOPES_* settings is in Configuration.

Groups

If the identity provider already puts the organization and the role in a group name, such as GROUP_DHB_ACME_EDITOR, the server reads both from the groups it already has. Nothing is looked up and no file is maintained.

MIOT_DASHBOARD_TICKET_GROUPS_PATH=user.data.groups   # or MIOT_DASHBOARD_JWT_GROUPS_CLAIM
MIOT_DASHBOARD_GROUP_ROLES_PATTERN='GROUP_DHB_{tenant}_{role}'
MIOT_DASHBOARD_GROUP_ROLES_MAP='CONSUMER=Consumer,COLLABORATOR=Contributor,EDITOR=Editor,COORDINATOR=Coordinator'

The server fills the organization from the address into the pattern and compares the result with each group. Case and surrounding spaces do not matter. Because it fills the organization in rather than reading it out, an organization id that contains the separator, such as north_zone, cannot be confused with north.

Add {scope} to the pattern, such as GROUP_DHB_{tenant}_{scope}_{role}, to give a role in one scope only. Scope ids then cannot contain the character next to {scope} (here _): otherwise GROUP_DHB_ACME_X_OPS_EDITOR could mean organization acme_x, scope ops, or organization acme, scope x_ops. Without {scope}, a role applies in every scope of the organization.

The settings are in Configuration.