Skip to content

Latest commit

 

History

History
332 lines (282 loc) · 13.4 KB

FHIR_VZD_HOWTO_Authenticate.adoc

File metadata and controls

332 lines (282 loc) · 13.4 KB
Raw

FHIR VZD HOWTO Authenticate

gematik
Version: 1.0.1

Referencing:

gemILF_FHIR_VZD

Document history

Version
 Stand
 Chap./ Page
 Change reason, special instructions
 Editing

1.0.0

28.07.23

Initial document

gematik

1.0.1

25.08.23

Chap. 2.4

added chapter for owner auth

gematik
Table of Contents

1. Classification of the document

1.1. Objective

This document describes how the different authentication interfaces of the FHIR directory service can be used to obtain access_tokens.

1.2. Target group

The document is aimed at software developers who are involved in implementing a client of the FHIR directory service and need access_tokens to interact with the API.

1.3. Scope

Intellectual property/patent notice

The following specification was created by gematik solely from a technical point of view. In individual cases, it cannot be ruled out that the implementation of the specification will interfere with the technical property rights of third parties. It is solely up to the supplier or manufacturer to take suitable measures to ensure that the products and/or services offered by him on the basis of the specification do not infringe third-party property rights and, if necessary, to obtain the necessary permits/licenses from the property right holders concerned. In this respect, gematik GmbH assumes no liability whatsoever.

2. FHIRDirectoryAuthenticationAPIs

2.1. Authenticate for the search endpoint

To use the search endpoint, a corresponding access token from the FHIRDirectoryAuthorizationService must be available.

With the following procedure an access token can be obtained:

Get authentication methods supported by the Matrix homeserver

 curl -X GET "[Matrix homeserver url]/_matrix/client/v3/login"

The request returns the supported authentication methods

200
{
  "flows": [
    {
      "type": "m.login.password"
    },
    {
      "type": "m.login.application_service"
    },
    {
      "type": "uk.half-shot.msc2778.login.application_service"
    }
  ]
}

Perform login and get Matrix Access Token

The login operation depends from the selected authentication methods which can be dependent from the used environment.

curl -X POST "[Matrix homeserver url]/_matrix/client/v3/login" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{
  "type": "m.login.password",
  "user": "username",
  "password": "password of the user"
}
EOF

The request returns a matrix access_token

200
{
  "user_id": "username",
  "access_token": "syt_ZXR0cjAy_JVJehocKZFlYyRbtTdiz_18uj52",
  "home_server": "matix.home.server.de",
  "device_id": "ABCDEFGHIJ"
}
Search-Acccesstoken Flow

[01] Request a Matrix OpenID Token

curl -X POST "[Matrix homeserver url]/_matrix/client/v3/user/{user_id}/openid/request_token?access_token=syt_ZXR0cjAy_JVJehocKZFlYyRbtTdiz_18uj52" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{}
EOF

In this operation the "username" has to be replaced with the user_id received in the response above.
For the access_token parameter the access_token returned in the response above has to be used.

[02] The request returns a matrix access_token

200
{
  "access_token": "zbKsYFDoZBWcKJMylLjCcMcR",
  "token_type": "Bearer",
  "matrix_server_name": "matix.home.server.de",
  "expires_in": 3600
}

[03] Get the access token from the FHIR-Directory

curl -X GET "[FHIRbaseUrl]/tim-authenticate?mxId=matrix.dev.service-ti.de" \
    -H "X-Matrix-OpenID-Token: zbKsYFDoZBWcKJMylLjCcMcR"

For the X-Matrix-OpenID-Token parameter the access_token aquired by the "Request Matrix OpenID Token" operation has to be used.

[08] The request returns a access token from the FHIR-Directory

200
{
  "access_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.e2lzcyI6Imh0dHBzOi8vZmhpci1kaXJlY3RvcnktdGVzdC52emQudGktZGllbnN0ZS5kZS90aW0tYXV0aGVudGljYXRlIiwiYXVkIjoiaHR0cHM6Ly9maGlyLWRpcmVjdG9yeS10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlL3NlYWNoIiwic3ViIjoiQGFiY2RlOm1hdHJpeC5kZXYuc2VydmljZS10aS5kZSIsImlhdCI6MTY2NDEyMjY3MywiZXhwIjoxNjY0MjA5MDczfQ.CoTwrZmZJyfVYVJFD068QJNFo0YLemhfPVER_lW5h3MU2hgoiSj1lkD6yDHPDQAs4JJ6PlBWIUHtoGoYAwVOVw",
  "token_type": "bearer",
  "expires_in": 86400
}
Tip
 Please note, that this example access token has an invalid signature (sub claim anonymized).

The access token is a JWT with the following structure:

Header:
{
  "typ": "JWT",
  "alg": "ES256"
}

Payload:

{
 "iss": "https://fhir-directory-test.vzd.ti-dienste.de/tim-authenticate\",
 "aud": "https://fhir-directory-test.vzd.ti-dienste.de/seach",
 "sub": "@abcde:matrix.dev.service-ti.de",
 "iat": 1664122673,
 "exp": 1664209073
 }

Signature:
...

For search examples see: Search Examples

2.2. Authenticate for the provider API

To use the TIM-PROVIDER-API, a corresponding TIM-Provider-API Token is needed. The following sequence diagram shows the flow to obtain such a token

Search-Acccesstoken Flow

[01] With the following request a ti-provider-accesstoken can be obtained:
(The Authorization string contains the base64 encoded client credentials.)

 curl -X POST "[baseUrl]:9443/auth/realms/TI-Provider/protocol/openid-connect/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -H "Authorization: Basic VElNUHJvdmlkZXI6YjEyMzMxZTktYWJjZC00NTY3LTZhaWUtZGY4ZTY4Y2E0ZmZj=" \
      -d @- << EOF
grant_type=client_credentials
EOF

[03] The request returns a ti-provider-accesstoken.

{
 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMkJXT0w2dmN2QjluMjhnYVRwQ19fQllnXzI1aDljMkN2UGVXbmFGYUVNIn0.eyJqdGkiOiI5YjFkYjQ2ZC0yOThmLTQ0ZGItOTQ3ZC0wODdmYTNkYjQ2YzMiLCJleHAiOjE2Nzg4NjcwMjQsIm5iZiI6MCwiaWF0IjoxNjc4ODY2NzI0LCJpc3MiOiJodHRwOi8vYXV0aC10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlOjk0NDMvYXV0aC9yZWFsbXMvVEktUHJvdmlkZXIiLCJzdWIiOiI2MWJjODJiOC0yN2VlLTRkMDUtYTc0OC1iNmQ3Zjc4NDk4ZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJnZW1hdGlrIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjg4NTc4MDgtNWIyNS00NWJhLWIzMDEtOGVkYjQzNTA4Mzc4IiwiYWNyIjoiMSIsInNjb3BlIjoidGktcHJvdmlkZXIiLCJjbGllbnRJZCI6ImdlbWF0aWsiLCJjbGllbnRIb3N0IjoiMTcyLjI0LjQ2LjEwIiwiY2xpZW50QWRkcmVzcyI6IjE3Mi4yNC40Ni4xMCJ9.LUbOr4XlICADdYuyT_SgviTBdXkSKdXQ43Fnp9VF7lr71Zrf0ELWiXkr1SplrMUmJrrbff8SaEzZTyy9Fx32xFTJnkX_Dw3uugbWXcARC-895lotzJ1Je4CJZSNSUSv4m6e86M8L7dfXjXxrbPAh4hH8IFWpudgF0mPG12VQMhaupJu13o2gIzB1GL7dk567_RVWXML8hi4ib6DT5dgZjIHFKKSAeuw99Xq0m1XdkwPCL9t8aIemY9lShQ2obvj70C8jBaIjquNGAScIrn3oTTLXs54XBN-t839M5wU0fxpwwHhuaDpRF-uLmPdQA3zE7MCNJYXkzl9nWdh2dLD31w",
  "expires_in":300,
  "refresh_expires_in":1800,
  "refresh_token":
 "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwMjk2NzMzNC1hOGJhLTQyNWYtYWQyOC1jYzAyOWE4YThhZDAifQ.eyJqdGkiOiIxMGY4ZjAyNi1iMzA1LTRjYmMtOWU4Yi1hZWE5MWY0YTRiMTciLCJleHAiOjE2Nzg4Njg1MjQsIm5iZiI6MCwiaWF0IjoxNjc4ODY2NzI0LCJpc3MiOiJodHRwOi8vYXV0aC10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlOjk0NDMvYXV0aC9yZWFsbXMvVEktUHJvdmlkZXIiLCJhdWQiOiJodHRwOi8vYXV0aC10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlOjk0NDMvYXV0aC9yZWFsbXMvVEktUHJvdmlkZXIiLCJzdWIiOiI2MWJjODJiOC0yN2VlLTRkMDUtYTc0OC1iNmQ3Zjc4NDk4ZmIiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiZ2VtYXRpayIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6IjI4ODU3ODA4LTViMjUtNDViYS1iMzAxLThlZGI0MzUwODM3OCIsInNjb3BlIjoidGktcHJvdmlkZXIifQ.FlfHbsFoC26fcwVzsQ4-m_D7ZaKigWvP7We-X5IlBaA",
  "token_type":"bearer",
  "not-before-policy":0,
  "session_state":"28857808-5b25-45ba-b301-8edb43508378",
  "scope":"ti-provider"
}

[04] Exchange the ti-provider-accesstoken for the tim-providerAPI-accesstoken

curl -X GET "[baseUrl]/ti-provider-authenticate" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMkJXT0w2dmN2QjluMjhnYVRwQ19fQllnXzI1aDljMkN2UGVXbmFGYUVNIn0.eyJqdGkiOiI5YjFkYjQ2ZC0yOThmLTQ0ZGItOTQ3ZC0wODdmYTNkYjQ2YzMiLCJleHAiOjE2Nzg4NjcwMjQsIm5iZiI6MCwiaWF0IjoxNjc4ODY2NzI0LCJpc3MiOiJodHRwOi8vYXV0aC10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlOjk0NDMvYXV0aC9yZWFsbXMvVEktUHJvdmlkZXIiLCJzdWIiOiI2MWJjODJiOC0yN2VlLTRkMDUtYTc0OC1iNmQ3Zjc4NDk4ZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJnZW1hdGlrIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjg4NTc4MDgtNWIyNS00NWJhLWIzMDEtOGVkYjQzNTA4Mzc4IiwiYWNyIjoiMSIsInNjb3BlIjoidGktcHJvdmlkZXIiLCJjbGllbnRJZCI6ImdlbWF0aWsiLCJjbGllbnRIb3N0IjoiMTcyLjI0LjQ2LjEwIiwiY2xpZW50QWRkcmVzcyI6IjE3Mi4yNC40Ni4xMCJ9.LUbOr4XlICADdYuyT_SgviTBdXkSKdXQ43Fnp9VF7lr71Zrf0ELWiXkr1SplrMUmJrrbff8SaEzZTyy9Fx32xFTJnkX_Dw3uugbWXcARC-895lotzJ1Je4CJZSNSUSv4m6e86M8L7dfXjXxrbPAh4hH8IFWpudgF0mPG12VQMhaupJu13o2gIzB1GL7dk567_RVWXML8hi4ib6DT5dgZjIHFKKSAeuw99Xq0m1XdkwPCL9t8aIemY9lShQ2obvj70C8jBaIjquNGAScIrn3oTTLXs54XBN-t839M5wU0fxpwwHhuaDpRF-uLmPdQA3zE7MCNJYXkzl9nWdh2dLD31w"

[06] This request returns the tim-providerAPI-accesstoken.

{
 "access_token":
 "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL2ZoaXItZGlyZWN0b3J5LXRlc3QudnpkLnRpLWRpZW5zdGUuZGUvdGktcHJvdmlkZXItYXV0aGVudGljYXRlIiwiYXVkIjoiaHR0cHM6Ly9maGlyLWRpcmVjdG9yeS10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlL3RpbS1wcm92aWRlci1zZXJ2aWNlcyIsInN1YiI6ImdlbWF0aWsiLCJpYXQiOjE2Nzg4NzI5NjAsImV4cCI6MTY3ODk1OTM2MCwiY2xpZW50SWQiOiJnZW1hdGlrIn0.hZDJXa-l1OK_B2NE54znl5FYWa5mW01Fw7LOiDo2kNIJOx2HPDCnEqxixd-7m9L34wq8WE4qVaA9jB6BNwX7qw",
  "client_id":"gematik",
  "token_type":"bearer",
  "expires_in":86400
}

For provider api usage examples see: Provider Examples

2.3. Authenticate for the owner endpoint as an organization

To use the API operations, a corresponding TI-Provider API Token from the FHIRDirectoryAuthorizationService must be available.

With the following operation an access token can be obtained:

2.3.1. Authenticate with an RegService-OpenID-Token

One way to authenticate an organization is the possibility to exchange an RegService-OpenID-Token for an owneraccess-token.

The RegService-OpenID-Token must have the following structure:

RegService-OpenID-Token structure 
HEADER
{
  "alg": "BP256R1",
  "typ": "JWT"
  "x5c": [
     "<X.509 Sig-Cert, base64-encoded DER>"
 ]
}
PAYLOAD
{
  "sub": "1234567890",
  "iss": "<url des Registrierungs-Dienst-Endpunkts, über den das Token ausgestellt wurde>",
  "aud": "https://vzd-fhir-directory.vzd.ti-dienste.de/owner-authenticate",
  "professionOID": "<professionOID der Organisation>",
  "idNummer": "<telematikID der Organisation>",
  "iat": "1516239022",
  "exp": "1516239022"
}

The RegService-OpenID-Token can be exchanged for an owneraccess-token

curl -X GET "[baseUrl]/owner-authenticate" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiMkJXT0w2dmN2QjluMjhnYVRwQ19fQllnXzI1aDljMkN2UGVXbmFGYUVNIn0.eyJqdGkiOiI5YjFkYjQ2ZC0yOThmLTQ0ZGItOTQ3ZC0wODdmYTNkYjQ2YzMiLCJleHAiOjE2Nzg4NjcwMjQsIm5iZiI6MCwiaWF0IjoxNjc4ODY2NzI0LCJpc3MiOiJodHRwOi8vYXV0aC10ZXN0LnZ6ZC50aS1kaWVuc3RlLmRlOjk0NDMvYXV0aC9yZWFsbXMvVEktUHJvdmlkZXIiLCJzdWIiOiI2MWJjODJiOC0yN2VlLTRkMDUtYTc0OC1iNmQ3Zjc4NDk4ZmIiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJnZW1hdGlrIiwiYXV0aF90aW1lIjowLCJzZXNzaW9uX3N0YXRlIjoiMjg4NTc4MDgtNWIyNS00NWJhLWIzMDEtOGVkYjQzNTA4Mzc4IiwiYWNyIjoiMSIsInNjb3BlIjoidGktcHJvdmlkZXIiLCJjbGllbnRJZCI6ImdlbWF0aWsiLCJjbGllbnRIb3N0IjoiMTcyLjI0LjQ2LjEwIiwiY2xpZW50QWRkcmVzcyI6IjE3Mi4yNC40Ni4xMCJ9.LUbOr4XlICADdYuyT_SgviTBdXkSKdXQ43Fnp9VF7lr71Zrf0ELWiXkr1SplrMUmJrrbff8SaEzZTyy9Fx32xFTJnkX_Dw3uugbWXcARC-895lotzJ1Je4CJZSNSUSv4m6e86M8L7dfXjXxrbPAh4hH8IFWpudgF0mPG12VQMhaupJu13o2gIzB1GL7dk567_RVWXML8hi4ib6DT5dgZjIHFKKSAeuw99Xq0m1XdkwPCL9t8aIemY9lShQ2obvj70C8jBaIjquNGAScIrn3oTTLXs54XBN-t839M5wU0fxpwwHhuaDpRF-uLmPdQA3zE7MCNJYXkzl9nWdh2dLD31w"
RegService-OpenID-Token validation steps

  1. jwt structure must follow RFC7519 Validating a JWT

  2. validating certificate

    1. type is C.FD.SIG

    2. technical role is "oid_tim"

  3. validating the used algorithm(BP256R1) and the expiration time

  4. checking for existence of field idnummer containing the TelematikID

Optional and mandatory starting with FHIR VZD 1.2

  1. compare the signature certificate with the one handed over while registering for the provider services endpoint credentials

  2. OCSP check of the signature certificate

  3. validating signature certificate against the X.509-Root-CA certificate

2.4. Authenticate for the owner endpoint as an user

The user can authenticate himself by using his smartcard(HBA/SMC-B). The following diagram shows the interaction between a client, the Auth-Service of the VZD-FHIR Directory, a smartcard and the IDP.

Caution
 The diagramm displays the most important interaction parts. For detailed information on the checks performed by the IDP or the detailed smartcard interaction steps please consult the product specific specification.
owner-authenticate Flow