Merge pull request #13 from elf-pavlik/example-tld

replace all made up .com TLDs with .example

Author: justinwb

README.md

@@ -111,10 +111,10 @@ documents.
 
 The overall sign in workflow used by the WebID-OIDC protocol is as follows.
 For example, here is what happens when Alice tries to request the resource
-`https://bob.com/resource1`.
+`https://bob.example/resource1`.
 
 1. [Initial Request](example-workflow.md#1-initial-request): Alice
-   (unauthenticated) makes a request to `bob.com`, receives an HTTP `401
+   (unauthenticated) makes a request to `bob.example`, receives an HTTP `401
    Unauthorized` response, and is presented with a 'Sign In With...' screen.
 2. [Provider Selection](example-workflow.md#21-provider-selection): She selects
    her WebID service provider by clicking on a logo, typing in a URI (for
@@ -127,22 +127,22 @@ For example, here is what happens when Alice tries to request the resource
    [WebAuthn](https://w3c.github.io/webauthn/) device, etc).
 4. [User Consent](example-workflow.md#4-user-consent): (Optional) She'd also be
    presented with a user consent screen, along the lines of "Do you wish to
-   sign in to `bob.com`?".
+   sign in to `bob.example`?".
 5. [Authentication Response](example-workflow.md#5-authentication-response):
-   She then gets redirected back towards `https://bob.com/resource1` (the
-   resource she was originally trying to request). The server, `bob.com`, also
+   She then gets redirected back towards `https://bob.example/resource1` (the
+   resource she was originally trying to request). The server, `bob.example`, also
    receives a signed ID Token from `alice.solidtest.space` that was returned
    with the response in point 3, attesting that she has signed in.
 6. [Deriving a WebID URI](#deriving-webid-uri-from-id-token):
-   `bob.com` (the server controlling the resource) validates the ID Token, and
+   `bob.example` (the server controlling the resource) validates the ID Token, and
    extracts Alice's WebID URI from inside  it. She is now signed in to
-   `bob.com` as user `https://alice.solidtest.space/#i`.
+   `bob.example` as user `https://alice.solidtest.space/#i`.
 7. [WebID Provider Confirmation](#webid-provider-confirmation):
-   `bob.com` confirms that `solidtest.space` is indeed Alice's authorized OIDC
+   `bob.example` confirms that `solidtest.space` is indeed Alice's authorized OIDC
    provider (by matching the provider URI from the `iss` claim with Alice's
    WebID).
 
-There is a lot of heavy lifting happening under the hood, performed by `bob.com`
+There is a lot of heavy lifting happening under the hood, performed by `bob.example`
 and `alice.solidtest.space`, the two servers involved in this exchange. They
 establish a trust relationship with each other (via
 [Discovery](example-workflow.md#22-provider-discovery), and [Dynamic
@@ -204,16 +204,16 @@ an additional step and *confirm* that the holder of that WebID has authorized
 a given Provider to use that WebID. Otherwise, the following situation can
 happen:
 
-1. Alice logs in to `bob.com` with her identity Provider of choice, `alice.com`.
-   The ID Token from `alice.com` claims Alice's WebID is
-   `https://alice.com/#i`. So far so good.
-2. An attacker also logs in to `bob.com`, using `evilbox.com` as an identity
+1. Alice logs in to `bob.example` with her identity Provider of choice, `alice.example`.
+   The ID Token from `alice.example` claims Alice's WebID is
+   `https://alice.example/#i`. So far so good.
+2. An attacker also logs in to `bob.example`, using `evilbox.com` as an identity
    Provider. And because they happen to control that server, they can put
    anything they want in the `webid` claim of any ID Token coming out of that
-   server. So they *also* claim that their `webid` is `https://alice.com/#i`.
+   server. So they *also* claim that their `webid` is `https://alice.example/#i`.
 
 Without an additional confirmation step, how can a recipient of an ID Token
-(here, `bob.com`) know which of those login attempts is correct? To put it
+(here, `bob.example`) know which of those login attempts is correct? To put it
 another way, how can a recipient know which Provider is *approved* by the
 owner of the WebID?
 
@@ -332,11 +332,11 @@ An OpenID Connect Identity `Provider` (called `OP` in most OIDC specs). Also
 sometimes referred to as `Issuer`. This can be either a POD (see below) or an
 external OIDC provider such as
 [Google](https://developers.google.com/identity/protocols/OpenIDConnect). In
-the spec, Alice's POD, `alice.com`, will mostly play the role of a Provider.
+the spec, Alice's POD, `alice.example`, will mostly play the role of a Provider.
 
 ##### Resource Server (RS)
 A server hosting resources that the user wants to access, such as HTML, images,
-Linked Data / RDF sources, and so on. In the spec, `bob.com` will be used as
+Linked Data / RDF sources, and so on. In the spec, `bob.example` will be used as
 the `Resource Server` (that is, Alice will be requesting resources on Bob's
 server). *Note:* In the traditional federated social sign on context, a
 provider (such as Facebook) serves as *both* an Identity Provider *and* a
@@ -345,12 +345,12 @@ Resource Server.
 ##### Relying Party (RP)
 A `Relying Party` is a POD or a client app that has to *rely* on an ID Token
 that's issued by a Provider. In the spec, when Alice tries to access a resource
-on `bob.com`, Bob's POD acts as the Relying Party, in that interaction.
-And correspondingly, Alice's POD, `alice.com`, will serve as the Identity
+on `bob.example`, Bob's POD acts as the Relying Party, in that interaction.
+And correspondingly, Alice's POD, `alice.example`, will serve as the Identity
 Provider, again for that interaction.
 
 Incidentally, when Alice tries to access a resource on her *own* POD,
-`alice.com` plays all of the roles -- it's both the Provider and a Relying
+`alice.example` plays all of the roles -- it's both the Provider and a Relying
 Party (as well as the Resource Server).
 
 ##### POD
@@ -360,7 +360,7 @@ also hosts the user's WebID Profile, and implements the API endpoints that allow
 it to act as a WebID-OIDC Identity Provider (OP). Lastly, when users requests
 resources from it, the POD also acts as a Relying Party (a recipient of those
 users' ID Tokens).
-In this spec, `alice.com` and `bob.com` are both PODs.
+In this spec, `alice.example` and `bob.example` are both PODs.
 
 ##### Home POD vs Other POD
 A user's Home POD is one that hosts their WebID Profile, and also acts as that
@@ -369,8 +369,8 @@ some other WebID-OIDC compliant POD, acting as a Resource Server and Relying
 Party, that a user is trying to access using the WebID URI and Profile of their
 Home POD.
 
-When Alice tries to access a resource on Bob's POD, `alice.com` is her Home
-POD, and `bob.com` plays the role of the Other POD.
+When Alice tries to access a resource on Bob's POD, `alice.example` is her Home
+POD, and `bob.example` plays the role of the Other POD.
 
 ##### Public Client vs Confidential Client
 Public - in-browser, mobile or desktop app, cannot be trusted with securely
@@ -380,7 +380,7 @@ Confidential - server-side app, can be trusted with secrets.
 ##### Presenter
 A public client app that is trying to *present* a user's credentials from their
 home POD to some other POD. For example, Bob is trying to access, via a client
-app, a shared file on Alice's `alice.com` POD, logging in using his own
-`bob.com` POD/provider. In this example, `bob.com` is a Provider, `alice.com` is
+app, a shared file on Alice's `alice.example` POD, logging in using his own
+`bob.example` POD/provider. In this example, `bob.example` is a Provider, `alice.example` is
 a Relying Party, and the client app (say, a browser-based HTML editor) is a
 Presenter.

application-workflow.md

@@ -2,8 +2,8 @@
 
 ## Actors
 **Alice** - A user that wants to allow an app access to data in her pod.  
-**Alice.com** - Alice’s Solid Pod Provider. She is using it both as her *Identity Provider (IdP)*, and as her *Resource Server (RS)* because her data is stored in her pod. This is the typical case for most Solid users.  
-**DecentPhotos** - The decentralized app that Alice wants to use at decentphotos.com, making it the *Relying Party (RP)*. Once authorized, it will act as an autonomous agent that connects to Alice's pod on its own at a regular interval or through an event-based trigger, and will organize her photos into different smart albums like - “photos taken in Italy”, or “photos of Bob".
+**alice.example** - Alice’s Solid Pod Provider. She is using it both as her *Identity Provider (IdP)*, and as her *Resource Server (RS)* because her data is stored in her pod. This is the typical case for most Solid users.  
+**DecentPhotos** - The decentralized app that Alice wants to use at decentphotos.example, making it the *Relying Party (RP)*. Once authorized, it will act as an autonomous agent that connects to Alice's pod on its own at a regular interval or through an event-based trigger, and will organize her photos into different smart albums like - “photos taken in Italy”, or “photos of Bob".
 
 ## Applicability
 This approach can be employed whether the application is one that Alice uses directly on the web through a browser (like a website she visits that lets her manage her photos), or one that runs autonomously (like a service she has authorized to connect to her pod every night and use smarts to organize her photos for her).
@@ -14,22 +14,22 @@ In this example, Alice is already logged into her identity provider (e.g. via so
 ## Step-by-Step Workflow
 1. Alice hears about DecentPhotos and wants to give it access to her pod so it can organize her pictures for her.
 2. DecentPhotos is an autonomous agent that runs on its own (from some cloud provider). To do this, Alice needs to give DecentPhotos some authority to access the photos in her pod on her behalf.
-3. Alice goes to `www.decentphotos.com` to connect it to her pod. She enters her WebID so DecentPhotos can lookup who her IdP (Identity Provider) is, and clicks a 'Connect' button.
-4. `decentphotos.com` (RP) reacts to the 'Connect' button being clicked by responding with a redirect. This redirect sends Alice's browser to the authorization endpoint at `Alice.com` because it is her IdP, including in the request a client_id of the DecentPhotos application/agent WebID (`https://decentphotos.com/appid#this`).
-5. Alice’s browser makes the request to the redirect URL (which is the authorization endpoint at IdP), identifying itself by the application WebID (client_id), and also passing along an optional scope and the redirect_uri, which is a callback to `decentphotos.com`, to be used after Alice has proved she has control of `Alice.com` (RS)
+3. Alice goes to `www.decentphotos.example` to connect it to her pod. She enters her WebID so DecentPhotos can lookup who her IdP (Identity Provider) is, and clicks a 'Connect' button.
+4. `decentphotos.example` (RP) reacts to the 'Connect' button being clicked by responding with a redirect. This redirect sends Alice's browser to the authorization endpoint at `alice.example` because it is her IdP, including in the request a client_id of the DecentPhotos application/agent WebID (`https://decentphotos.example/appid#this`).
+5. Alice’s browser makes the request to the redirect URL (which is the authorization endpoint at IdP), identifying itself by the application WebID (client_id), and also passing along an optional scope and the redirect_uri, which is a callback to `decentphotos.example`, to be used after Alice has proved she has control of `alice.example` (RS)
 6. Because Alice is already logged in at her IdP, she doesn’t need to enter her username and password again (she’s already got a token proving she is THE ALICE).
-7. The authorization endpoint at `Alice.com` (IdP) asks Alice if she wants to authorize DecentPhotos (RP) to access her Pod at a given scope. She has the ability here to further narrow this to only a subset of her photo library if she likes. Upon her confirmation here, DecentPhotos will be added as a trusted application in her WebID Profile, identified by its application/agent WebID (`https://decentphotos.com/appid#this`), and Alice's private photos folder at `https://alice.com/pics/private` will have its ACL updated to allow DecentPhotos (RP), identified by `https://decentphotos.com/appid#this`, read/write access to that folder and its contents.
-8. Alice submits this and is sent (redirected) to the redirect_uri / callback which was provided by DecentPhotos (RP) in Step #5, along with an authorization code. Alice's browser now makes a new GET request to `decentphotos.com` (RP), with that authorization code included.
+7. The authorization endpoint at `alice.example` (IdP) asks Alice if she wants to authorize DecentPhotos (RP) to access her Pod at a given scope. She has the ability here to further narrow this to only a subset of her photo library if she likes. Upon her confirmation here, DecentPhotos will be added as a trusted application in her WebID Profile, identified by its application/agent WebID (`https://decentphotos.example/appid#this`), and Alice's private photos folder at `https://alice.example/pics/private` will have its ACL updated to allow DecentPhotos (RP), identified by `https://decentphotos.example/appid#this`, read/write access to that folder and its contents.
+8. Alice submits this and is sent (redirected) to the redirect_uri / callback which was provided by DecentPhotos (RP) in Step #5, along with an authorization code. Alice's browser now makes a new GET request to `decentphotos.example` (RP), with that authorization code included.
 9. DecentPhotos makes a request to the IdP’s token endpoint with the authorization code, and receives a token in the response (assuming it all checks out) like:  
 ```
   { access_token: “98qwerkjhqwerjhkwq”, token_type: “Bearer” }.
 ```
   - The response may also include additional details like scope / expiration time, or a refresh token if available. The refresh token would allow DecentPhotos to continue to renew the bearer token without Alice having to intervene until the expire time associated with the Refresh token is passed. A refresh token's expire time is typically set for weeks or months, as opposed to the expire time on a bearer which should be much shorter lived (typically minutes or hours).
 
-10. DecentPhotos (RP) stores this token and is able to use it for requests to `Alice.com` (RS)
-11. That night, while Alice is asleep, DecentPhotos (RP) is going to connect to `Alice.com` (RS) and organize some photos
-12. DecentPhotos (RP) sends a request to the `Alice.com` (RS) for `https://alice.com/pics/private`, including the bearer token
-13. `Alice.com` (RS) validates the bearer token against `Alice.com` (IdP), and concludes it is valid. Since these are on the same server, this is fairly easy because the data is readily available. If they weren’t, this could be done through token introspection.
-14. `Alice.com` (RS) has confirmed that this is in fact THE DecentPhotos, and moves on to checking to see if DecentPhotos is authorized to access `https://alice.com/pics/private` based on the associated ACL.
-15. `Alice.com` (RS) matched the client_id in the token (`https://decentphotos.com/appid#this`), with a rule in the ACL which permits that the agent at `https://decentphotos.com/appid#this` has read and write access to `https://alice.com/pics/private`
+10. DecentPhotos (RP) stores this token and is able to use it for requests to `alice.example` (RS)
+11. That night, while Alice is asleep, DecentPhotos (RP) is going to connect to `alice.example` (RS) and organize some photos
+12. DecentPhotos (RP) sends a request to the `alice.example` (RS) for `https://alice.example/pics/private`, including the bearer token
+13. `alice.example` (RS) validates the bearer token against `alice.example` (IdP), and concludes it is valid. Since these are on the same server, this is fairly easy because the data is readily available. If they weren’t, this could be done through token introspection.
+14. `alice.example` (RS) has confirmed that this is in fact THE DecentPhotos, and moves on to checking to see if DecentPhotos is authorized to access `https://alice.example/pics/private` based on the associated ACL.
+15. `alice.example` (RS) matched the client_id in the token (`https://decentphotos.example/appid#this`), with a rule in the ACL which permits that the agent at `https://decentphotos.example/appid#this` has read and write access to `https://alice.example/pics/private`
 16. The request is granted.