diff --git a/docs/development/self-sovereign-identity/README.md b/docs/development/self-sovereign-identity/README.md new file mode 100644 index 000000000..43d84a4bf --- /dev/null +++ b/docs/development/self-sovereign-identity/README.md @@ -0,0 +1,32 @@ +# Self-Sovereign Identity + +> Draft + +This document is intended to create a common understanding of SSI in Catena-X. The content described here can then be +used for documentation on the SSI topic. + +## Table of Contents + +1. Catena-X Onboarding +2. Connector Authentication + +## 1. Catena-X Onboarding + +The user registers at the portal. The portal then +- creates a new MIW tenant +- creates / requests some initial credentials for the tenant +- puts the verifiable credentials into the wallet of the tenant + +![Catena-X Onboarding](./diagrams/onboarding.png) + +## 2. Connector Authentication + +If one connector sends out a catalog request to another connector +- it creates an IDS authentication token with a verifiable presentation +- it sends the IDS message with the token to the other connector + +The receiving connector then +- checks the verifiable presentation for SSI compliance +- checks the verifiable presentation for authentication + +![Connector Authentication](./diagrams/connector-authentication.png) diff --git a/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-1.png b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-1.png new file mode 100644 index 000000000..73e16acbc Binary files /dev/null and b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-1.png differ diff --git a/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-1.puml b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-1.puml new file mode 100644 index 000000000..14b08d8a9 --- /dev/null +++ b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-1.puml @@ -0,0 +1,68 @@ +@startuml + +' TODO Add Copyright Header + +autonumber + +actor User as USER + +box Connector A + participant "IDS\n<>" as IDS_EXT_A + participant "SSI Identity Service\n<>" as SSI_IAM_EXT_A + participant "Managed Identity Wallets\n<>" as MIW_EXT_A +end box + +participant "IAM\n<>" as IAM + +box "Managed Identity Wallets" + participant "API" as MIW_API + participant "Participant Wallet\n<>" as MIW_Participant +end box + +box Connector B + participant "Managed Identity Wallets\n<>" as MIW_EXT_B + participant "SSI Identity Service\n<>" as SSI_IAM_EXT_B + participant "IDS\n<>" as IDS_EXT_B +end box + +-> IDS_EXT_A ++ : initiate catalog request + IDS_EXT_A -> SSI_IAM_EXT_A ++ : request authentication token + SSI_IAM_EXT_A -> MIW_EXT_A ++ : request credential, used for authentication + MIW_EXT_A -> IAM ++: request token with client_secret + return access token + + MIW_EXT_A -> MIW_API ++: get credential + MIW_API -> MIW_API : resolve wallet of token owner + MIW_API -> MIW_Participant ++ : get + return credential + return credential + return credential + + SSI_IAM_EXT_A -> MIW_EXT_A ++ : request verifiable presentation with auth. credential + MIW_EXT_A -> IAM ++: request token with client_secret + return access token + MIW_EXT_A -> MIW_API ++ : request verifiable presentation + MIW_API -> MIW_API : resolve wallet of token owner + MIW_API -> MIW_API : resolve owner signature key + return signed JWT with verifiable presentation + return JWT +return authentication token + +IDS_EXT_A -> IDS_EXT_B ++ : send catalog request message + IDS_EXT_B -> SSI_IAM_EXT_B ++ : verify JWT token + SSI_IAM_EXT_B -> MIW_EXT_B ++ : verify JWT token with verifiable presentation + MIW_EXT_B -> IAM ++: request token with client_secret + return access token + MIW_EXT_B -> MIW_API ++ : verify JWT token with verifiable presentation + MIW_API -> MIW_API : JSON LD checks + MIW_API -> MIW_API : Revocation checks + MIW_API -> MIW_API : Signature checks + return ok + return ok + SSI_IAM_EXT_B -> SSI_IAM_EXT_B : credential check + SSI_IAM_EXT_B -> SSI_IAM_EXT_B : issuer checks + return ok +return catalog + + +@enduml \ No newline at end of file diff --git a/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-2-abstract.png b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-2-abstract.png new file mode 100644 index 000000000..98a0d8f92 Binary files /dev/null and b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-2-abstract.png differ diff --git a/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-2-abstract.puml b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-2-abstract.puml new file mode 100644 index 000000000..f6a3ee5f9 --- /dev/null +++ b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-2-abstract.puml @@ -0,0 +1,21 @@ +@startuml + +autonumber + +participant "Participant A\n<>" as Consumer +participant "Participant B\n<>" as Provider +participant "Token Provider" as TokenProvider +participant "VC Issuer" as Issuer + + +Consumer -> TokenProvider ++: request token +return token + +Consumer -> Provider ++ : presents token + Provider -> TokenProvider ++ : validate token +' TokenProvider -> Issuer ++ : Request signature +' return signature + return ok +return response + +@enduml \ No newline at end of file diff --git a/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-3-tbd.png b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-3-tbd.png new file mode 100644 index 000000000..74072b43e Binary files /dev/null and b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-3-tbd.png differ diff --git a/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-3-tbd.puml b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-3-tbd.puml new file mode 100644 index 000000000..a17890a90 --- /dev/null +++ b/docs/development/self-sovereign-identity/diagrams/auth-flow-draft-3-tbd.puml @@ -0,0 +1,25 @@ +@startuml + +autonumber + +participant "Participant A\n<>" as Consumer +participant "Token Provider" as TokenProvider +participant "Participant B\n<>" as Provider + +Consumer -> TokenProvider ++: request token +note right + The token may contain a custom claim, + e.g. a VP, URI, pointer to VP, etc. +end note +return token + +Consumer -> Provider ++ : presents token + alt if provider cannot decide itself + Provider -> ++ : validate token + return ok + else if provider can decide itself + Provider -> Provider: validate token + end +return response + +@enduml \ No newline at end of file diff --git a/docs/development/self-sovereign-identity/diagrams/onboarding.png b/docs/development/self-sovereign-identity/diagrams/onboarding.png new file mode 100644 index 000000000..6c1a09991 Binary files /dev/null and b/docs/development/self-sovereign-identity/diagrams/onboarding.png differ diff --git a/docs/development/self-sovereign-identity/diagrams/onboarding.puml b/docs/development/self-sovereign-identity/diagrams/onboarding.puml new file mode 100644 index 000000000..99cb8a446 --- /dev/null +++ b/docs/development/self-sovereign-identity/diagrams/onboarding.puml @@ -0,0 +1,38 @@ + @startuml + +' TODO Add Copyright Header + +autonumber + +Actor User + +participant Portal + +participant "Authority Wallet\n<>" as Operator + +participant "Gaia-X Digital Clearing House" as GXDCH + +User -> Portal ++: register + +Portal -> Operator ++: request CX-Credential(s) +return verifiable credential(s) + +Portal -> GXDCH ++: request Legal Entity Credential +return verifiable credential + +create participant "Participant Wallet\n<>" as Participant +Portal -> Participant : create +Portal -> Participant ++ : put verifiable credentials +return ok + +... do some more registration stuff ... + +return registration complete + + + + + + + + @enduml \ No newline at end of file