Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update II mobile integration sequence diagrams to use mermaid #3930

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Update II mobile integration sequence diagrams to use mermaid #3930

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ec62ac1
Update II mobile integration sequence diagrams to use mermaid
roelstorms Jan 7, 2025
09bd06a
Changed title for the diagrams
roelstorms Jan 7, 2025
a09b9f1
Update iam.mdx
roelstorms Jan 30, 2025
2c318a6
Merge branch 'master' into roelstorms-II-mobile-sequence-diagram
roelstorms Jan 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 80 additions & 2 deletions docs/developer-docs/security/security-best-practices/iam.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 sequence diagram:**
```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=<br/><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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear here that the delegation is granted for the session public key

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a note on line 145 similar to the second diagram.

II_BE -->> II_FE: 7. <<delegation>>
Note over II_BE,II_FE: Delegation can leak through<br/> replica or boundary nodes
deactivate II_BE
II_FE -->> PWA: 8. Return the delegation<br/>using postMessage API
deactivate II_FE
PWA -->> MA: 9. Return the delegation
Note over PWA,MA: Delegation can leak through<br/> 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<br/> replica or boundary nodes
BE -->> MA: <<Response>>
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.

Expand All @@ -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=<br/><SessionPublicKey>
PWA ->> PWA: 4. Generate intermediate session key
Note over PWA: This key never<br/>leaves the proxy<br/>front-end
activate II_FE
PWA ->> II_FE: 5. Standard II client auth protocol<br/>using intermediate session key
Note over PWA,II_FE: II will create a delegation for the<br/>intermediate key and not for the attacker<br/>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. <<delegation>>
II_FE ->> II_FE: 9. Construct the delegation chain
Note over II_FE: The proxy front-end creates a<br/>delegation from the intermediate<br/> key to the mobile app session key<br/>and combines it with the<br/>delegation from the II canister key<br/>to the intermediate key.
II_FE -->> PWA: 10. Return the delegation<br/>using the postMessage API
deactivate II_FE
PWA -->> MA: 11. Return the delegation chain using<br/>an app link (Android)<br/>or universal link (iOS)<br/>as part of the fragment<br/>using associated domains
Note over MA,PWA: Protect the delegation chain<br/>from being leaked to the web<br/> server by using a URI fragment<br/>instead of a GET parameter.
MA ->> MA: 12 Verify the delegation chain<br/>against the session<br/>key from step 2
Note over MA: Verify the delegation chain before using it<br/> to avoid leaking a delegation with an<br/>attacker controlled session key to the IC
MA -->> U: <<Success>>
U ->> MA: 13. Authenticated call
activate BE
MA ->> BE: 14. Update call using the verified delegation chain
BE -->> MA: <<Response>>
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.
Expand Down
Loading