Hellō
Skip to Content

Hellō Protocol

The Hellō Protocol ensures that Hellō can not impersonate a user, and that no component can arbitrarily access user data.

These assurances are provided transparently to external systems.
Hellō provides a standard OpenID Connect  interface to applications, and a standard relying party to issuers.

The following sequence of diagrams incrementally show how the Hellō Protocol achieves its goals. The final diagram is a complete sequence of the protocol for a simple login operation. An understanding of the OpenID Connect protocol and ID Tokens is required to appreciate how the Hellō Protocol acheives its goals.

Currently, the Hellō service is a monolithic architecture operated directly by the cooperative. Once we have product market fit, we will migrate to using the protocol.

Legend

Signed by example.appSigned by op.exampleSigned by Token ServiceSigned by Storage Service

Diagram 1 - Interactions with External Systems

The Hellō Protocol can be understood as a service that transforms a Request Token from an application and an ID Token from a user’s preferred provider into a Hellō ID Token in a trusted and repeatable manner.

In this diagram, we show how an application (example.app) requests a Hellō ID Token. Steps (01) and (99) are a standard OpenID Connect flow from the perspective of the application.

In step (10), Hellō is acting as a standard RP / client from the perspective of the user’s preferred login provider.

Steps (01), (10), & (99) are the same in all diagrams.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main Node example.app Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Node example.app Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Hellō circles 99 10 01

Diagram 2 - New User - Two Components

We separate the functionality between the Orchestration Service and the Token Service. Only the Orchestration Service can interact with external systems. As it is a new user in this case, the Token Service generates a random identifier for the user and a subject record binding the OpenID Provider’s identifiers to the Hellō user identifier, and mints an ID Token containing the new user identifier.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 create subject Token Service Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 DB Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes NOT FOUND DB Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Node example.app Node example.app Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Orchestration Service Orchestration Service Orchestration Service circles 99 15 12 13 01 14 10 11

Diagram 3 - Returning User - Impersonation Not Possible

The only way for the Token Service to generate an ID Token with the same user identifier is to be presented an OpenID Provider ID Token with the same identifiers and the subject record generated in Diagram 2.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main response create ID token Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 DB Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 Orchestration Service Token Service Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Node example.app Node example.app Orchestration Service Orchestration Service Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 circles 99 01 17 18 19 20 16 10

Diagram 4 - New User - Three Components

In Diagram 2, the Orchestration Service can access the database at will, and can choose to not present a subject record for an existing user, causing the Token Service to generate a new user. Introducing the Storage Service addresses these issues. The Orchestration can now only perform CRUD operations when it has acquired an access token, and can only have a user created if the Storage Service provides a token that there is no record for the user.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main create subject DB read subject Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes iss Class Name Error Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read Attributes NOT FOUND response Orchestration Service Group Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read Token Service request Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read response Attributes iss Class Name Error Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read DB response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes create Token Service request Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes create Storage Service Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Node example.app Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Orchestration Service Orchestration Service Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Storage Service Node example.app circles 99 01 21 22 24 26 27 28 30 32 33 29 31 23 10 25

Diagram 5 - Returning User - Three Components

Diagram 3 with the three components and access tokens.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main Orchestration Service read subject Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Token Service response Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read request Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 DB Token Service create ID Token Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes user Attributes ABCD-0123 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Node example.app Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Orchestration Service Orchestration Service Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Node example.app Storage Service response Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 circles 99 01 21 22 23 24 35 36 37 38 39 40 10 34

Diagram 6 - New User - Directed Identifier

So far, we have provided each application the same identifier for the same user. To address this, we create a layer of abstraction with a Release Record that links the Hellō identifier with a new, directed identifier specific to the application and user.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main DB Attributes NOT FOUND Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 read subject Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Token Service response Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read request Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read response Attributes iss Class Name Error Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read DB create user Attributes iss Class Name Error Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Token Service response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes create Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app Class Name Access Token Attributes op Attributes create Attributes id Attributes ABCD-0123 Attributes aud Attributes example.com Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 request Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes create Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app Class Name Access Token Attributes op Attributes create Attributes id Attributes ABCD-0123 Attributes aud Attributes example.com Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app Storage Service Node example.app Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Node example.app Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Orchestration Service Orchestration Service Orchestration Service Storage Service circles 01 21 22 23 24 26 27 28 42 43 44 99 29 41 10 25

Diagram 7 - Returning User - Directed Identifier

Diagram 5 with a directed identifier. The extra layer of abstraction requires an additional request from the Orchestration Service to the Storage Service.

Produced by OmniGraffle 7.20\n2022-09-21 19:06:03 +0000 Canvas 1 main Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 read subject Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Token Service response Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read request Attributes iss Class Name Access Token Attributes op.example Attributes sub Attributes OP-123456 Attributes op Attributes read response DB Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 read user Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Token Service response Class Name Access Token Attributes op Attributes read Attributes id Attributes ABCD-0123 Attributes aud Attributes example.com request Class Name Access Token Attributes op Attributes read Attributes id Attributes ABCD-0123 Attributes aud Attributes example.com Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app response Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app create ID token Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app Token Service response Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Node example.app Node example.app Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Orchestration Service Orchestration Service Orchestration Service DB Storage Service Storage Service circles 99 01 21 22 23 24 36 35 45 46 47 48 49 51 53 54 55 56 52 10 50 34

Diagram 8 - Creating Hashed Keys and Encrypted Records

While neither the Token Service, nor the Orchestration Service can arbitrarily access user data, the Storage Service can access data for all users. We address this issue by hashing all identifiers used to retrieve records, and encrypting the records with the fourth component, the Encryption Service.

Produced by OmniGraffle 7.20\n2022-09-22 16:07:31 +0000 Canvas 1 main Hash DB Token Service response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes create request Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes create Orchestration Service Encryption Service request Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes create Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr Storage Service circles 57 58 59 60 61

Diagram 9 - Reading Encrypted Records

The Encryption Service decrypts records retrieved from the Storage Service.

Produced by OmniGraffle 7.20\n2022-09-22 16:07:31 +0000 Canvas 1 main Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr Hash Token Service response Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes read request Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes read Encryption Service response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 request Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes read response Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr DB Storage Service Orchestration Service circles 57 63 64 66 67 68 65 read user Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 45 46 Hash 58

Diagram 10 - Four Components and Session Token

Requiring the Orchestration Service to pass all tokens and records with each request to the Token Service does not scale to more complex requests. The Token Service can capture state in a Session Token so that the Orchestration only needs to pass newly acquired tokens or records when making a request of the Token Service.

Produced by OmniGraffle 7.20\n2022-09-22 16:07:31 +0000 Canvas 1 circles Hash Hash new session response read subject Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Attributes nonce Attributes 9876543210 Token Service response Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes read request Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes read response Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Encryption Service request Attributes hash Class Name Access Token Attributes dnA1NjRiYjZj Attributes op Attributes read response Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr read user Attributes iss Class Name Subject Record Attributes op.example Attributes sub Attributes OP-123456 Attributes id Attributes ABCD-0123 Token Service response Attributes hash Class Name Access Token Attributes FidzB5YWFwb Attributes op Attributes read request Attributes hash Class Name Access Token Attributes FidzB5YWFwb Attributes op Attributes read response Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app create ID token Class Name Release Record Attributes di Attributes 4567-899A Attributes id Attributes ABCD-0123 Attributes aud Attributes example.app response Token Service response Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr request Attributes hash Class Name Access Token Attributes FidzB5YWFwb Attributes op Attributes read Encryption Service 91 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Attributes sid Class Name Session Token Attributes 9876543210 Attributes app Attributes example.app Attributes nonce Attributes 1212121212 Attributes iss Attributes op.example Attributes sub Attributes OP-123456 Attributes sid Class Name Session Token Attributes 9876543210 Attributes app Attributes example.app Attributes nonce Attributes 1212121212 Attributes iss Attributes op.example Attributes sub Attributes OP-123456 Attributes sid Class Name Session Token Attributes 9876543210 Attributes app Attributes example.app Attributes nonce Attributes 1212121212 Attributes iss Attributes op.example Attributes sub Attributes OP-123456 Attributes sid Class Name Session Token Attributes 9876543210 Attributes app Attributes example.app Attributes nonce Attributes 1212121212 Attributes id Attributes ABCD-0123 Attributes iss Attributes op.example Attributes sub Attributes OP-123456 Attributes sid Class Name Session Token Attributes 9876543210 Attributes app Attributes example.app Attributes nonce Attributes 1212121212 Attributes id Attributes ABCD-0123 Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 Attributes iss Class Name Request Token Attributes example.app Attributes aud Attributes hello.coop Attributes nonce Attributes 1212121212 Node example.app Node OpenID Provider op.example Attributes iss Class Name ID Token Attributes op.example Attributes aud Attributes hello.coop Attributes sub Attributes OP-123456 Node example.app Attributes iss Class Name ID Token Attributes hello.coop Attributes aud Attributes example.app Attributes sub Attributes ABCD-0123 Attributes nonce Attributes 1212121212 02 03 70 71 73 63 66 67 74 75 76 77 78 83 84 86 87 90 92 93 94 01 10 99 DB Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr DB Class Name Encrypted Record Attributes N3BuamdyM3ZwdnJr 65 85 64 72 Storage Service Storage Service Attributes sid Class Name Session Token Attributes 9876543210 Attributes app Attributes example.app Attributes nonce Attributes 1212121212 Orchestration Service Orchestration Service Orchestration Service

Other Transactions

We have shown the building blocks for verifying token transformation, and ensuring no custodian has credentials that can be used to access user data without colluding with another custodian.

Additional flows will support other transactions such as linking additional claims and subjects to the user, recoverying a Hellō wallet with recovery providers, and merging wallets.

Last updated on
Data Governance