diff --git a/CHANGELOG.md b/CHANGELOG.md index e8177b9..49bbf05 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,10 +18,32 @@ The versioning policy of this project follows [Semantic Versioning v2.0.0][].
Table of Contents
    -
  1. Release 1.0.0
    2. +
  2. Release 3.0.0
    3. +
  3. Release 2.0.0
    4. +
  4. Release 1.0.0
+## Release 3.0.0 +Summary of changes in release 3.0.0 compared to 2.0.0: +1. added: + 1. interface "I_PoPP_CheckIn_AuthorizationServer.yaml" + 2. interface "I_PoPP_CheckIn_ResourceServer.yaml" + 3. claim "stpl" to object "ConnectorScenarioHeaders" + in interface "I_PoPP_Token_Generation.yaml" +2. removed + 1. removed property "x5c" for object "TokenHeaders" + in interface "I_PoPP_Token_Generation.yaml" + 2. removed property "pn" for object "TokenMessage" + in interface "I_PoPP_Token_Generation.yaml" + +## Release 2.0.0 +Summary of changes in release 2.0.0 compared to 1.0.0: +1. added: + 1. interface "I_PoPP_Token_Generation.yaml" +2. removed: + 1. outdated interface specification "scenario/Specification.md" + ## Release 1.0.0 First release with major version number greater than zero. diff --git a/README.md b/README.md index 3b035cc..0197836 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ See [ReleaseNotes.md](./ReleaseNotes.md) for all information regarding the See [CHANGELOG.md](./CHANGELOG.md) for information about changes. ## Folder Structure - +This project has the following folders: | Folder | Subfolder | Content | |:-------|-----------|--------------------------------------------------------| @@ -37,7 +37,6 @@ See [CHANGELOG.md](./CHANGELOG.md) for information about changes. If you want to contribute, please check our [CONTRIBUTING.md](./CONTRIBUTING.md). ## License - Copyright 2024 gematik GmbH Licensed under the Apache License, Version 2.0 (the "License"); you may not use diff --git a/ReleaseNotes.md b/ReleaseNotes.md index c023a3a..3fe7980 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -5,11 +5,20 @@
Table of Contents
    +
  1. Release 3.0.0
  2. Release 2.0.0
  3. Release 1.0.0
+## Release 3.0.0 +This release describes three interfaces: +1. I_PoPP_CheckIn_AuthorizationServer.yaml +2. I_PoPP_CheckIn_ResourceServer.yaml +3. I_PoPP_Token_Generation.yaml + +This release corresponds to the first version of gemSpec_PoPP_Service. + ## Release 2.0.0 This release describes the following interface which substitutes the interface from release 1.0.0: diff --git a/src/openapi/I_PoPP_CheckIn_AuthorizationServer.yaml b/src/openapi/I_PoPP_CheckIn_AuthorizationServer.yaml new file mode 100644 index 0000000..57add2f --- /dev/null +++ b/src/openapi/I_PoPP_CheckIn_AuthorizationServer.yaml @@ -0,0 +1,659 @@ +openapi: 3.1.0 +info: + title: PoPP-Service Authorization Server + description: | + This interface provides access to PoPP-Service Authorization Server. + Via this interface, client systems (PoPP-Modul) can carry out user + authentication with the eHealth-ID using the insured person's device + through the health insurance company's sectoral IDP. + The PoPP-Module receives an eHealth-ID-checked access token for access to the + PoPP-Service (Resource Server). + + This interface also describe user authentication via the insurer's + eHealth-Card during a mobile check-in (possibly via a smartphone). + The PoPP-Module receives an card-checked access token for access to the + PoPP-Service (Resource Server). + + **General conditions**:
+ For all operations if applicable: + - error responses may be extended by helpful information about the error + condition in _errorDetail_ + + **Prerequisites**:
+ For using eHealth-ID + - The sectoral IDP of health insurance is registered with the TI-Federation. + - The PoPP-Service Authorization Server is registered with the TI-Federation. + - The PoPP-Module is registered with PoPP-Service Authorization Server. + + For using electronic Health Card + - The PoPP-Module is registered with PoPP-Service Authorization Server + - The PoPP-Module can read public data from eHealth-Card + + **Retry interval**:
+ The following retry intervals are suggested in case of an error response:
+ - '500' Internal Error + - approx. 10 minutes + + contact: + name: gematik GmbH + url: 'https://www.gematik.de' + + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0' + + version: 1.0.0 + + # version history: + # ---------------- + # version 0.0.1 + # - initial version for review + # version 1.0.0 + # - first version for publication + +servers: +- url: https://popp-service.de + +tags: +- name: Authorization Health-ID + description: | + The insured person uses a device to authenticate himself to the health + insurance company's sectoral IDP (GesundheitsID). + The PoPP-Service Authorization Server must know the address of the IDP + (iss-idp) with which the insured person is registered. + For this reason, it is possible to view a list of registered IDPs + (insurance companies) on PoPP-Modul. + If the PoPP-Service Authorization Server does not know the IDP address of + the calling PoPP-Modul, the insured person SHALL select their health + insurance company in the PoPP-Modul. + + Authenticating a user against the IDP is a task of the authenticator + belonging to the IDP on the insured person’s device. + + A successful login provides an PoPP-Module access token and causes an + authorized user allowing access to the protected resource (PoPP-Service) + to get a TAN-Set. + +- name: Authorization eHealth-Card + description: | + The insured person uses his eHealth-Card for validation. + The PoPP-Service Authorization Server generate an card-communication + access token. + PoPP-Module use card-communication access token for communication with + PoPP-Service to read data from eHealth-Card. + + A successful evaluation of eHealth-Card data provides a TAN-Set. + +externalDocs: + description: 'Specification: gemSpec_PoPP_Service, gemSpec_PoPP_Modul' + url: https://gemspec.gematik.de/docs/gemSpec/ + +paths: + /popp/patient/api/auth/v1/authorization-request-healthid: + parameters: + - $ref: '#/components/parameters/useragent' + post: + tags: + - Authorization Health-ID + operationId: sendAuthorizationRequestGid + summary: Send authorization request for authentication with eHealth-ID + description: | + Sends an authorization request to the authorization service for + authentication with eHealth-ID. + + **Client**:
+ A registered PoPP-Module SHALL send an OAuth-compliant request to the + PoPP-Service Authorization Server. + To defend against attacks, the PoPP-Module SHALL use pkce + (Proof Key for Code Exchange). + The code challenge method (code_challenge_method) SHALL be “S256”. + The response type (response_type) SHALL be "code".
+ + **Provider**:
+ The PoPP-Service Authorization Server SHALL send a pushed authorization + request (PAR) to the IDP + (see: gemSpec_IDP_Sek, table "Parameter Pushed Authorization Request"). + To defend against attacks, the PoPP-Service Authorization Server SHALL + use pkce (Proof Key for Code Exchange) too. + The code challenge method (code_challenge_method) SHALL be “S256”. + The response type (response_type) SHALL be "code". + It is necessary to generate and propagate a "nonce" parameter. + The acr-value in the PAR SHALL be "gematik-ehealth-loa-high", the + scope parameter used in the PAR SHALL be "urn:telematik:versicherter". + + The authorization server state value and clientid used for the PAR SHALL + occur in the URI-PAR response of the IDP. + After successful authentication PoPP-Service Authorization Server + creates an authorization code for the calling PoPP-Modul. + + | Conditions | Status code | Error code | Remarks | + |-------------------------------|-------------|------------------|-----------------------------------------------------------------| + | Successful operation | 200 | successful | | + | Request does not match schema | 400 | malformedRequest | | + | clientid value mismatch | 403 | invalData | PoPP-Service Authorization Server didn't know clientid value | + | Invalid URI (idp-iss) | 404 | noResource | uri for idp do not exist or ist not registered on TI-Federation | + | Any other error | 500 | internalError | | + + + requestBody: + description: | + Authorization Request is an OAuth compliant request using + Proof Key for Code Exchange by OAuth Public Clients + (see https://datatracker.ietf.org/doc/html/rfc763). + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationRequestGidSchema' + + responses: + '200': + $ref: '#/components/responses/AuthorizationResponse200' + '400': + $ref: '#/components/responses/Error400BadRequest' + '403': + $ref: '#/components/responses/Error403Forbidden' + '404': + $ref: '#/components/responses/Error404NotFound' + '500': + $ref: '#/components/responses/Error500InternalError' + + /popp/patient/api/auth/v1/authorization-request-ehc: + parameters: + - $ref: '#/components/parameters/useragent' + post: + tags: + - Authorization eHealth-Card + operationId: sendAuthorizationRequestEHC + summary: Send authorization request for authentication with eHealth-Card + description: | + Sends an authorization request to the authorization service with + information from eHealth-Card of the insured person. + + **Client**:
+ A registered PoPP-Module SHALL send an OAuth-compliant request to the + PoPP-Service Authorization Server. + To defend against attacks, the PoPP-Module SHALL use pkce + (Proof Key for Code Exchange). + The code challenge method (code_challenge_method) SHALL be “S256”. + The response type (response_type) SHALL be "code".
+ + **Provider**:
+ The PoPP-Service Authorization Server creates an access token + (card-communication access token). + The card-communication access token is signed with a key which was + published in entity statement of PoPP-Service Authorization Server. + The PoPP-Module uses the card-communication access token to get access + to the PoPP-Service for creating a direct communication channel + between eHealth-Card and PoPP-Service. + + After creating a card-communication access token the + PoPP-Service Authorization Server creates an authorization code + for the calling PoPP-Modul. + + | Conditions | Status code | Error code | Remarks | + |-------------------------------|-------------|------------------|--------------------------------------------------------------| + | Successful operation | 200 | successful | | + | Request does not match schema | 400 | malformedRequest | | + | clientid value mismatch | 403 | invalData | PoPP-Service Authorization Server didn't know clientid value | + | Any other error | 500 | internalError | | + + + requestBody: + description: | + Authorization Request is an OAuth complaint request using + Proof Key for Code Exchange by OAuth Public Clients + (see https://datatracker.ietf.org/doc/html/rfc763). + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationRequestEHCSchema' + + responses: + '200': + $ref: '#/components/responses/AuthorizationResponse200' + '400': + $ref: '#/components/responses/Error400BadRequest' + '403': + $ref: '#/components/responses/Error403Forbidden' + '500': + $ref: '#/components/responses/Error500InternalError' + + /popp/patient/api/token/v1/token-request-healthid: + parameters: + - $ref: '#/components/parameters/useragent' + post: + tags: + - Authorization Health-ID + operationId: sendAuthCodeHealthId + summary: Send token request to obtain an healthId-checked access token from PoPP-Service Authorization Server + description: | + Sends a token request to the PoPP-Service Authorization Server. + + **Client**:
+ A registered PoPP-Module SHALL send token request to the + PoPP-Service Authorization Server to get an access token. + The parameter grand type (grant_type) SHALL be "authorization_code".
+ + **Provider**:
+ The PoPP-Service Authorization Server checks the authorization code and + the code verifier. + Depending on the authorization code the PoPP-Service Authorization Server + sends a PoPP-Module access token to the PoPP-Modul. + + | Conditions | Status code | Error code | Remarks | + |----------------------------------------------------------|-------------|------------------|-----------------------------------------------------------------------------------| + | Successful operation | 200 | successful | | + | Request does not match schema | 400 | malformedRequest | | + | mismatch authorization code or code verifier or clientId | 403 | invalData | PoPP-Service Authorization Server didn't know clientid value or pkce proof failed | + | Any other error | 500 | internalError | | + + requestBody: + description: | + Token Request is an OAuth complaint request using Proof Key for + Code Exchange by OAuth Public Clients + (see https://datatracker.ietf.org/doc/html/rfc763). + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TokenRequestHealthIdSchema' + + responses: + '200': + $ref: '#/components/responses/TokenResponseHealthId200' + '400': + $ref: '#/components/responses/Error400BadRequest' + '403': + $ref: '#/components/responses/Error403Forbidden' + '500': + $ref: '#/components/responses/Error500InternalError' + + /popp/patient/api/token/v1/token-request-ehc: + parameters: + - $ref: '#/components/parameters/useragent' + post: + tags: + - Authorization eHealth-Card + operationId: sendAuthCodeEHC + summary: Send token request to obtain an card-checked access token from PoPP-Service Authorization Server + description: | + Sends an token request to the PoPP-Service Authorization Server. + + **Client**:
+ A registered PoPP-Module SHALL send token request to the + PoPP-Service Authorization Server to get an access token. + The parameter grand type (grant_type) SHALL be "authorization_code".
+ + **Provider**:
+ The PoPP-Service Authorization Server checks the authorization code + and the code verifier. + Depending on the authorization code the PoPP-Service Authorization Server + sends a card-communication access token or a PoPP-Module access token to + the PoPP-Modul. + + | Conditions | Status code | Error code | Remarks | + |---------------------------------------------------------|-------------|------------------|-----------------------------------------------------------------------------------| + | Successful operation | 200 | successful | | + | Request does not match schema | 400 | malformedRequest | | + | mismatch authorizationcode or code verifier or clientId | 403 | invalData | PoPP-Service Authorization Server didn't know clientid value or pkce proof failed | + | Any other error | 500 | internalError | | + + requestBody: + description: | + Token Request is an OAuth complaint request using Proof Key for + Code Exchange by OAuth Public Clients + (see https://datatracker.ietf.org/doc/html/rfc763). + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TokenRequestEHCSchema' + + responses: + '200': + $ref: '#/components/responses/TokenResponseEHC200' + '400': + $ref: '#/components/responses/Error400BadRequest' + '403': + $ref: '#/components/responses/Error403Forbidden' + '500': + $ref: '#/components/responses/Error500InternalError' + +components: + parameters: + useragent: + name: x-useragent + in: header + description: user agent information + required: true + schema: + $ref: '#/components/schemas/UserAgentSchema' + + responses: + AuthorizationResponse200: + description: HttpStatus.OK (200) + content: + application/json: + schema: + $ref: '#/components/schemas/AuthorizationResponse200Schema' + + TokenResponseHealthId200: + description: | + A JSON Web Token (JWT), healthId-checked access token for access to the + PoPP-Service, with the following format according to RFC-7515:
+ base64url (protected_header) + '.' + base64url (payload) + '.' + base64url (signature)"
+ Content for device attestation:
+ - protected_header contains: + - "typ": "JWT" + - "alg": "ES256" + - payload claims: + - "iat": issued at timestamp + - "exp": expiry timestamp (always iat + 120 min) + - "idNummer": KVNR + - "organizationID": IK-Nummer + - "telematikId": Telematik-ID of an eHealth institution + - "poppfdv": Information about registered PoPP-Modul + - "shortTan": false (default), set to true when short TAN needed + - signature contains token signature + content: + application/jwt: + schema: + $ref: '#/components/schemas/TokenResponseHealthId200Schema' + example: + - eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIng1YyI6ImNlcnRpZmljYXRlIGMuZmQuc2lnIn0.eyJhY3RvcklkIjoiQTEyMzQ1Njc4OSIsICJpYXQiOjE3MzY4OTkyMDAsImV4cCI6MTczNjkwNjQwMH0.e3NpZ25hdHVyZU92ZXJIZWFkZXJBbmRQYXlsb2FkfQ + + TokenResponseEHC200: + description: | + A JSON Web Token (JWT), card-checked access token for access to the + PoPP-Service, with the following format according to RFC-7515:
+ base64url (protected_header) + '.' + base64url (payload) + '.' + base64url (signature)"
+ Content for device attestation:
+ - protected_header contains: + - "typ": "JWT" + - "alg": "ES256" + - payload claims: + - "iat": issued at timestamp + - "exp": expiry timestamp (always iat + 120 min) + - "telematikId": Telematik-ID of an eHealth institution + - "poppmodul": Information about registered PoPP-Modul + - "shortTan": false (default), set to true when short TAN needed + - signature contains token signature + content: + application/jwt: + schema: + $ref: '#/components/schemas/TokenResponseEHC200Schema' + example: + - eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIng1YyI6ImNlcnRpZmljYXRlIGMuZmQuc2lnIn0.eyJhY3RvcklkIjoiQTEyMzQ1Njc4OSIsICJpYXQiOjE3MzY4OTkyMDAsImV4cCI6MTczNjkwNjQwMH0.e3NpZ25hdHVyZU92ZXJIZWFkZXJBbmRQYXlsb2FkfQ + + Error400BadRequest: + description: HttpStatus.BAD_REQUEST (400) + content: + application/json: + example: + errorCode: malformedRequest + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error401UnauthorizedError: + description: HttpStatus.Unauthorized (401) + content: + application/json: + example: + errorCode: unauthorized + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error403Forbidden: + description: HttpStatus.FORBIDDEN (403) + content: + application/json: + example: + errorCode: invalAuth + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error404NotFound: + description: HttpStatus.NOT_FOUND (404) + content: + application/json: + example: + errorCode: noResource + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error409Conflict: + description: HttpStatus.CONFLICT (409). + content: + application/json: + example: + errorCode: statusMismatch + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error500InternalError: + description: HttpStatus.INTERNAL_SERVER_ERROR (500) + content: + application/json: + example: + errorCode: internalError + schema: + $ref: '#/components/schemas/ErrorSchema' + + schemas: + UserAgentSchema: + description: | + Information about client software with: + ClientId(20 characters) + / + VersionNumber (1 to 15 characters). + type: string + pattern: '^[a-zA-Z0-9\-]{1,20}\/[a-zA-Z0-9\-\.]{1,15}$' + examples: ["CLIENTID1234567890AB/2.1.12-45"] + + AuthorizationRequestGidSchema: + description: | + PoPP-Module sends an oauth-complaint authorization request with pkce + type: object + properties: + issidp: + description: | + The issuer identifier (URL) of the IDP used for user authentication + type: string + examples: ["https://idp_kk.de"] + clientId: + description: | + Identifier of the application registered on + PoPP-Service Authorization Server + type: string + examples: ["myApplicationPoPPFdV"] + state: + description: | + Necessary security parameter, see + https://datatracker.ietf.org/doc/html/rfc8252#section-8.9 + type: string + examples: ["myPoPPFdVGeneratedState"] + redirect_uri: + description: | + Destination URL for the authorization code. + The application needs to send the authorization code to the + PoPP-Service Authorization Server. + The PoPP-Service Authorization Server exchanges the authorization + code to an access token. + type: string + examples: ["https://myApplication.de"] + code_challenge: + description: | + see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 + type: string + examples: ["K2-mvd94bdd5i1d0x7FTD_sFNRK4cxx-vDIbpfL2u9W"] + code_challenge_method: + description: | + see https://datatracker.ietf.org/doc/html/rfc7636#section-4.3 + type: string + examples: ["S256"] + response_type: + description: | + PoPP-Module will get an authorization code, and will exchange this + code for an access token. + type: string + examples: ["code"] + telematikId: + description: | + PoPP-Module indicates the request for a LEI-specific TAN by including this optional parameter in the Request. If this parameter is absent in the request, only long TAN without LEI specificity are requested. + type: string + examples: ["1234567890"] + + AuthorizationResponse200Schema: + description: | + Authorization code issued by the PoPP-Service Authorization Server + type: object + properties: + code: + description: authorization code + type: string + examples: ["authorization code"] + state: + description: | + The status SHALL be exactly the same as what the PoPP-Module sent in + the authorization request + (see https://datatracker.ietf.org/doc/html/rfc8252#section-8.9) + type: string + examples: ["myPoPPFdVGeneratedState"] + + AuthorizationRequestEHCSchema: + description: | + PoPP-Module sends an oauth-complaint authorization request with pkce + type: object + properties: + cvcehc: + description: cvc read from eHealth-Card of the insurend person + type: string + cauthehc: + description: c.aut read from eHealth-Card of the insurend person + type: string + clientId: + description: | + Identifier of the application registered on + PoPP-Service Authorization Server + type: string + examples: ["myApplicationPoPPFdV"] + state: + description: | + Necessary security parameter, + see https://datatracker.ietf.org/doc/html/rfc8252#section-8.9 + type: string + examples: ["myPoPPFdVGeneratedState"] + redirect_uri: + description: | + Destination URL for the authorization code. + The authorization code is used to redeem against an access token + used in the PoPP-Service Authorization Server. + type: string + examples: ["https://myApplication.de"] + code_challenge: + description: | + see https://datatracker.ietf.org/doc/html/rfc7636#section-4.2 + type: string + examples: ["K2-mvd94bdd5i1d0x7FTD_sFNRK4cxx-vDIbpfL2u9W"] + code_challenge_method: + description: | + see https://datatracker.ietf.org/doc/html/rfc7636#section-4.3 + type: string + examples: ["S256"] + response_type: + description: | + PoPP-Module will get an authorization code, and will + exchange this code against an access token. + type: string + examples: ["code"] + telematikId: + description: | + PoPP-Module indicates the request for a LEI-specific TAN by including this optional parameter in the Request. If this parameter is absent in the request, only long TAN without LEI specificity are requested. + type: string + examples: ["1234567890"] + + TokenRequestHealthIdSchema: + description: | + PoPP-Module sends an oauth-complaint token request with pkce + type: object + properties: + grant_type: + description: grant type + type: string + examples: ["authorization_code"] + code: + description: authorization code + type: string + examples: ["autorization code"] + code_verifier: + description: | + pkce code verifier + (see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) + type: string + clientId: + description: | + Identifier of the application registered on + PoPP-Service Authorization Server + type: string + examples: ["myApplicationPoPPFdV"] + redirect_uri: + description: Destination URL for the access token. + type: string + examples: ["https://myApplication.de"] + + TokenResponseHealthId200Schema: + type: object + properties: + jwt: + type: string + format: application/jwt + pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' + + TokenRequestEHCSchema: + description: PoPP-Module sends an oauth-complaint token request with pkce + type: object + properties: + grant_type: + description: grant type + type: string + examples: [authorization_code] + code: + description: authorization code + type: string + examples: ["cardcommunication_autorizationcode"] + code_verifier: + description: | + pkce code verifier + (see https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) + type: string + clientId: + description: | + Identifier of the application registered on + PoPP-Service Authorization Server + type: string + examples: ["myApplicationPoPPFdV"] + redirect_uri: + description: Destination URL for the access token. + type: string + examples: ["https://myApplication.de"] + + TokenResponseEHC200Schema: + type: object + properties: + jwt: + type: string + format: application/jwt + pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' + + ErrorSchema: + description: Error object with additional information about the occurred error + type: object + properties: + errorCode: + description: Error condition specifier + type: string + errorDetail: + description: Additional details regarding the error condition (if applicable) + type: string + required: + - errorCode diff --git a/src/openapi/I_PoPP_CheckIn_ResourceServer.yaml b/src/openapi/I_PoPP_CheckIn_ResourceServer.yaml new file mode 100644 index 0000000..6117583 --- /dev/null +++ b/src/openapi/I_PoPP_CheckIn_ResourceServer.yaml @@ -0,0 +1,354 @@ +openapi: 3.1.0 +info: + title: PoPP-Service Resource Server for 3rd party applications + description: | + This interface provides access to PoPP-Service Resource Server for applications. + Via this interface, client systems that implement a PoPP-Modul + can carry out TAN generation. + The client system receives TAN which can be presented at a practitioner system + to exchange the TAN for a PoPP-Token. + + This interface describe the request of TANs. + The client system utilizes an access token to gain access to the + PoPP-Service (resource server). + + + **General conditions**:
+ For all operations if applicable: + - error responses may be extended by helpful information about the error + condition in _errorDetail_ + + **Prerequisites**:
+ - The sectoral IDP of health insurance is registered with the TI-Federation. + - The PoPP-Service Authorization Server is registered with the TI-Federation. + - The client system is registered with the PoPP-Service Authorization Server. + - The client system received an access token from the + PoPP-Service Authorization Server. + + + contact: + name: gematik GmbH + url: 'https://www.gematik.de' + + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0' + + version: 1.0.0 + + # version history: + # ---------------- + # version 0.0.1 + # - initial version for review + # version 1.0.0 + # - first version for publication + +servers: +- url: https://popp-service.de + +tags: +- name: Authorization Health-ID + description: | + The insured person uses a device to authenticate himself to the health + insurance company's sectoral IDP (GesundheitsID). + The PoPP-Service Authorization Server must know the address of the IDP + (iss-idp) with which the insured person is registered. + For this reason, it is possible to view a list of registered IDPs + (insurance companies) on PoPP-Modul. + If the PoPP-Service Authorization Server does not know the IDP address of + the calling PoPP-Modul, the insured person SHALL select their health + insurance company in the PoPP-Modul. + + Authenticating a user against the IDP is a task of the authenticator + belonging to the IDP on the insured person’s device. + + Using an access token a PoPP-Module enables an authorized user accessing + the protected resource (PoPP-Service) to get a TAN-Set. + + A TAN is presented to the IT-System of a practitioner as affirmative action + of the insured person authorizing the health care professional to access + care relevant data of the insured person. + +- name: Authorization eHealth-Card + description: | + The insured person uses his eHealth-Card for validation. + The PoPP-Service Authorization Server generate an card-communication + access token. + PoPP-Module use card-communication access token for communication with + PoPP-Service to read data from eHealth-Card. + + A successful evaluation of eHealth-Card data provides a TAN-Set. + +externalDocs: + description: 'Specification: gemSpec_PoPP_Service, gemSpec_PoPP_Modul' + url: https://gemspec.gematik.de/docs/gemSpec/ + +paths: + /popp/patient/api/tan/v1/tan-request-healthid: + parameters: + - $ref: '#/components/parameters/useragent' + post: + tags: + - Authorization Health-ID + operationId: generateTAN2KVNR + summary: Send request to obtain a TAN or TAN-Set. + description: | + Sends a request to the PoPP-Service Resource Server. + + **Client**:
+ A registered PoPP-Module sends a request to the + PoPP-Service Resource Server to get a TAN or a TAN-Set. + The authorization SHALL be "eHealth-ID-check" Access Token.
+ + **Provider**:
+ The PoPP-Service Resource Server checks the "eHealth-ID-check" Access-Token. + The PoPP-Service Resource Server uses information from the Access-Token + to create an TAN-Set-Record. + Depending on the information from the Access-Token the + The PoPP-Service Resource Server creates a "short" TAN, or a "long" TAN + or a TAN-Set with more then one "long" TAN. + Additionally, the PoPP-Service Resource Server timestamps "iat" and "exp" + for the validity period of the TAN/TAN-Set-Record. + + | Conditions | Status code | Error code | Remarks | + |-----------------------------------------|-------------|------------------|---------------------------------------------------------------------------| + | Successful operation | 200 | successful | | + | Request does not match schema | 400 | malformedRequest | | + | "eHealth-ID-check" Access Token invalid | 401 | unauthorized | PoPP-Service Resource Server does not accept the Access-Token | + | "eHealth-ID-check" Access Token missing | 403 | invalAuth | PoPP-Service Resource Server does not accept request without Access-Token | + | Any other error | 500 | internalError | | + + responses: + '200': + $ref: '#/components/responses/TanResponseHealthId200' + '400': + $ref: '#/components/responses/Error400BadRequest' + '401': + $ref: '#/components/responses/Error401UnauthorizedError' + '500': + $ref: '#/components/responses/Error500InternalError' + + security: + - bearerAuthHealtId: [] + + /popp/patient/api/tan/v1/tan-request-ehc: + parameters: + - $ref: '#/components/parameters/useragent' + post: + tags: + - Authorization eHealth-Card + operationId: generateTAN2EHCCheck + summary: Send request to check the eHealth-Card and obtain a TAN. + description: | + Sends a request to the PoPP-Service Resource Server. + + **Client**:
+ A registered PoPP-Module sends a request to the PoPP-Service Resource + Server to get a TAN after checking the eHealth-Card. + The authorization must be "card-check" Access Token.
+ + **Provider**:
+ The PoPP-Service Resource Server checks the "card-check" Access Token. + The PoPP-Service Resource Server verifies the eHealth-Card by communicating + with the card. + The PoPP-Service Resource Server uses information from the card to create + an TAN-Set-Record. + Depending on the information from the Access-Token the PoPP-Service + Resource Server create a "short" TAN or a "long" TAN. + Additionally, the PoPP-Service Resource Server timestamps "iat" and "exp" + for the validity period of the TAN. + + | Conditions | Status code | Error code | Remarks | + |-------------------------------------|-------------|------------------|---------------------------------------------------------------------------| + | Successful operation | 200 | successful | | + | Request does not match schema | 400 | malformedRequest | | + | "card-check" Access Token not valid | 401 | unauthorized | PoPP-Service Resource Server does not accept the Access-Token | + | "card-check" Access Token missing | 403 | invalAuth | PoPP-Service Resource Server does not accept request without Access-Token | + | Any other error | 500 | internalError | | + + responses: + '200': + $ref: '#/components/responses/TanResponseHealthId200' + '400': + $ref: '#/components/responses/Error400BadRequest' + '401': + $ref: '#/components/responses/Error401UnauthorizedError' + '500': + $ref: '#/components/responses/Error500InternalError' + + security: + - bearerAuthEHC: [] + +components: + parameters: + useragent: + name: x-useragent + in: header + description: user agent information + required: true + schema: + $ref: '#/components/schemas/UserAgentSchema' + + responses: + TanResponseHealthId200: + description: | + A JSON Web Token (JWT) with the following format according to RFC-7515:
+ base64url (protected_header) + '.' + base64url (payload) + '.' + base64url (signature)"
+ Content for device attestation:
+ - protected_header contains: + - "typ": "JWT" + - "alg": "ES256" + - payload claims: contain tans and a hint for processing - structure of payload is defined by TanResponsePayloadSchema + - tans: + - iat: 1736899200 + tan: 123456...40 + - iat: 1736899201 + tan: 223456...40 + - hint: + - code: xyz + - description: maxTAN is exceeded, therefore less TANs than requested are returned + + - signature contains signature of the PoPP-Service Resource Server + content: + application/jwt: + schema: + $ref: '#/components/schemas/TanResponseHealthId200Schema' + example: + - eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIng1YyI6ImNlcnRpZmljYXRlIGMuZmQuc2lnIn0.eyJ0YW5zIjpbeyJpYXQiOjE3MzY4OTkyMDAsInRhbiI6IjEyMzQ1Ni4uLjQwIn0seyJpYXQiOjE3MzY4OTkyMDEsInRhbiI6IjIyMzQ1Ni4uLjQwIn1dLCJoaW50Ijp7ImNvZGUiOiJ4eXoiLCJkZXNjcmlwdGlvbiI6Im1heFRBTiBpcyBleGNlZWRlZCwgdGhlcmVmb3JlIGxlc3MgVEFOcyB0aGFuIHJlcXVlc3RlZCBhcmUgcmV0dXJuZWQifX0.e3NpZ25hdHVyZU92ZXJIZWFkZXJBbmRQYXlsb2FkfQ + + TanResponseEHC200: + description: | + A JSON Web Token (JWT) with the following format according to RFC-7515:
+ base64url (protected_header) + '.' + base64url (payload) + '.' + base64url (signature)"
+ Content for device attestation:
+ - protected_header contains: + - "typ": "JWT" + - "alg": "ES256" + - payload claims: contain tans and a hint for processing - structure of payload is defined by TanResponsePayloadSchema + - tans: + - iat: 1736899200 + tan: 123456...40 + - iat: 1736899201 + tan: 223456...40 + - hint: + - code: xyz + - description: maxTAN is exceeded, therefore less TANs than requested are returned + - signature contains signature of the PoPP-Service Resource Server + content: + application/jwt: + schema: + $ref: '#/components/schemas/TanResponseEHC200Schema' + example: + - eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsIng1YyI6ImNlcnRpZmljYXRlIGMuZmQuc2lnIn0.eyJ0YW5zIjpbeyJpYXQiOjE3MzY4OTkyMDAsInRhbiI6IjEyMzQ1Ni4uLjQwIn0seyJpYXQiOjE3MzY4OTkyMDEsInRhbiI6IjIyMzQ1Ni4uLjQwIn1dLCJoaW50Ijp7ImNvZGUiOiJ4eXoiLCJkZXNjcmlwdGlvbiI6Im1heFRBTiBpcyBleGNlZWRlZCwgdGhlcmVmb3JlIGxlc3MgVEFOcyB0aGFuIHJlcXVlc3RlZCBhcmUgcmV0dXJuZWQifX0.e3NpZ25hdHVyZU92ZXJIZWFkZXJBbmRQYXlsb2FkfQ + + Error400BadRequest: + description: HttpStatus.BAD_REQUEST (400) + content: + application/json: + example: + errorCode: malformedRequest + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error401UnauthorizedError: + description: HttpStatus.Unauthorized (401) + content: + application/json: + example: + errorCode: unauthorized + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error403Forbidden: + description: HttpStatus.FORBIDDEN (403) + content: + application/json: + example: + errorCode: invalAuth + schema: + $ref: '#/components/schemas/ErrorSchema' + + Error500InternalError: + description: HttpStatus.INTERNAL_SERVER_ERROR (500) + content: + application/json: + example: + errorCode: internalError + schema: + $ref: '#/components/schemas/ErrorSchema' + + schemas: + UserAgentSchema: + description: | + Information about client software with: + ClientId(20 characters) + / + VersionNumber (1 to 15 characters). + type: string + pattern: '^[a-zA-Z0-9\-]{1,20}\/[a-zA-Z0-9\-\.]{1,15}$' + examples: ["CLIENTID1234567890AB/2.1.12-45"] + + TanResponsePayloadSchema: + description: | + structure returned in tan responses to convey tans and processing hint to the requestor + type: object + properties: + tans: + type: array + items: + type: object + properties: + iat: + type: number + tan: + type: string + hint: + type: object + properties: + code: + type: string + description: + type: string + + + + TanResponseHealthId200Schema: + type: object + properties: + jwt: + type: string + format: application/jwt + pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' + + TanResponseEHC200Schema: + type: object + properties: + jwt: + type: object + format: application/jwt + pattern: '^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$' + + ErrorSchema: + description: | + Error object with additional information about the occurred error + type: object + properties: + errorCode: + description: Error condition specifier + type: string + errorDetail: + description: | + Additional details regarding the error condition (if applicable) + type: string + required: + - errorCode + + securitySchemes: + bearerAuthHealtId: + description: eHealth-ID-check Access-Token + type: http + scheme: bearer + bearerFormat: JWT + bearerAuthEHC: + description: card-check Access-Token + type: http + scheme: bearer + bearerFormat: JWT diff --git a/src/openapi/I_PoPP_Token_Generation.yaml b/src/openapi/I_PoPP_Token_Generation.yaml index 0f54170..865410f 100644 --- a/src/openapi/I_PoPP_Token_Generation.yaml +++ b/src/openapi/I_PoPP_Token_Generation.yaml @@ -162,7 +162,7 @@ components: description: | An integer in range [0, 32767] indicating the time span in milliseconds for the PoPP-Service between receiving a - "ScenarioResultMessage" till the (expected) send time of the next + "ScenarioResponseMessage" till the (expected) send time of the next "StandardScenarioMessage" or "ConnectorScenarioMessage". A Connector or client uses this information to detect a timeout. The special value "timeSpan=0" indicates that this is the last @@ -254,10 +254,16 @@ components: End entity X.509 certificate with the signature verification key. Certificates are encoded in DER and base64 encoded as described in https://datatracker.ietf.org/doc/html/rfc7517#section-4.7 + stpl: + type: string + description: | + This is a base64 encoded representation of the OCSP response to the + end entity X.509 certificate in x5c. required: - typ - alg - x5c + - stpl ScenarioResponseMessage: type: object @@ -322,13 +328,9 @@ components: token: type: string description: "PoPP token as JWT compact serialization." - pn: - type: string - description: "Prüfnachweis" required: - type - token - - pn # PoPP Token Headers TokenHeaders: @@ -354,25 +356,14 @@ components: The key identifier of the key used to sign the token. Key itself can be retrieved from the JWK endpoint of the PoPP server. - x5c: - type: array - items: - type: string - description: | - The X.509 certificate chain used to sign the token. - The first element is the certificate that was used to sign the token. - Certificates are encoded in DER and base64 encoded as described in - https://datatracker.ietf.org/doc/html/rfc7517#section-4.7 required: - typ - alg - kid - - x5c examples: - typ: "vnd.telematik.popp+jwt" alg: "ES256" kid: "x_vW4LVDipvu8iUQ5alKsZLWtH6jh4eJ4c5offXtMV0" - x5c: [ "MIIBI..." ] # PoPP Token Claims TokenClaims: