azuma mimoto

azuma mimoto implements Gesundheits-ID as a service, which includes the following integration scenarios

• Auth as a Service: We provide the Authorization Service (Relying Party) for your Application. You use the established OpenID Connect (abbr. OIDC ) protocol against the Relying Party. We manage all the required technical and organizational trust requirements for you and provide an UI for the selection of the target Identity Provider.

• Auth Gateway as a Service: We provide the Authorization Service (Relying Party) as a gateway for your frontend. We manage all the required technical and organizational trust requirements for you. You control the selection of the target Identity Provider and initiate the identification process.

Need something else?

If our integration scenarios do not meet your requirements, please don't hesitate to contact us.

Architectural Approach

• Application is registered in **azuma mimoto **and operates via OpenID Connect (Authorization Code flow)
• azuma mimoto acts as OpenID Connect Provider towards Application and as Relying Party in the federation
• Application is registered in the Federation Master specifically (not a global azuma mimoto registration)
• Trust is established for each Application specifically

Important

The architectural concept of azuma mimoto was presented and clarified with gematik.

Getting Started

Pre-requirements

1. Relying Party definition in azuma mimoto.

• Input required from Application:

  • Short Key

• azuma mimoto provides the following:

  • Certificates for Entity Statement, Relying Party mtls and Relying Party enc
  • Client(s) for the OIDC Authorization Code flow
  • Entity Statement for the Application

  Available under https://mimoto.azuma-health.tech/*short-key*/.well-known/openid-federation (Domain names are specific per environment, see below)

ShortKey

The Short Key in conjunction with the azuma mimoto domain provides a unique identifier within the federation for the Relying Party.

Format: https://env.mimoto.azuma-health.tech/short-key.
e.g.: https://mimoto.azuma-health.tech/hokoku

Therefore, the Short Key is also unique within azuma mimoto.

2. Relying Party configuration

• Definition of integration mode and further parameters, see below
• Definition of Application, see below

3. Registration in Federation Master

• Application needs to be registered in Federation Master per `Environment?. This is done by email and requires the disclosure of the following data:
  • Environment : test environment (TU) / reference environment (RU) / production environment (PU)
  • Issuer : this is the Federation Key created above
  • Organization : Name of your legal entity / company
  • Required Scopes (You can find the available Scopes here: https://wiki.gematik.de/display/IDPKB/App-App+Flow)
  • A PEM-based Public Key of the Entity Statement signature
  • Further DiGA identification data for the PROD registration
• We will provide all the required technical information to simplify the composition of such an email

note

We can send those emails on your behalf in the lower environments (TU/RU)

4. PROD registration in Federation Master

Prior to the registration on the PROD environment, some admission tests will be done by gematik in the lower environments. This means, that we need to register in TU/RU environments first (see below), before requesting a PROD registration in the Federation Master.

Registration Timeline

The Federation Master registrations per Environment can take several business days.

Integration Approaches

The overall integration approach is to implement the OpenID Connect Authorization Code flow against azuma mimoto.

Depending on the current application solution, this can be done

• by adding an external identity provider (e.g. in Keycloak) (similar to adding social providers like google etc.)
• by extending an OIDC-capable framework, that is already in place (frontend or backend)
• by adding an OIDC-capable framework (frontend or backend)
• by triggering the flow manually

warning

We would advise against triggering the flow manually, as there are well-tested and hardened libraries available for most languages and frameworks

The above implementation choice has security implications on token storage/handling. Therefore, it is important to consider how tokens should be issues and if they should be stored at all in azuma mimoto.

Token Storage

Following token storage modes are available:

• Proxy Mode: azuma mimoto does not store tokens at all (only some claims are stored encrypted during login process and removed after login is finished). The token is retrieved once per login by the Application, especially: each token retrieval requires a full login by the user.

• Full Mode: azuma mimoto stores tokens encrypted for the time of token validity. This mode allows the Application to request a token within the validity timeframe without triggering a full login by the user.

Need something else?

If token handling needs to be different in your integration scenario, please don't hesitate to contact us.

Token Issuing Mode

Currently only one token issuing mode is available:

• mimoto Tokens: azuma mimoto issues Access Token and Identity Token with the original claims as given from the Identity Provider. If original Identity Provider tokens are required, those can be configured to be included as claims in the issued tokens. See Application configuration below.

The main reason not to propagate the original Identity Provider tokens is due to the following security concern: Each participant in the flow needs to be fully identifiable. Application doesn't know which Identity Provider was chosen and especially has no easy way to get the public signing keys to validate the received tokens. mimoto Tokens on the other hand can easily be verified and therefore ensure a completely secure data exchange chain.

Retrieving the list of available Identity Providers

The list of available Identity Providers can be retrieved via API, see for more details.

Authorization Code flow initialization

The default flow within the federation requires the user to first select the relevant target Identity Provider. If the target Identity Provider is already known in advance by the implementing application, the selection can be avoided and the required IDP provided as parameter. To provide additional parameters, the initialization call should look as follows:

authorization-code-flow-request&additional-parameters

E.g.: /connect/auth?client_id=your-client-id&redirect_uri=your-redirect-url&response_type=code&scope=your-scopes&state=your-state&code_challenge=your-code-challenge&code_challenge_method=S256&response_mode=query&provider=target-idp-issuer&language=requested-language

Available parameters

• provider (optional): Issuer from the list of available identity providers, e.g.: https://gsi.dev.gematik.solutions
• language (optional): Currently we support de_DE and en_GB

Need something else?

If further parameters are required or specific provider mappings needed, please don't hesitate to contact us.

Local Development

To simplify local development, mocked federation flows will be available. This means, that:

• Application can integrate normally via OIDC
• the target Identity Provider can be selected
• the actual login flow is mocked and a test token is automatically returned to the Application. This mode is only available with mimoto Tokens.

Local Development: App-App Flow

To properly test the App-App flow, we provide authenticator apps designed to support integration testing. The authenticator app is provided for Android and iOS. Please contact us for more information.

Relying Party configuration

The following parameters are configured by us for your Relying Party:

Name	(Possible/Example) Value(s)	Description
Short Key	e.g.: hokoku	As described above, this uniquely identifies your Application and is used to create an unique issuer for your Application within the federation.
AcrValues	e.g.: gematik-ehealth-loa-high	See default_acr_values on https://wiki.gematik.de/display/IDPKB/App-App+Flow
Scopes	e.g.: urn:telematik:versicherter openid	See available scopes on https://wiki.gematik.de/display/IDPKB/App-App+Flow
Organization	e.g.: azuma	Name of your company / organization
Member ID	e.g.: AZ12345	The Member-ID is issued by gematik per DiGA per environment and is required to send a new/updated registration request to gematik, which is also important for entity statement certificate rotation.
Relying Party Mode	Proxy Mode or Full Mode	See token storage explanation above
Federation Mode	Live or Simulation	Live denotes a full integration within the federation (login via selected IDP). Simulation is used for the initial setup or testing and simulates the login process by returning simulation tokens.
Include Original AccessToken	boolean, defaults to false	If true, adds the claim ext-mimoto-original-access-token to the Access Token containing the original token returned by the Identity Provider
Include Original IdentityToken	boolean, defaults to false	If true, adds the claim ext-mimoto-original-id-token to the ID Token containing the original token returned by the Identity Provider

The following parameters can be modified by you for your Relying Party:

Name	(Possible/Example) Value(s)	Description
Name	e.g. hokoku DiGA	Name of your DiGA, should reflect the name as added in DiGA Verzeichnis
Logo URI (Optional)	e.g.: https://docs.azuma-health.tech/img/logo-1.svg	Logo of your DiGA
Homepage URI (Optional)	e.g.: https://azuma.health/	Homepage of your DiGA
Contacts (Optional)	e.g.: support@azuma.health	Contacts of your DiGA

info

On the lower environments, you can have multiple relaying parties, e.g.:

1. used for live integration --> Federation Mode: Live
2. used for testing and local simulation --> Federation Mode: Simulation

Each Relying Party is always configured by us after the initial contract setup.

Application Configuration

Developer Portal

Application configurations can be done by the developers of a DiGA via our Developer Portal.

An Application identifies each registered client Application for the OpenID Connect Authorization Code flow. Each Application always belong to exactly one Relying Party, in turn each Relying Party can have more than one Application.

The definition of an Application consists of

Name	(Possible/Example) Value(s)	Description
Client ID	Guid identifying the client	Generated automatically
Client Secret	Only required if PKCE is not supported	Generated automatically if required
Display Name	e.g.: hokoku	Name identifying the Application
Redirect URLs	e.g.: https://oidcf-example.develop.azuma-health.tech	List of redirect URLs as required by the Application
Scopes	See Scopes definition of Relying Party.	This can be used to specify a subset of the Scopes defined in the Relying Party. Can be omitted, in which case all Scopes of the Relying Party are setup for the Application
Integration Mode	Web Application or Mobile Application	Web Application expects the default OpenID Connect Authorization Code redirect flow to be sufficient. Mobile Application integration requires a special App to App flow to be implemented as specified by gematik.
Mobile Application: Deep Link Url	e.g.: https://mimoto-example-app.azuma-health.tech/code/ce	Deep Link Url that is called from the IDP Authenticator Application. Important: Changes to this can take some time to be usuable in the federation environment. The main reason is, that this Deep Link Url needs to be published to the Entity Statement as a valid redirect URL. The Entity Statement is only queried by the Identity Providers once it expires. The current expiration time per environment is available below.
Use requested Redirect URI as deep link URL	Yes or no	For Mobile Flowonly: Allows to use the Redirect URLs as deep links instead of providing a static Deep Link Url
Error handling mode (Web-Application)	Default, Redirect to Auth or Redirect to Custom	In Default mode the integrated Error-UI screen of mimoto is displayed. In Redirect to Auth mode errors are redirected to the 'Redirect-URL' used in the Auth-Request in the following format: redirect-url?error=error. In Redirect to Custom mode errors are redirected to the 'Custom-URL' in the following format: custom-url?error=error
Sub mode	Default or Unique	In Default mode the value from IDP is propagated in the sub claim. In Unique mode the sub claim is enriched to become globally unique (by adding provider to the claim)
Layout	your defined layout	Allows to select a Layout that should be shown for the DiGA instead of the default layout
ACR Validation mode	None, High (Strict) or High (Relaxed)	The following options are available None: No validation is done in mimoto High (Strict): Only gematik-ehealth-loa-high is accepted in the acr-claim of the ID-Token. High (Relaxed): Accepted are one of the following options: gematik-ehealth-loa-high in the acr-claim or gematik-ehealth-loa-substantial in the acr-claim and urn:telematik:auth:mEW in the amr-claim (A_23202-01) In case of an validation error, a 403 error response is returned (e.g. during Token exchange) or an appropriate error message is displayed (e.g. during Web flow with the default redirect configuration).

Scope handling

Scopes handling is as follows:

1. Relying Party contains a definition of all scopes that can be requested by Applications.
2. Each Application defines a set of scopes specific to the application. This can either be the same or a subset of scopes of the Relying Party.
3. With each Authorization Code flow, the requested scopes can be further adjusted as needed, but need to be a subset of the Application.

This way, the usage of scopes can be specified as required the by the application context.

Avoiding Redirect on Auth-Url (for mobile App-App flow)

In the App-App flow it is important to avoid automatic redirect following (otherwise the IDP deep link will already be called once and that might lead to errors). Depending on the platform, it might not be easy to disable automatic redirect following (e.g. with fetch there is no way to disable that behavior).

Therefore, it is possible to request a response format in the auth call via query parameter response_format.

Possible values:

• redirect: response is the default redirect response (302)
• json: response is json (200) with payload looking like: {"url": "..."}

See e.g. our example: https://github.com/azuma-healthtech-public/mimoto-examples/blob/main/react-native-ce/lib/helpers/Api.ts#L38

Entity Statement expiration time

The current entity statement expiration time is

• RU: 30 Minutes
• TU: 30 Minutes
• PRD: 240 Minutes

Token introspection

Token introspection can be used to validate that a given token was issues by azuma mimoto.

To request an introspection, a special introspection client is required. You can create a new introspection client in mimoto dashboard und Applications.

Screenshot: Menu to create Introspection Client:

The introspection request looks as follows:

curl --location --request POST '*introspection-endpoint*' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=*your_token*' \
--data-urlencode 'client_id=*introspection-client-id*' \
--data-urlencode 'client_secret=*introspection-client-secret*'

Alternatively you could also use:

curl --location --request GET '*introspection-endpoint*?token=*your_token*' \
--header 'Authorization: Basic *introspection-client-id:introspection-client-secret*'

We allow introspection for both Access Token and ID Token.

Valid token response:

{
    "active": true,
    "iss": "*+issuer**",
    "sub": "**current**sub",
    "jti": "2c948e39-51c6-4bad-9025-f7297764e75a",
    "token_type": "Bearer",
    "token_usage": "access_token",
    "client_id": "bce63135-c5a2-4846-90ca-c0de2c2318e2",
    "iat": 1701270568,
    "nbf": 1701270568,
    "exp": 1701274168
}

Invalid token response:

{
    "active": false
}

See below for the actual URL of the introspection endpoint in the available environments.

Token content

azuma mimoto issues, as expected, an Access Token and an ID Token in reponse to the Code Exchange step in the Authorization Code flow.

In general, the original Claims as propagated from the Identity Provider except:

• iss
• aud
• iat
• exp

Those special Claims are required for token validation.

Sub-Claim

The provided sub claim is only unique within the Identity Provider, not across all Identity Providers. To ensure you have a unique ID, you can either concatenate as and sub claims or use ext-mimoto-original-sub-unique claim (see below).

Ext Claims: Access token

The following ext claims are available in Access Token

• ext-mimoto-original-access-token: Contains the original value as given by Identity Provider. This is included, if configured in Relying Party.

Ext Claims: ID token

• ext-mimoto-original-id-token: Contains the original value as given by Identity Provider. This is included, if configured in Relying Party.

Ext Claims: Access and ID token

• ext-mimoto-original-iss: Original Identity Provider issuer.
• ext-mimoto-original-sub-unique: Concatenated value of Identity Provider issuer and sub claim.

Developer Portal

Please see Developer Portal for more details.

Integration Examples

Please see Integration Examples for more details.

Infrastructural Environments Approach

The following stages of Environment are present on gematik side:

• TU (Testumgebung / testing environment): used to check test concepts as well as interface testing
• RU (Referenzumgebung /reference environment): used for integration testing
• PU (Produktivumgebung / productive environment): used for productive deployment

(See Federation Master Umgebungen)

We mirror those environments as follows:

TU / TEST

• Main Url: https://mimoto-test.pie.azuma-health.tech
• Dashboard Url: https://mimoto-dashboard-test.pie.azuma-health.tech
• Swagger: https://mimoto-test.pie.azuma-health.tech/swagger - contains
  • API to retrieve available IDPs
  • Exchange code api for mobile
• OpenID Configuration: https://mimoto-test.pie.azuma-health.tech/.well-known/openid-configuration
  • Authorization Endpoint: https://mimoto-test.pie.azuma-health.tech/connect/auth
  • Token Endpoint: https://mimoto-test.pie.azuma-health.tech/connect/token
  • Introspection Endpoint: https://mimoto-test.pie.azuma-health.tech/connect/introspection
  • JWKS Endpoint: https://mimoto-test.pie.azuma-health.tech/.well-known/jwks

RU / REF

• Main Url: https://mimoto-ref.pie.azuma-health.tech
• Dashboard Url: https://mimoto-dashboard-ref.pie.azuma-health.tech
• Swagger: https://mimoto-ref.pie.azuma-health.tech/swagger - contains
  • API to retrieve available IDPs
  • Exchange code api for mobile
• OpenID Configuration: https://mimoto-ref.pie.azuma-health.tech/.well-known/openid-configuration
  • Authorization Endpoint: https://mimoto-ref.pie.azuma-health.tech/connect/auth
  • Token Endpoint: https://mimoto-ref.pie.azuma-health.tech/connect/token
  • Introspection Endpoint: https://mimoto-ref.pie.azuma-health.tech/connect/introspection
  • JWKS Endpoint: https://mimoto-ref.pie.azuma-health.tech/.well-known/jwks

PU / PROD

• Main Url: https://mimoto.azuma-health.tech
• Dashboard Url: https://mimoto-dashboard.azuma-health.tech
• Swagger: https://mimoto.azuma-health.tech/swagger - contains
  • API to retrieve available IDPs
  • Exchange code api for mobile
• OpenID Configuration: https://mimoto.azuma-health.tech/.well-known/openid-configuration
  • Authorization Endpoint: https://mimoto.azuma-health.tech/connect/auth
  • Token Endpoint: https://mimoto.azuma-health.tech/connect/token
  • Introspection Endpoint: https://mimoto.azuma-health.tech/connect/introspection
  • JWKS Endpoint: https://mimoto.azuma-health.tech/.well-known/jwks

Error Handling

azuma mimoto provides errors as JSON (whenever possible) in the following format:

{
"error": "error code/id",
"error_description": "error description in english",
"error_uri": "error uri"
}

Example:

{
  "error": "IDM2003",
  "error_description": "The Relying Party 9b5972c5-0c1d-45b9-b177-81bcc10fbdf0 was not found.",
  "error_uri": "https://docs.azuma-health.tech/products/mimoto/error?code=IDM2003"
}

The documentation of all possible errors is on our roadmap and will be available soon.

Roadmap

Planned for Q4/2023

• Identity Provider UI: Optimizations including language selector.
• Integration examples

Planned for 2024

• Example applications and IDP mock apps for testing
• Advanced testing capabilities (including user selection and scope declining)
• Identity Provider UI: Rebranding (customization of layout, colors, texts)
• Event logs for Relying Party usage.
• Dashboard for Relying Party usage.
• DiGAs can modify Relying Party certain properties.
• Notifications
• ACR Validation mode
• ...

Ideas for 2025

• Interactive flow explaining how the Gesundheits-ID works
• Meta application support
• Integration into azuma Zero Trust approach.
• ...

Missing something on our roadmap?

If you require specific features that are currently missing on our roadmap, please don't hesitate to contact us.

Links

• gematik Documentation: https://wiki.gematik.de/pages/viewpage.action?pageId=510272126