Ehrbase Authentication

generated: '2026-09-02'
method: searched
source: https://docs.ehrbase.org/docs/EHRbase/Explore/Security
docs: https://docs.ehrbase.org/docs/EHRbase/Explore/Security
note: >-
  EHRbase is deployer-hosted software, not a hosted SaaS API, so authentication is a
  DEPLOYMENT-TIME CHOICE made by whoever runs the server rather than a fixed scheme
  the vendor enforces. The published OpenAPI carries NO components.securitySchemes
  and no top-level security[] - it is generated by springdoc from a running instance,
  and the public reference instance (sandkiste.ehrbase.org) runs with AUTH_TYPE=NONE.
  Everything below is read from the provider's own Security documentation, not derived
  from the spec, which is why this artifact is `searched` rather than `derived`.
default_posture: none
default_posture_note: >-
  "By default, EHRbase is started without security enabled (NONE) which will be
  reported by a message during boot." Operators must opt in to BASIC or OAUTH.
mechanisms:
  - id: none
    type: none
    label: No authentication
    default: true
    config:
      env: SECURITY_AUTHTYPE
      yaml: security.authType
      value: NONE
    note: The shipped default. Every resource is open. Not for production.
  - id: basic
    type: http
    scheme: basic
    label: HTTP Basic authentication
    header: 'Authorization: Basic {base64(username:password)}'
    config:
      env:
        - SECURITY_AUTHTYPE=BASIC
        - SECURITY_AUTHUSER
        - SECURITY_AUTHPASSWORD
        - SECURITY_AUTHADMINUSER
        - SECURITY_AUTHADMINPASSWORD
      yaml:
        - security.authType
        - security.authUser
        - security.authPassword
        - security.authAdminUser
        - security.authAdminPassword
    roles:
      - user
      - admin
    note: >-
      A fixed two-account model - one user account and one admin account, configured
      at boot. The admin account is what gates /rest/admin/** and /management.
  - id: oauth2
    type: oauth2
    label: OAuth 2.0 / OIDC bearer JWT against an external realm
    header: 'Authorization: Bearer {jwt}'
    config:
      env:
        - SECURITY_AUTHTYPE=OAUTH
        - SECURITY_OAUTH2USERROLE
        - SECURITY_OAUTH2ADMINROLE
        - SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI
      yaml:
        - security.authType
        - security.oauth2UserRole
        - security.oauth2AdminRole
        - spring.security.oauth2.resourceserver.jwt.issuer-uri
    token_validation: >-
      EHRbase acts as an OAuth2 resource server and validates the JWT against the
      configured issuer-uri. It reads the admin/user role from the JWT's
      realm_access.roles and scope claims.
    claims_read:
      - realm_access.roles
      - scope
    roles:
      - name: USER
        default_claim_value: USER
        configurable_via: SECURITY_OAUTH2USERROLE
      - name: ADMIN
        default_claim_value: ADMIN
        configurable_via: SECURITY_OAUTH2ADMINROLE
    note: >-
      The role names are configurable so the deployment can match an authorization
      server that is opinionated about custom role/scope naming. There is no
      EHRbase-published scope registry - authorization is role-based, which is why
      no scopes/ artifact is emitted for this provider.
authorization_model:
  style: role-based
  roles:
    - id: user
      grants: The openEHR REST API (/rest/openehr/v1/**) and the EHRscape API (/rest/ecis/v1/**)
    - id: admin
      grants: >-
        Everything the user role grants, plus the Admin API (/rest/admin/**) and the
        Spring Boot Actuator status/metrics surface (/management/**)
  evidence:
    - Every /rest/admin/** operation in the OpenAPI declares 401 and 403 responses.
    - https://docs.ehrbase.org/docs/EHRbase/Explore/Admin-REST
    - https://docs.ehrbase.org/docs/EHRbase/Explore/Status-And-Metrics
transport:
  tls_required_by_docs: true
  tls_note: >-
    "All auth methods can be attacked easily if you do not use HTTPS encrypted
    communication outside trusted networks" - Status and Metrics docs.
  mutual_tls_supported: >-
    For outbound HTTP event triggers only (enterprise feature); SSL/TLS with mutual
    authentication can be enforced on the trigger client.
reference_instance:
  host: https://sandkiste.ehrbase.org/ehrbase
  auth: none
  observed: '2026-09-02'
  note: >-
    Public EHRbase sandbox ("Sandkiste"). Reads such as
    GET /rest/openehr/v1/definition/template/adl1.4 returned HTTP 200 anonymously.