From ec62ac18ac46bdf3d94991f60945eeb432cf0143 Mon Sep 17 00:00:00 2001 From: Roel Storms Date: Tue, 7 Jan 2025 16:51:04 +0100 Subject: [PATCH 1/3] Update II mobile integration sequence diagrams to use mermaid Update II mobile integration sequence diagrams to use mermaid --- .../security/security-best-practices/iam.mdx | 82 ++++++++++++++++++- 1 file changed, 80 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/security/security-best-practices/iam.mdx b/docs/developer-docs/security/security-best-practices/iam.mdx index e68b8278ed..4c869416ba 100644 --- a/docs/developer-docs/security/security-best-practices/iam.mdx +++ b/docs/developer-docs/security/security-best-practices/iam.mdx @@ -124,7 +124,44 @@ Upon successful authentication, II will return a delegation for the principal de When integrating a mobile application with II, the implementation is not straightforward, since a mobile app can’t call the `postMessage` API. It is tempting to create a simple “proxy” web frontend served by the dapp as shown in the sequence diagram below. The mobile application can load this proxy to complete the normal II authorization flow. Upon completion, this proxy web app provides the delegation back to the mobile app. -![Naive integration sequence diagram](./_attachments/II_mobile_naive_integration.png) +Naive implementation +```mermaid +sequenceDiagram + actor U as User + participant MA as Mobile App + participant PWA as Proxy web app + participant II_FE as II Front-end + participant II_BE as II Back-end + participant BE as Back-end + + activate U + U -> MA : 1. Login + activate MA + MA ->> MA : 2. Generate session key pair + activate PWA + MA ->> PWA: 3. Load /?sessionPublicKey=
+ activate II_FE + PWA ->> II_FE: 4. Standard II client auth protocol + U ->> II_FE: 5. Authenticate with passkey + activate II_BE + II_FE ->> II_BE: 6. getDelegation(frontEndHostname) + II_BE -->> II_FE: 7. <> + Note over II_BE,II_FE: Delegation can leak through
replica or boundary nodes + deactivate II_BE + II_FE -->> PWA: 8. Return the delegation
using postMessage API + deactivate II_FE + PWA -->> MA: 9. Return the delegation + Note over PWA,MA: Delegation can leak through
insecure return mechanism + deactivate PWA + U ->> MA: 10. Authenticated call + activate BE + MA ->> BE: 11. Update call using the delegation + Note over II_BE,BE: Delegation can leak through
replica or boundary nodes + BE -->> MA: <> + deactivate BE + deactivate MA + deactivate U +``` However, without any precautions, this proxy would happily accept malicious requests to authenticate the user and might return the delegation back to an attacker. @@ -148,7 +185,48 @@ In the standard integration between a client web app and the II web frontend, th This risk can be addressed by adopting the following remediations shown in the sequence diagram and explained further below. -![Secure integration sequence diagram](./_attachments/ii_mobile_secure_integration.png) +Secure integration sequence diagram +```mermaid +sequenceDiagram + actor U as User + participant MA as Mobile App + participant PWA as Secure Proxy web app + participant II_FE as II Front-end + participant II_BE as II Back-end + participant BE as Back-end + + activate U + U -> MA : 1. Login + activate MA + MA ->> MA : 2. Generate session key pair + activate PWA + MA ->> PWA: 3. Load /?sessionPublicKey=
+ PWA ->> PWA: 4. Generate intermediate session key + Note over PWA: This key never
leaves the proxy
front-end + activate II_FE + PWA ->> II_FE: 5. Standard II client auth protocol
using intermediate session key + Note over PWA,II_FE: II will create a delegation for the
intermediate key and not for the attacker
chosen session key. + U ->> II_FE: 6. Authenticate with passkey + activate II_BE + II_FE ->> II_BE: 7. getDelegation(frontEndHostname) + II_BE -->> II_FE: 8. <> + II_FE ->> II_FE: 9. Construct the delegation chain + Note over II_FE: The proxy front-end creates a
delegation from the intermediate
key to the mobile app session key
and combines it with the
delegation from the II canister key
to the intermediate key. + II_FE -->> PWA: 10. Return the delegation
using the postMessage API + deactivate II_FE + PWA -->> MA: 11. Return the delegation chain using
an app link (Android)
or universal link (iOS)
as part of the fragment
using associated domains + Note over MA,PWA: Protect the delegation chain
from being leaked to the web
server by using a URI fragment
instead of a GET parameter. + MA ->> MA: 12 Verify the delegation chain
against the session
key from step 2 + Note over MA: Verify the delegation chain before using it
to avoid leaking a delegation with an
attacker controlled session key to the IC +MA -->> U: <> + U ->> MA: 13. Authenticated call + activate BE + MA ->> BE: 14. Update call using the verified delegation chain + BE -->> MA: <> + deactivate BE + deactivate MA + deactivate U +``` * Introduce an intermediate session key which is generated and stored by the web app proxy frontend. * Initiate the II client authentication protocol using this intermediate session key. By using a new session key which the attacker can’t control, the delegation issued by II would no longer be usable by the attacker if it were stolen in step 8, as the attacker doesn’t have access to the intermediate session private key. From 09bd06a4a61f49ed181d183f6ca37aee61540e8c Mon Sep 17 00:00:00 2001 From: Roel Storms Date: Tue, 7 Jan 2025 16:56:03 +0100 Subject: [PATCH 2/3] Changed title for the diagrams --- docs/developer-docs/security/security-best-practices/iam.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-docs/security/security-best-practices/iam.mdx b/docs/developer-docs/security/security-best-practices/iam.mdx index 4c869416ba..889f183ef6 100644 --- a/docs/developer-docs/security/security-best-practices/iam.mdx +++ b/docs/developer-docs/security/security-best-practices/iam.mdx @@ -124,7 +124,7 @@ Upon successful authentication, II will return a delegation for the principal de When integrating a mobile application with II, the implementation is not straightforward, since a mobile app can’t call the `postMessage` API. It is tempting to create a simple “proxy” web frontend served by the dapp as shown in the sequence diagram below. The mobile application can load this proxy to complete the normal II authorization flow. Upon completion, this proxy web app provides the delegation back to the mobile app. -Naive implementation +**Naive implementation sequence diagram:** ```mermaid sequenceDiagram actor U as User @@ -185,7 +185,7 @@ In the standard integration between a client web app and the II web frontend, th This risk can be addressed by adopting the following remediations shown in the sequence diagram and explained further below. -Secure integration sequence diagram +**Secure integration sequence diagram:** ```mermaid sequenceDiagram actor U as User From a09b9f15ffbd45d6230ca058e420b081b8d9e2db Mon Sep 17 00:00:00 2001 From: Roel Storms Date: Thu, 30 Jan 2025 10:49:05 +0100 Subject: [PATCH 3/3] Update iam.mdx Addresses @venkkatesh-sekar remark. --- docs/developer-docs/security/security-best-practices/iam.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/developer-docs/security/security-best-practices/iam.mdx b/docs/developer-docs/security/security-best-practices/iam.mdx index 889f183ef6..a1c45459e5 100644 --- a/docs/developer-docs/security/security-best-practices/iam.mdx +++ b/docs/developer-docs/security/security-best-practices/iam.mdx @@ -142,6 +142,7 @@ sequenceDiagram MA ->> PWA: 3. Load /?sessionPublicKey=
activate II_FE PWA ->> II_FE: 4. Standard II client auth protocol + Note over PWA,II_FE: II will create a delegation for the session
key generated by the mobile application. U ->> II_FE: 5. Authenticate with passkey activate II_BE II_FE ->> II_BE: 6. getDelegation(frontEndHostname)