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

Jump to bottom

Resource indication #320

Merged
merged 3 commits into from
Nov 7, 2023
Merged

Resource indication #320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
568c3c4
[spec] update authorization flows
elf-pavlik Oct 22, 2023
963947d
[primer] update both primers with authorization flows
elf-pavlik Nov 6, 2023
34624d7
Apply suggestions from code review
elf-pavlik Nov 6, 2023
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
93 changes: 93 additions & 0 deletions proposals/primer/app-authorization-flow.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
<figure>
<table class="data tree" align="left">
<col>
<col>
<thead>
<tr>
<th>Step</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>1</b></td>
<td>Alice finds an Application called Projectron that she'd like
to use to manage her Projects and Tasks.</td>
</tr>
<tr>
<td><b>2</b></td>
<td>Alice authenticates to Projectron with her WebID.</td>
</tr>
<tr>
<td><b>3</b></td>
<td>Projectron dereferences her WebID and retrieves Authorization Agent from her WebID Profile Document.</td>
</tr>
<tr>
<td><b>4</b></td>
<td>Projectron asks Alice's Authorization Agent whether Alice already has an Application Registration for Projectron.</td>
</tr>
<tr>
<td><b>5</b></td>
<td>Alice's Authorization Agent checks the Agent Registry in Alice's Pod for a Projectron Application Registration.</td>
</tr>
<tr>
<td><b>6</b></td>
<td>No Application Registration for Projectron is found.
Projectron now knows that Alice hasn't given it permission to access her data, so it must ask.</td>
</tr>
<tr>
<td><b>7</b></td>
<td>Projectron redirects Alice to her Authorization Agent, supplying its identifier for context.</td>
</tr>
<tr>
<td><b>8</b></td>
<td>Alice's Authorization Agent dereferences the supplied Projectron identifier, retrieving Projectron's
Application profile graph and corresponding Access Need Groups from the WebID Profile Document,
as well as <code>hasAuthorizationCallbackEndpoint</code>.</td>
</tr>
<tr>
<td><b>9</b></td>
<td>Alice's Authorization Agent presents the Access Need Groups from Projectron's Application
profile graph, so that Alice understands what kind of data is being requested, and why.</td>
</tr>
<tr>
<td><b>10</b></td>
<td>Alice's chooses the scope of access that Projectron will receive, to the data to
which it has asked for access via the presented Access Needs.</td>
</tr>
<tr>
<td><b>11-13</b></td>
<td>Alice's Authorization Agent records her decision as an Access Authorization in Alice's
Authorization Registry. An Application Registration is created for Projectron in
Alice's Agent Registry. An Access Grant and corresponding Data Grants are generated
from the Access Authorization and stored in the Projectron Application Registration.
</tr>
<tr>
<td><b>14</b></td>
<td>Alice's Authorization Agent redirects her back to Projectron, now that the appropriate access has been granted.</td>
</tr>
<tr>
<td><b>15</b></td>
<td>Projectron again asks Alice's Authorization Agent for a Projectron Application Registration.</td>
</tr>
<tr>
<td><b>16</b></td>
<td>Alice's Authorization Agent finds the newly created Projectron Application Registration in the Agent Registry in Alice's Pod.</td>
</tr>
<tr>
<td><b>17</b></td>
<td>Alice's Authorization Agent provides the URI of the Application Registration to Projectron.</td>
</tr>
<tr>
<td><b>18</b></td>
<td>Projectron learns what access it received through the Access Grant in Alice's Projectron Application Registration.</td>
</tr>
<tr>
<td><b>19</b></td>
<td>Projectron may now function as intended, within the scope of authorization it was given by Alice.</td>
</tr>
</tbody>
</table>
</figure>

<img class="sequence-diagram" src="diagrams/application-requests-access-flow.seq.mmd.svg">
18 changes: 13 additions & 5 deletions proposals/primer/application.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,16 +106,24 @@ Details in <a href="https://solid.github.io/data-interoperability-panel/specific

## User Consent ## {#user-consent}

In case where application haven't been registered yet it needs to initiate flow with Authorization Agent.
In cases where an application hasn't been registered yet, it needs to initiate the flow with the Authorization Agent.

Issue: Add details as soon as defined for Authorization Agent
After successful flow, the application will be able to discover its registration.

After successful flow aplication will be able to discover its registration.
<pre class=include>path: app-authorization-flow.bs</pre>

## Resource Indication ## {#resource-indication}

When the application has already been registered, and the user wants to
initiate a sharing-specific [[#data-instance]], an authorization flow with resource
indication is available.

<pre class=include>path: resource-indication-flow.bs</pre>

# Application Registration # {#application-registration}

Application Registration can be considered an entry point to all the data
that user authorized it to access. Next step in discovery of that data
that the user authorized it to access. The next step in the discovery of that data
is the Access Grant linked via <code>interop:hasAccessGrant</code> predicate.

<figure>
Expand Down Expand Up @@ -149,7 +157,7 @@ via <code>interop:hasDataGrant</code> predicate.

# Data Registration # {#data-registration}

<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png" />
<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png">

<figure>
<pre class=include-code>
Expand Down
24 changes: 14 additions & 10 deletions proposals/primer/authorization-agent.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ The Registry Set can be discovered from a social agent's WebID Profile using `in
While WebID Profile is readable to the public, Registry Set should only be readable by its owner
and their Authorization Agent.

<img class="flowchart-diagram" src="diagrams/registry-set.flow.mmd.png" />
<img class="flowchart-diagram" src="diagrams/registry-set.flow.mmd.png">

<figure>
<pre class=include-code>
Expand Down Expand Up @@ -86,7 +86,7 @@ In a Data Registry, there can be at most one Data Registration for any given sha
Data Registration is a container, which contains Data Instances. Each of those Data Instances conforms to one specific
shape tree assigned to the Data Registration.

<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png" />
<img class="flowchart-diagram" src="diagrams/pro.alice.example.flow.mmd.png">

<figure>
<pre class=include-code>
Expand All @@ -110,8 +110,6 @@ An Authorization Agent is not responsible for modifying data instances. Sometime
during [[#gathering-authorizations]] if the user wants to select specific data instances.


Issue(186):

# Authorization Registry # {#authorization-registry}

Authorization Registry is a container, which contains Access Authorizations.
Expand Down Expand Up @@ -200,7 +198,7 @@ from another Social Agent and performing [[#agent-registration-discovery]]
In the case of Social Agent Registration for ACME, created in Alice's Agent Registry. The reciprocal registration
will be the Social Agent Reigstration for Alice, created in ACME's Agent Registry.

<img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png" />
<img class="flowchart-diagram" src="diagrams/reciprocal-registration.flow.mmd.png">

## Application Registration

Expand Down Expand Up @@ -255,9 +253,9 @@ another's social agent Authorization Agent. The response will include a link to

## Access Grant ## {#access-grant}

An Access Grant grups together all the Data Grants provided for specific agent.
An Access Grant groups together all the Data Grants provided for a specific agent.

An Access Grant is immutable, it never gets updated, instead it can be only replaced with a newer Access Grant.
An Access Grant is immutable — it never gets updated; it can only be replaced, by a newer Access Grant.

<pre class=include>path: data-grant.bs</pre>

Expand Down Expand Up @@ -292,11 +290,17 @@ It should also assist the user in composing new Access Authorization, taking int
* Data Registries with Data Registrations and Data Instances
* [[#access-grant]] with [[#data-grant]] others issued to them (available via all the [[#reciprocal-registration]])

<img src="images/authorization-screen.svg" width="100%" />
<img src="images/authorization-screen.svg" width="100%">

<pre class=include>path: app-authorization-flow.bs</pre>

# Sharing resources indicated by the application # {#resource-indication}

Issue(186):
When the application has already been registered, and the user wants to
initiate a sharing-specific [[#data-instance]], an authorization flow with resource
indication is available.

Issue(138):
<pre class=include>path: resource-indication-flow.bs</pre>

# Generating Access Grant from Access Authorization # {#generating-grants-from-authorizations}

Expand Down
25 changes: 25 additions & 0 deletions proposals/primer/diagrams/application-requests-access-flow.seq.mmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
sequenceDiagram
participant Projectron's ID Document
participant Projectron
participant Authorization Agent
participant Alice's Pod
participant Alice's WebID Document
Note over Projectron: 1. 👩 Alice decides to use Projectron
Note over Projectron: 2. 👩 Alice authenticates with her WebID
Note over Alice's WebID Document,Projectron: 3. Projectron discovers Alice's Authorization Agent in her WebID Document
Projectron->>Authorization Agent: 4. Check for Application Registration
Note over Authorization Agent, Alice's Pod: 5. Searches for Application Registration
Authorization Agent->>Projectron: 6. No Application Registration Found
Projectron-->>Authorization Agent: 7. Redirects Alice to her Authorization Agent's Redirect Endpoint
Note over Projectron's ID Document, Authorization Agent: 8. Discovers Access Needs and Authorization Callback Endpoint
Note over Authorization Agent: 9. 👩 Alice revievs Projectron Access Needs
Note over Authorization Agent: 10. 👩 Alice chooses scope of access for Projectron
Note over Authorization Agent, Alice's Pod: 11. Record Access Authorization
Note over Authorization Agent, Alice's Pod: 12. Create Application Registration
Note over Authorization Agent, Alice's Pod: 13. Provide Access Grant
Authorization Agent-->>Projectron: 14. Redirect Alice back to Projectron
Projectron->>Authorization Agent: 15. Check for Application Registration
Note over Authorization Agent, Alice's Pod: 16. Serches for Application Registration
Authorization Agent->>Projectron: 17. Provide Application Registration
Note over Projectron, Alice's Pod: 18. Fetch Access Grant and Data Grants
Note over Projectron: 19. 🟢 Now can access all the data Alice authized it to access
19 changes: 19 additions & 0 deletions proposals/primer/diagrams/resource-indication.seq.mmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
sequenceDiagram
participant Projectron's ID Document
participant Projectron
participant Authorization Agent
participant Alice's Pod
Note over Projectron: 1. 👩 Alice is authenticated Projectron
Note over Projectron: 2. 👩 Alice has authorized Projectron
Note over Projectron, Alice's Pod: 3. Projectron has read its Access Grant and displayed projects
Note over Projectron: 4. 👩 Alice initiates sharing of a specific project
Projectron-->>Authorization Agent: 5. Redirect to Authorization Agent (indicating resource)
Note over Authorization Agent, Alice's Pod: 6. Fetch indicated project
Note over Authorization Agent, Alice's Pod: 7. Check who already has access to that project
Note over Authorization Agent, Alice's Pod: 8. Fetch list of all social agents
Note over Authorization Agent: 9. 👩 Alice chooses social agents and modes of access for each
Note over Authorization Agent, Alice's Pod: 10. Record new authorizations for selected agents
Note over Authorization Agent, Alice's Pod: 11. Regenerate access grants for selected agents
Note over Projectron's ID Document, Authorization Agent: 11. Discovers Projectron's Authorization Callback Endpoint
Authorization Agent-->>Projectron: 13. Redirect Alice back to Projectron
Note over Projectron: 14. 👩 Alice continues using Projectron
66 changes: 66 additions & 0 deletions proposals/primer/resource-indication-flow.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
<figure>
<table class="data tree" align="left">
<col>
<col>
<thead>
<tr>
<th>Step</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>1</b></td>
<td>Alice's is authenticated with Projectron.</td>
</tr>
<tr>
<td><b>2</b></td>
<td>Alice has already authorized Projectron.</td>
</tr>
<tr>
<td><b>3</b></td>
<td>Projectron has read its Access Grant and displayed projects.</td>
</tr>
<tr>
<td><b>4</b></td>
<td>Alice initiates sharing of a specific project.</td>
</tr>
<tr>
<td><b>5</b></td>
<td>Projectron redirects Alice to her Authorization Agent, indicating the selected project.</td>
</tr>
<tr>
<td><b>6-8</b></td>
<td>Alice's Authorization Agent fetches the indicated project and checks who already has access to it.
It also fetches list of all registered social agents to present it to Alice.</td>
</tr>
<tr>
<td><b>9</b></td>
<td>Alice chooses all the social agents with which she wants to share the selected project,
as well as modes of access for all selected agents. If the shape tree has references (e.g., tasks) she can
also select modes of access for each inherited shape tree.</td>
</tr>
<tr>
<td><b>10-11</b></td>
<td>Alice's Authorization Agent records new access authorizations for all the selected agents
and regenerates access grants provided in their agent registrations.</td>
</tr>
<tr>
<td><b>12</b></td>
<td>Alice's Authorization Agent dereferences the supplied Projectron WebID, retrieving Projection's
Application profile graph from the WebID Profile Document,
to discover the <code>hasAuthorizationCallbackEndpoint</code>.</td>
</tr>
<tr>
<td><b>13</b></td>
<td>Alice's Authorization Agent redirects her back to Projectron, now that the project has been shared.</td>
</tr>
<tr>
<td><b>14</b></td>
<td>Alice continues using Projectron.</td>
</tr>
</tbody>
</table>
</figure>

<img class="sequence-diagram" src="diagrams/resource-indication.seq.mmd.svg">
6 changes: 6 additions & 0 deletions proposals/specification/application.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,12 @@ use any resource or subject names.
<td>[=Access Need Group=] representing types of data the
[=Application=] needs to operate</td>
</tr>
<tr>
<td>hasAuthorizationCallbackEndpoint</td>
<td>IRI</td>
<td>URI used to redirect back from [=Authorization Agent=]
to the application, after completing authorization</td>
</tr>
</tbody>
</table>

Expand Down
Loading