Merge pull request #20 from gematik/feature/more_OpenAPI

Feature/more open api

src/examples/client-assertion-jwt-payload-examle.json

@@ -0,0 +1,49 @@
+{
+    "nonce": "...Nonce from the AS...",
+    "iss":"urn:telematik:telematik-id:9-123456789",
+    "sub":"...Client ID...",
+    "aud":"https://as.example.com",
+    "iat":1562262611,
+    "exp":1562266216,
+    "cnf": {
+        "jkt":"..thumbprint of the DPoP key..."
+    },
+     "urn:telematik:client-self-assessment": {
+        "name": "MeinTestClient",
+        "client_id": "...Client ID...",
+        "product_id": "PS-000",
+        "product_name": "TestApp",
+        "product_version": "0.5.0",
+        "manufacturer_id": "HRST-001",
+        "manufacturer_name": "TestHersteller",
+        "owner": {
+           "sub": "0XkIBtL3XhZ9qncbFmkYbLkj4vjkES4T3dgSgTfl2s5WyZgDkl7WW1HakMyi9iN6kLEGu7ssw1S52uW521gn9vLeNFLaIBlDJbbo55xQFJIqfPqUWYarCL253hQL2uIB4A",
+            "urn:telematik:claims:id": "T020821918",
+           "urn:telematik:claims:organization": "101575519",
+            "amr": [
+                "urn:telematik:auth:other"
+             ],
+            "iss": "https://...",
+            "urn:telematik:claims:display_name": "Juliane Mustermann",
+            "nonce": "WEgmvoUcr5EUAB7x41fmbXRqBdnr4gio",
+            "aud": "https://...",
+            "acr": "gematik-ehealth-loa-high",
+            "urn:telematik:claims:profession": "1.2.276.0.76.4.49",
+            "auth_time": 1710409161,
+            "exp": 1710409463,
+            "iat": 1710409163
+         },
+        "owner_mail": "test@example.com",
+        "registration_timestamp": 1678886400,
+        "platform": "software",
+	"posture": {
+           "os": "Microsoft Windows",
+           "os_version": "10.0.19045.4291",
+           "arch": "x86"
+        },
+       "attestation": {
+        "method": "none",
+        "timestamp": 1678886400
+        }
+    }
+}

src/examples/client-instance-example.json

@@ -0,0 +1,75 @@
+{
+    "name": "MeinTestClient",
+    "client_id": "unique-client-id-123",
+    "product_id": "product-id-456",
+    "product_name": "TestApp",
+    "product_version": "1.0.0",
+    "manufacturer_id": "manufacturer-789",
+    "manufacturer_name": "TestHersteller",
+     "owner": {
+          "sub": "0XkIBtL3XhZ9qncbFmkYbLkj4vjkES4T3dgSgTfl2s5WyZgDkl7WW1HakMyi9iN6kLEGu7ssw1S52uW521gn9vLeNFLaIBlDJbbo55xQFJIqfPqUWYarCL253hQL2uIB4A",
+          "urn:telematik:claims:id": "T020821918",
+          "urn:telematik:claims:organization": "101575519",
+          "amr": [
+              "urn:telematik:auth:other"
+          ],
+          "iss": "https://...",
+          "urn:telematik:claims:display_name": "Juliane Mustermann",
+          "nonce": "WEgmvoUcr5EUAB7x41fmbXRqBdnr4gio",
+          "aud": "https://...",
+          "acr": "gematik-ehealth-loa-high",
+          "urn:telematik:claims:profession": "1.2.276.0.76.4.49",
+          "auth_time": 1710409161,
+          "exp": 1710409463,
+          "iat": 1710409163
+      },
+    "owner_mail": "test@example.com",
+    "registration_timestamp": 1678886400,
+    "platform": "android",
+    "platform_product_id": {
+      "namespace": "android_app",
+      "package_name": "com.test.app",
+      "sha256_cert_fingerprints": [
+        "AABBCCDD..."
+      ]
+    },
+    "posture": {
+      "build": {
+          "version": {
+              "sdk_init": 30,
+              "security_patch": "2023-04-05"
+           },
+          "manufacturer": "Google",
+          "product": "Pixel",
+          "model": "Pixel 5",
+      "board": "sunfish"
+
+        },
+      "ro": {
+          "crypto": {
+              "state": true
+           },
+      "product": {
+          "first_api_level": 29
+             }
+        },
+       "packageManager": {
+            "feature_verified_boot": true,
+            "mainline_patch_level": "2023-08-01"
+        },
+      "keyguardManager": {
+          "isDeviceSecure": true
+      },
+      "biometricManager": {
+          "deviceCredential": true,
+          "biometricStrong": true
+      },
+      "devicePolicyManager": {
+          "passwordComplexity": 2
+      }
+    },
+    "attestation": {
+      "method": "android-key-id-attestation",
+      "timestamp": 1678886400
+    }
+  }

src/plantuml/native_client_attestation_oidc_and_oauth.puml

@@ -0,0 +1,178 @@
+@startuml "native_client_attestation_oidc_and_oauth"
+
+skinparam defaultFontSize 10
+skinparam DefaultMonospacedFontName Courier
+skinparam lengthAdjust none
+
+skinparam sequence {
+  ParticipantBorderColor black
+  ParticipantBackgroundColor white
+  ActorBorderColor black
+  ActorBackgroundColor white
+  ArrowColor black
+  LifeLineBorderColor black
+  LifeLineBackgroundColor #F0F0F0
+  NoteBorderColor black
+  NoteBackgroundColor #FEFECE
+}
+
+!pragma teoz true
+
+Actor User
+box "Mobile Device" #GhostWhite
+    participant UserAgent as "User Agent"
+    participant MUA as "Mail\nUser Agent"
+    participant Client as "Client"
+    participant AndroidTEE as "Android TEE"
+    participant Authenticator as "Authenticator"
+end box
+
+box "Anbieter" #TECHNOLOGY
+    box "ZETA Guard" #SandyBrown
+        participant AuthS as "PDP\nAuthS"
+        participant PEP as "PEP\nHTTP Proxy"
+        participant PEA as "PDP\nPolicy Engine"
+    end box
+    box "TI 2.0\nDienst" #DarkSeaGreen
+        participant RS as "Resource\nServer"
+    end box
+end box
+
+participant "Attestation\nService" as AttService
+participant "IDP" as IDP
+participant "Federation \nMaster" as FedMaster
+
+== Client Registration (with Client Attestation and Email) ==
+
+User -> Client: User Starts Registration
+activate Client
+alt Android Attestation
+    Client -> AndroidTEE: Generate Key Pair\nfor Attestation
+    activate AndroidTEE
+    note right: Using Android TEE or iOS Secure Enclave
+    AndroidTEE --> Client: Public Key
+    deactivate AndroidTEE
+    Client -> AttService: Request Attestation Challenge
+    activate AttService
+    AttService --> Client: Attestation Challenge
+    deactivate AttService
+    Client -> AndroidTEE: Sign Challenge with\nAttestation Key
+    activate AndroidTEE
+    note right: Using Android SafetyNet/Play Integrity or\niOS DeviceCheck/App Attest API
+    AndroidTEE --> Client: Attestation Statement
+    deactivate AndroidTEE
+else iOS Attestation
+    Client -> Client:
+    note right: iOS Attestation with App Attest API or\nDeviceCheck API
+end
+Client -> AuthS: Client Registration Request
+note right: client_instance.yaml\nIncludes attestation statement, public key,\nUser Email and software statement
+activate AuthS
+AuthS -> AttService: Verify Client Attestation
+activate AttService
+note right: AS A forwards attestation data\nto Attestation Service
+AttService -> AttService: Validate Attestation\nStatement
+AttService --> AuthS: Attestation Verification Result
+AuthS -> AuthS: Verify Email Confirmation JWT
+deactivate AttService
+alt Email Confirmation Required
+    AuthS -> AuthS: Generate Confirmation\nLink and send Email
+    activate MUA
+    MUA -> MUA: Receive Email
+    User -> MUA: Click Confirmation\nLink in Email
+    MUA -> UserAgent: Open\nConfirmation\nLink
+    activate UserAgent
+    deactivate MUA
+    UserAgent -> AuthS: Email Confirmation\nRequest
+    deactivate UserAgent
+    AuthS -> AuthS: Verify Email\nConfirmation\nRequest
+    AuthS -> AuthS: Generate Email\nConfirmation JWT
+    note right: JWT Claims:\n - iss: AS_A_ID\n - sub: Client_id\n - aud: (all AS)\n - exp: (Policy Engine decision)\n - iat: (now)\n - Email_verified: true
+    AuthS -> PEA: Request Client\nRegistration Decision
+    activate PEA
+    note right: AS A sends input data to Policy Engine A\nfor registration request
+    PEA -> PEA: Evaluate Policy based\non Input Data
+    PEA --> AuthS: Client Registration\nDecision (Permit/Deny)
+    deactivate PEA
+    AuthS --> Client: Client Registration Response\n(client_id, Email Confirmation JWT)
+    deactivate AuthS
+    else Email Confirmation already done
+    AuthS -> PEA: Request Client\nRegistration Decision
+    activate PEA
+    note right: AS A sends input data to Policy Engine A\nfor registration request
+    PEA -> PEA: Evaluate Policy based\non Input Data
+    PEA --> AuthS: Client Registration\nDecision (Permit/Deny)
+    deactivate PEA
+    AuthS --> Client: Client Registration Response\n(client_id)
+end
+deactivate AuthS
+
+== OAuth 2.0 Authorization Code Flow with PAR, PKCE and DPoP ==
+Client -> Client: Generate PKCE\nCode Verifier
+Client -> Client: Generate PKCE\nCode Challenge
+Client -> Client: Generate DPoP Key Pair
+Client -> AuthS: PAR Request\n(client_id, redirect_uri, scope, etc., dpop_jkt)
+activate AuthS
+note right: Authorization Code Request\n(inkl. DPoP Proof, code_challenge, code_challenge_method, redirect_uri)
+AuthS -> AuthS: Validate DPoP Proof
+AuthS --> Client: Request URI
+deactivate AuthS
+
+Client -> UserAgent: Navigate to Request URI
+activate UserAgent
+UserAgent -> AuthS: Authorization Request (with Request URI)
+
+activate AuthS
+group OIDC user authentication with confidential client
+    AuthS -> IDP: PAR Request (OpenID Connect), redirect_uri, client_id_idpsek\nsee https://gemspec.gematik.de/docs/gemSpec/gemSpec_IDP_Sek/latest/#7.1.2
+activate IDP
+note right: AS A acts as Relying Party\n for the IDP\n(client_id_idpsek)
+    IDP --> AuthS: URI-PAR Response, request_uri, expires_in
+    AuthS --> Client: Redirect URI-PAR to IDP, request_uri
+    Client --> Authenticator: Redirect URI-PAR to IDP, request_uri
+activate Authenticator
+    Authenticator -> IDP: Navigate to URI-PAR, request_uri
+    IDP --> Authenticator: Authentication Prompt, consent
+    Authenticator -> IDP: User Credentials, consent
+    IDP --> Authenticator: Redirect to AuthS, auth_code, redirect_uri
+    Authenticator -> Client: Redirect to AuthS, auth_code, redirect_uri
+deactivate Authenticator
+    Client-> AuthS: Redirect to AuthS, auth_code, redirect_uri
+    AuthS -> IDP: Token Request (Authorization Code Grant), auth_code
+    IDP -> IDP: Validate\nAuthorization\nCode
+IDP --> AuthS: Authentication Response (ID Token)
+deactivate IDP
+end
+    AuthS -> AuthS: Validate\nID Token
+    AuthS --> UserAgent: Authorization Code
+    UserAgent -> Client: Redirect with Authorization Code
+deactivate UserAgent
+
+Client -> Client: Generate\nDPoP Proof JWT
+Client -> AuthS: Token Request (Authorization Code Grant)
+note right: Enthält Authorization Code, DPoP Proof,\nclient_id, redirect_uri, code_verifier
+AuthS -> AuthS: Validate\nAuthorization Code
+AuthS -> AuthS: Validate DPoP Proof
+AuthS -> AuthS: Validate PKCE\nCode Verifier
+AuthS -> PEA: Request Token Issuance Decision
+activate PEA
+note right: AS A sends input data to Policy Engine A\nfor token request
+PEA -> PEA: Evaluate Policy based\non Input Data
+PEA --> AuthS: Token Issuance Decision (Permit/Deny)
+deactivate PEA
+    AuthS --> Client: Access Token, Refresh Token
+note left: Access Token bound to\nclient's DPoP public key
+deactivate AuthS
+
+Client -> Client: Generate DPoP Token
+Client -> PEP: Access Protected Resource\n(with Access Token and DPoP Proof)
+activate PEP
+PEP -> PEP: Validate Access Token\nand DPoP Proof
+PEP -> RS: Forward Request to\nResource Server A
+activate RS
+RS --> PEP: Resource Data
+PEP --> Client: Resource Data
+deactivate PEP
+deactivate RS
+
+@enduml

src/plantuml/sm-b-auth.puml → src/plantuml/sm-b_auth_with_dpop.puml

@@ -8,7 +8,7 @@ skinparam lengthAdjust none
 !pragma teoz true
 
 box "LEI" #GhostWhite
-  participant Client
+  participant Client as "ZETA\nClient"
   participant Konnektor as "Konnektor or\nTI-Gateway"
   participant SMB as "SM-B"
 end box