Skip to content

Commit 1b84e90

Browse files
jmaupetitjmaupetit
authored
Merge pull request #5 from openburo/add-backend-approach-docs
Add draft backend spec
2 parents 3610205 + 7599c99 commit 1b84e90

9 files changed

Lines changed: 416 additions & 18 deletions

‎docs/approche-back.md‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

‎docs/backend-approach/appendices.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
layout: default
3+
title: Backend approach: appendices
4+
nav_order: 4
5+
---
6+
7+
# Backend approach: appendices
8+
9+
10+
[← Backend approach](./index.md) · [Accueil](../index.md)
11+
12+
---
13+
14+
## The Token Exchange Flow (RFC 8693)
15+
16+
1. **Initial Authentication**
17+
- The end-user authenticates with the **Primary IdP**, which issues an
18+
initial **access token** or **ID token**.
19+
20+
2. **Token Exchange Request**
21+
- The client application sends the initial token to the **Token Exchange
22+
Service**, requesting a new token for a specific **target resource** or
23+
**audience**.
24+
- The request includes:
25+
- `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`
26+
- `subject_token`: The initial token.
27+
- `subject_token_type`: The type of the initial token (e.g.,
28+
`urn:ietf:params:oauth:token-type:access_token`).
29+
- `audience`: The target resource or service.
30+
- `scope`: The requested permissions for the new token.
31+
32+
3. **Token Transformation**
33+
- The **Token Exchange Service** validates the initial token and issues a
34+
new token tailored for the target resource. This new token may have:
35+
- Restricted scopes.
36+
- Additional claims.
37+
- A different audience or issuer.
38+
39+
4. **Access to Resource Server**
40+
- The client application uses the exchanged token to access the **Resource
41+
Server**, which validates the token and grants access based on its claims
42+
and scopes.
43+

‎docs/backend-approach/demo.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
layout: default
3+
title: Backend approach: demo
4+
nav_order: 4
5+
---
6+
7+
# Backend approach: demo
8+
9+
[← Backend approach](./index.md) · [Accueil](../index.md)
10+
11+
---
12+
13+
## OpenBuro router
14+
15+
We developed a POC server that can act as a proxy exposing the OpenBuro file
16+
picker API for services that are not natively integrated with OpenBuro.
17+
18+
Source code of the project is available at:
19+
https://github.com/openburo/openburo-router
20+
21+
You will find a back-end with different connectors to:
22+
23+
- Twake
24+
- Google Drive
25+
- Jamespot
26+
- Nextcloud
27+
28+
And also a front-end to showcase the integration.
29+
30+
> Note that only API server and connectors have been developed during this
31+
> first technical sprint. OIDC resource server and authorization server
32+
> implementations have been bypassed on purpose.

‎docs/backend-approach/index.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
layout: default
3+
title: Backend approach
4+
nav_order: 4
5+
---
6+
7+
# Backend approach
8+
9+
[← Approche front](proposition-hackathon/) · [Accueil](index.md)
10+
11+
---
12+
13+
## Architecture
14+
15+
![Minimal Viable Architecture](openburo-filepicker.drawio.svg)
16+
17+
## Principles
18+
19+
The consumer.com service will use server to server communication using a
20+
specified resource server API to pick files from the openburo-certified
21+
drive.com service.
22+
23+
The Open Buro initiative provides an OpenBuro "router" that acts as a proxy to
24+
drive services that do not implement the resource server API specification.
25+
26+
> The target architecture depicted in the schema illustrates a **federated
27+
> identity and access management system** leveraging **OpenID Connect (OIDC)**
28+
> and the **OAuth 2.0 Token Exchange (RFC 8693)**. This architecture enables
29+
> secure delegation of authentication and authorization across multiple trust
30+
> domains, allowing services to exchange tokens while maintaining strict
31+
> control over access rights and security policies.
32+
33+
---
34+
35+
### Key Components
36+
37+
1. **OpenBuro-specified resource server API** (drive.com or openburo router)
38+
- Services or APIs that require tokens for access. They validate tokens
39+
issued by the Token Exchange Service or directly by the IdPs, ensuring that
40+
only authorized requests are processed.
41+
- The openburo router acts as a proxy with services that does implement
42+
expected resources server API endpoints
43+
- Servers are expected to implement the specified file-picking capability
44+
(see next section).
45+
46+
2. **Identity Providers (IdPs)**
47+
- **Primary IdP**: The central identity provider responsible for
48+
authenticating end-users and issuing initial tokens (e.g., ID tokens, access
49+
tokens).
50+
- **Secondary IdPs**: Additional identity providers that may issue tokens
51+
for specific domains or services, enabling cross-domain authentication and
52+
authorization.
53+
54+
3. **Token Exchange Service**
55+
- A dedicated service implementing **RFC 8693 (Token Exchange)**. It acts as
56+
an intermediary to exchange tokens between different trust domains, ensuring
57+
that tokens are transformed, restricted, or enriched according to the target
58+
service’s requirements.
59+
60+
4. **Client Applications (consumer.com)**
61+
- Applications or services that consume tokens to access resources on behalf
62+
of users. They interact with the Token Exchange Service to obtain tokens
63+
with the appropriate scopes and claims for the target resource.
64+
65+
---
66+
67+
### Security Considerations
68+
69+
- **Token Validation**: All tokens must be validated for integrity, issuer,
70+
audience, and expiration.
71+
- **Scope Restriction**: The Token Exchange Service ensures that exchanged
72+
tokens do not grant more privileges than the original token.
73+
- **Audit and Traceability**: All token exchanges are logged for security
74+
auditing and compliance.
75+
- **Consent Management**: User consent is managed transparently, especially
76+
when tokens are exchanged across trust domains.
77+
78+
## Motivations
79+
80+
### Pros
81+
82+
- This architecture provides a **scalable, secure, and interoperable**
83+
framework for federated identity and access management, leveraging **OIDC** and
84+
**Token Exchange (RFC 8693)**.
85+
- Each service consuming a resource is free to implement it's own UI/UX to
86+
access the resource.
87+
88+
### Cons
89+
90+
- Proposed architecture relies on a circle of trust: if you share a token with
91+
a third party application, it implies that the later is trustworthy as it will
92+
have access to a user token to perform actions on behalf of users. The token
93+
exchange specification mitigate the scope of possible actions in a limited
94+
time, but does not solve the OIDC resource server trust issue.
95+
96+
## Technical specifications
97+
98+
- [Resource server API](./specification.md)
99+
- [Demo](./demo.md)
100+
- [Appendices](./appendices.md)

‎docs/backend-approach/openburo-filepicker.drawio‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64; rv:148.0) Gecko/20100101 Firefox/148.0">
2+
<diagram name="Page-1" id="Miq5_UqQhUQHEElPLVpS">
3+
<mxGraphModel dx="2601" dy="1224" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0" />
6+
<mxCell id="1" parent="0" />
7+
<mxCell id="0_j7Obm5OifOXc6rpGYc-11" edge="1" parent="1" source="0_j7Obm5OifOXc6rpGYc-1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="0_j7Obm5OifOXc6rpGYc-4">
8+
<mxGeometry relative="1" as="geometry" />
9+
</mxCell>
10+
<mxCell id="0_j7Obm5OifOXc6rpGYc-1" parent="1" style="swimlane;startSize=0;" value="" vertex="1">
11+
<mxGeometry height="80" width="160" x="530" y="40" as="geometry" />
12+
</mxCell>
13+
<mxCell id="0_j7Obm5OifOXc6rpGYc-3" parent="0_j7Obm5OifOXc6rpGYc-1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" value="&lt;div&gt;&lt;font style=&quot;font-size: 18px;&quot;&gt;consumer.com&lt;/font&gt;&lt;/div&gt;&lt;div&gt;frontend&lt;/div&gt;" vertex="1">
14+
<mxGeometry height="30" width="60" x="50" y="25" as="geometry" />
15+
</mxCell>
16+
<mxCell id="0_j7Obm5OifOXc6rpGYc-14" edge="1" parent="1" source="0_j7Obm5OifOXc6rpGYc-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;startArrow=classic;startFill=1;" target="0_j7Obm5OifOXc6rpGYc-12">
17+
<mxGeometry relative="1" as="geometry" />
18+
</mxCell>
19+
<mxCell id="0_j7Obm5OifOXc6rpGYc-18" edge="1" parent="1" source="0_j7Obm5OifOXc6rpGYc-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="0_j7Obm5OifOXc6rpGYc-7">
20+
<mxGeometry relative="1" as="geometry" />
21+
</mxCell>
22+
<mxCell id="0_j7Obm5OifOXc6rpGYc-23" edge="1" parent="1" source="0_j7Obm5OifOXc6rpGYc-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" target="0_j7Obm5OifOXc6rpGYc-6">
23+
<mxGeometry relative="1" as="geometry" />
24+
</mxCell>
25+
<mxCell id="0_j7Obm5OifOXc6rpGYc-4" parent="1" style="swimlane;startSize=0;" value="" vertex="1">
26+
<mxGeometry height="80" width="160" x="530" y="150" as="geometry">
27+
<mxRectangle height="40" width="50" x="180" y="190" as="alternateBounds" />
28+
</mxGeometry>
29+
</mxCell>
30+
<mxCell id="0_j7Obm5OifOXc6rpGYc-5" parent="0_j7Obm5OifOXc6rpGYc-4" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" value="&lt;div&gt;&lt;font style=&quot;font-size: 18px;&quot;&gt;consumer.com&lt;/font&gt;&lt;/div&gt;&lt;div&gt;backend&lt;/div&gt;" vertex="1">
31+
<mxGeometry height="30" width="60" x="50" y="25" as="geometry" />
32+
</mxCell>
33+
<mxCell id="0_j7Obm5OifOXc6rpGYc-27" edge="1" parent="1" source="0_j7Obm5OifOXc6rpGYc-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;startArrow=classic;startFill=1;" target="0_j7Obm5OifOXc6rpGYc-9">
34+
<mxGeometry relative="1" as="geometry" />
35+
</mxCell>
36+
<mxCell id="0_j7Obm5OifOXc6rpGYc-6" parent="1" style="whiteSpace=wrap;html=1;aspect=fixed;" value="&lt;div&gt;&lt;font style=&quot;font-size: 18px;&quot;&gt;OpenBuro&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;router&lt;/font&gt;&lt;/div&gt;" vertex="1">
37+
<mxGeometry height="120" width="120" x="420" y="380" as="geometry" />
38+
</mxCell>
39+
<mxCell id="0_j7Obm5OifOXc6rpGYc-7" parent="1" style="whiteSpace=wrap;html=1;aspect=fixed;" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;drive.com&lt;/font&gt;" vertex="1">
40+
<mxGeometry height="120" width="120" x="680" y="380" as="geometry" />
41+
</mxCell>
42+
<mxCell id="0_j7Obm5OifOXc6rpGYc-9" parent="1" style="whiteSpace=wrap;html=1;aspect=fixed;" value="&lt;font style=&quot;font-size: 18px;&quot;&gt;nextcloud&lt;/font&gt;" vertex="1">
43+
<mxGeometry height="120" width="120" x="240" y="380" as="geometry" />
44+
</mxCell>
45+
<mxCell id="0_j7Obm5OifOXc6rpGYc-10" parent="1" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;" value="" vertex="1">
46+
<mxGeometry height="50" width="50" x="770" y="360" as="geometry" />
47+
</mxCell>
48+
<mxCell id="0_j7Obm5OifOXc6rpGYc-22" edge="1" parent="1" source="0_j7Obm5OifOXc6rpGYc-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0;startArrow=classic;startFill=1;" target="0_j7Obm5OifOXc6rpGYc-7">
49+
<mxGeometry relative="1" as="geometry" />
50+
</mxCell>
51+
<mxCell id="0_j7Obm5OifOXc6rpGYc-12" parent="1" style="rounded=0;whiteSpace=wrap;html=1;" value="&lt;div&gt;&lt;font style=&quot;font-size: 18px;&quot;&gt;Identity&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;Provider&lt;/font&gt;&lt;/div&gt;" vertex="1">
52+
<mxGeometry height="120" width="160" x="770" y="130" as="geometry" />
53+
</mxCell>
54+
<mxCell id="0_j7Obm5OifOXc6rpGYc-15" parent="1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" value="&lt;div&gt;access&lt;/div&gt;&lt;div&gt;token&lt;/div&gt;" vertex="1">
55+
<mxGeometry height="30" width="60" x="700" y="150" as="geometry" />
56+
</mxCell>
57+
<mxCell id="0_j7Obm5OifOXc6rpGYc-17" parent="1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" value="&lt;div&gt;exchanged&lt;/div&gt;&lt;div&gt;token&lt;/div&gt;" vertex="1">
58+
<mxGeometry height="30" width="60" x="700" y="204" as="geometry" />
59+
</mxCell>
60+
<mxCell id="0_j7Obm5OifOXc6rpGYc-19" parent="1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;rounded=0;" value="&lt;div&gt;exchanged&lt;/div&gt;&lt;div&gt;token&lt;/div&gt;" vertex="1">
61+
<mxGeometry height="30" width="60" x="580" y="320" as="geometry" />
62+
</mxCell>
63+
<mxCell id="0_j7Obm5OifOXc6rpGYc-24" parent="1" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;" value="" vertex="1">
64+
<mxGeometry height="50" width="50" x="240" y="40" as="geometry" />
65+
</mxCell>
66+
<mxCell id="0_j7Obm5OifOXc6rpGYc-25" parent="1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;rounded=0;" value="&lt;div align=&quot;left&quot;&gt;&lt;b&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;OpenBuro&lt;/font&gt;&lt;/b&gt;&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;&lt;b&gt;&lt;font size=&quot;3&quot;&gt;certified&lt;/font&gt;&lt;/b&gt;&lt;/div&gt;" vertex="1">
67+
<mxGeometry height="30" width="60" x="300" y="50" as="geometry" />
68+
</mxCell>
69+
<mxCell id="0_j7Obm5OifOXc6rpGYc-28" parent="1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=left;verticalAlign=middle;rounded=0;" value="&lt;div align=&quot;left&quot;&gt;token&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;introspection&lt;/div&gt;" vertex="1">
70+
<mxGeometry height="30" width="60" x="860" y="320" as="geometry" />
71+
</mxCell>
72+
<mxCell id="0_j7Obm5OifOXc6rpGYc-32" parent="1" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;" value="" vertex="1">
73+
<mxGeometry height="50" width="50" x="510" y="360" as="geometry" />
74+
</mxCell>
75+
</root>
76+
</mxGraphModel>
77+
</diagram>
78+
</mxfile>

‎docs/backend-approach/openburo-filepicker.drawio.png‎

50.5 KB
Loading

‎docs/backend-approach/openburo-filepicker.drawio.svg‎

Lines changed: 4 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)