Skip to main content

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 Keye.g.: hokokuAs described above, this uniquely identifies your Application and is used to create an unique issuer for your Application within the federation.
AcrValuese.g.: gematik-ehealth-loa-highSee default_acr_values on https://wiki.gematik.de/display/IDPKB/App-App+Flow
Scopese.g.: urn:telematik:versicherter openidSee available scopes on https://wiki.gematik.de/display/IDPKB/App-App+Flow
Organizatione.g.: azumaName of your company / organization
Relying Party ModeProxy Mode or Full ModeSee token storage explanation above
Federation ModeLive or SimulationLive 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 AccessTokenboolean, defaults to falseIf true, adds the claim ext-mimoto-original-access-token to the Access Token containing the original token returned by the Identity Provider
Include Original IdentityTokenboolean, defaults to falseIf true, adds the claim ext-mimoto-original-id-token to the ID Token containing the original token returned by the Identity Provider
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 IDGuid identifying the clientGenerated automatically
Client SecretOnly required if PKCE is not supportedGenerated automatically if required
Display Namee.g.: hokokuName identifying the Application
Redirect URLse.g.: https://oidcf-example.develop.azuma-health.techList of redirect URLs as required by the Application
ScopesSee 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 ModeWeb Application or Mobile ApplicationWeb 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 Urle.g.: https://mimoto-example-app.azuma-health.tech/code/ceDeep 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.

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​

RU / REF​

PU / PROD​

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)
  • Dashboard for Relying Party usage.
  • Notifications
  • Integration into azuma Zero Trust approach.
  • ...

Ideas for 2024​

  • Interactive flow explaining how the Gesundheits-ID works
  • Meta application support
  • ...
Missing something on our roadmap?

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