diff --git a/README.md b/README.md index ff6a453..045561b 100644 --- a/README.md +++ b/README.md @@ -59,11 +59,46 @@ but also in the home. * human-friendly * machine-friendly * no developer required - # Implementation Details OAuth3 is intended to work in URL-based flows such as `https://`, `app://`, and (ostensibly) `dat://`. -### 4 Flows for User-Defined Privacy +### subject, issuer, authorized party, and audience +Just a quick intro to vocabulary that will be explained more thoroughly later on: -![](https://media.daplie.com/oauth3/oauth3-flows-800x800.png) \ No newline at end of file +* **subject** - typically a username or email address that references the real, live person that we care about +* **issuer** - the service or device that issues tokens (or manages public keys). In the old-world model this is Facebook, Twitter, etc +* **audience** - the service or device that exchanges tokens for goods or services. In the old-world model this is Facebook, Twitter, etc +* **authorized party** - the service or device that uses tokens to accomplish the subject's goals. In the old-world model this is a site that has a "Login with Facebook" button + +### There are 4 potential Identity Delegation styles + +![](https://media.daplie.com/oauth3/oauth3-flows-800x800.png) + +### Type 1: Full Delegation (no discovery) + +This provides the simplest user experience by hiding all choices from the user and presenting only a single login button. + +In this scenario a default identity issuer has already been selected (presumably oauth3.org) and the single button is immediately active. + +The advanced button presents another input box that can be used to enter an address. + +### Type 2: Address Flow (email - no discovery) + +In this flow a default identity issuer has also already been selected and the user provides their email address which will be passed to the issuer as the subject. + +The advanced button presents another input box that can be used to manually specify an identity issuer (requires discovery). + +### Type 3: Address Flow (oauth3 - discovery) + +In this flow the identity issuer will be chosen based on the address provided by the user. If the address is discovered to be an oauth3 address it will be used as such. Otherwise the flow will fallback to type 2. + +**email address**: this is the same as flow type 2 + +**oauth3 address**: the identity issuer specified will be used, the username is optional + +### Type 4: Advanced Flow (manual + discovery) + +There is a chance that someone would like to use an oauth3 subject address (i.e. jane@smithfam.net) with a different identity issuer than the one identified by the subject. + +In this flow the subject and the identity issuer can be manually selected independently, ignoring the discovery of the subject. \ No newline at end of file