Skip to content

Commit dc8fd99

Browse files
phwissmannphwissmann
authored
fix(docs): move auth from readme (#305)
2 parents 106e903 + 760f617 commit dc8fd99

File tree

2 files changed

+77
-76
lines changed

2 files changed

+77
-76
lines changed

‎README.md‎

Lines changed: 0 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -58,65 +58,3 @@ Deploy documentation to GitHub Pages
5858
```bash
5959
docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs ghcr.io/swissopenem/scopemarchiver-docs:latest gh-deploy
6060
```
61-
62-
## Authentication and securing of dashboards
63-
64-
Certain service pages do not support standard OAuth2/OIDC authentication mechanism, such as:
65-
66-
- Traefik dashboard
67-
- MinIO admin login
68-
- Grafana monitoring dashboard
69-
70-
To protect these pages, we use a proxy technology called **Forward Auth**. To achieve this, we need to configure the following:
71-
72-
- we need to tell Traefik to act as a **reverse proxy** to logically protect certain webpages
73-
- we do this by registering a so called **middleware** in traefik
74-
- this middleware will be of type [forwardauth](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) and redirects to a service called **authentik-proxy**, e.g. `traefik.http.middlewares.authentik.forwardauth.address: http://authentik-proxy:9000/outpost.goauthentik.io/auth/traefik`
75-
- `authentik-proxy` service integrates with Traefik's reverse proxy and acts as a **authentication gateway** to Authentik's **outpost**
76-
- an outpost in Authentik is a deployment that acts as a bridge between Authentik and external services, handling authentication and authorization.
77-
- in Authentik (our identity broker) we need to register
78-
- **Application**: basically a name and a URL where the application can be found. It is onnected to one provider
79-
- **Provider**: the mechanism we use _how_ to provide authentication and _source of the users_. For our use-case, we take a **Proxy Provider** of type **Forward Auth** at domain level, as all the service pages should be protected the same way. A provider can be connected to many applications.
80-
- **Outpost**: an entity that talks to the Authentik-proxy service and provides a AUTHENTIK_TOKEN for that service. It is also connected to the provider.
81-
- for every service page that we would like to protect, we have to tell Traefik's router to use the `authentik` middleware defined earlier, e.g. `traefik.http.routers.dashboard.middlewares=authentik`
82-
83-
84-
The following sequence diagram illustrates the authentication mechanism.
85-
86-
```mermaid
87-
88-
sequenceDiagram
89-
autonumber
90-
participant U as User Browser
91-
participant T as Traefik<br/>(reverse-proxy)
92-
participant S as Service Page
93-
participant O as authentik-proxy<br/>(outpost)
94-
participant AO as Authentik outpost
95-
participant AP as Authentik provider
96-
participant I as LDAP<br/>(identity provider)
97-
98-
U -) T: request access to service page
99-
T -) T: is user authenticated (cookie 🔑)?
100-
T -) O: redirect to outpost
101-
O -) AO: redirect to authentication (AUTHENTIK_TOKEN 🔑)
102-
AO -) AP: redirect to login page
103-
AP -) U: ask for username
104-
U -) AP: enter username
105-
AP -) I: check username exists
106-
I -) AP: OK
107-
AP -) I: authorization: username is in allowed groups
108-
I -) AP: OK
109-
AP -) U: ask for password (plus OTP, if needed)
110-
U -) AP: enter password 🔑
111-
AP -) I: check password 🔑
112-
I -) AP: password OK
113-
AP -) O: redirect (cookie 🔑)
114-
O -) T: redirect (cookie 🔑)
115-
T -) S: access service page
116-
117-
loop optional: sync users & groups
118-
AP -) I: get users, groups
119-
I -) AP: users, groups
120-
end
121-
122-
```

‎docs/architecture.md‎

Lines changed: 77 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,31 +8,94 @@
88

99
#### Archiver Service
1010

11-
| Name | Technology | Description | Endpoint |
12-
| ----------------------- | -------------------------------------- | ---------------------------------------------------------------- | --------------------------------------- |
13-
| Reverse Proxy | Traefik <https://traefik.io/traefik/> | Routes traffic to endpoints | <https://${HOST}/dashboard/> |
14-
| Backend Api | FastAPI <https://fastapi.tiangolo.com> | Endpoint for Scicat backend, requests flow scheduling by Prefect | <https://${HOST}/archiver/api/v1/docs> |
11+
| Name | Technology | Description | Endpoint |
12+
|-------------------------|----------------------------------------|------------------------------------------------------------------|-------------------------------------------------|
13+
| Reverse Proxy | Traefik <https://traefik.io/traefik/> | Routes traffic to endpoints | <https://${HOST}/dashboard/> |
14+
| Backend Api | FastAPI <https://fastapi.tiangolo.com> | Endpoint for Scicat backend, requests flow scheduling by Prefect | <https://${HOST}/archiver/api/v1/docs> |
1515
| Workflow Orchestraction | Prefect <https://www.prefect.io> | Orchestrates workflows for archival and retrieval operations | <https://${HOST}/archiver/prefect/ui/dashboard> |
1616

1717
#### Workflow Orchestration
1818

19-
| Name | Technology | Description | Endpoint |
20-
| -------------- | --------------------------------------------------------------------- | ----------- | ----------------------------------------------------- |
19+
| Name | Technology | Description | Endpoint |
20+
|----------------|-----------------------------------------------------------------------|-------------|-------------------------------------------------|
2121
| Prefect Server | <https://docs.prefect.io/3.0/manage/self-host> | | <https://${HOST}/archiver/prefect/ui/dashboard> |
22-
| Prefect Worker | <https://docs.prefect.io/3.0/deploy/infrastructure-concepts/workers> | | n/a |
23-
| Prefect Flow | <https://docs.prefect.io/3.0/develop/write-flows#write-and-run-flows> | | n/a |
22+
| Prefect Worker | <https://docs.prefect.io/3.0/deploy/infrastructure-concepts/workers> | | n/a |
23+
| Prefect Flow | <https://docs.prefect.io/3.0/develop/write-flows#write-and-run-flows> | | n/a |
2424

2525
#### Storage Components
2626

2727
| Name | Technology | Description | Endpoint |
28-
| -------------- | ---------------------- | ---------------------------------------------------------------------- | ------------------------- |
28+
|----------------|------------------------|------------------------------------------------------------------------|---------------------------|
2929
| Storage Server | Minio <https://min.io> | Storage for datasets that are to be archived or are retrievable | <http://localhost/minio/> |
3030
| LTS Share | NFS Network share | ETHZ Long term storage where datasets are stored on and retrieved from | n/a |
3131

3232
#### External Components
3333

34-
| Name | Technology | Description | Endpoint |
35-
| -------- | ------------------------------------------------ | -------------------------------------------------------------------------------------- | --------------------------- |
36-
| Ingestor | Golang <https://github.com/SwissOpenEM/Ingestor> | Client application to select, ingest, and upload datasets | n/a |
37-
| SciCat Frontend | Node.js <https://scicatproject.github.io> | Data catalog frontend where datasets are registered and archival/retrieval is triggered | <https://discovery.psi.ch/>, <https://${HOST}/> |
38-
| SciCat Backend | Node.js <https://scicatproject.github.io> | Data catalog backend where datasets are registered and archival/retrieval is triggered | <https://dacat.psi.ch/explorer/>, <https://${HOST}/scicat/backend/explorer> |
34+
| Name | Technology | Description | Endpoint |
35+
|-----------------|--------------------------------------------------|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
36+
| Ingestor | Golang <https://github.com/SwissOpenEM/Ingestor> | Client application to select, ingest, and upload datasets | n/a |
37+
| SciCat Frontend | Node.js <https://scicatproject.github.io> | Data catalog frontend where datasets are registered and archival/retrieval is triggered | <https://discovery.psi.ch/>, <https://${HOST}/> |
38+
| SciCat Backend | Node.js <https://scicatproject.github.io> | Data catalog backend where datasets are registered and archival/retrieval is triggered | <https://dacat.psi.ch/explorer/>, <https://${HOST}/scicat/backend/explorer> |
39+
40+
41+
## Authentication
42+
43+
Certain service pages do not support standard OAuth2/OIDC authentication mechanism, such as:
44+
45+
- Traefik dashboard
46+
- MinIO admin login
47+
- Grafana monitoring dashboard
48+
49+
To protect these pages, we use a proxy technology called **Forward Auth**. To achieve this, we need to configure the following:
50+
51+
- we need to tell Traefik to act as a **reverse proxy** to logically protect certain webpages
52+
- we do this by registering a so called **middleware** in traefik
53+
- this middleware will be of type [forwardauth](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) and redirects to a service called **authentik-proxy**, e.g. `traefik.http.middlewares.authentik.forwardauth.address: http://authentik-proxy:9000/outpost.goauthentik.io/auth/traefik`
54+
- `authentik-proxy` service integrates with Traefik's reverse proxy and acts as a **authentication gateway** to Authentik's **outpost**
55+
- an outpost in Authentik is a deployment that acts as a bridge between Authentik and external services, handling authentication and authorization.
56+
- in Authentik (our identity broker) we need to register
57+
- **Application**: basically a name and a URL where the application can be found. It is onnected to one provider
58+
- **Provider**: the mechanism we use _how_ to provide authentication and _source of the users_. For our use-case, we take a **Proxy Provider** of type **Forward Auth** at domain level, as all the service pages should be protected the same way. A provider can be connected to many applications.
59+
- **Outpost**: an entity that talks to the Authentik-proxy service and provides a AUTHENTIK_TOKEN for that service. It is also connected to the provider.
60+
- for every service page that we would like to protect, we have to tell Traefik's router to use the `authentik` middleware defined earlier, e.g. `traefik.http.routers.dashboard.middlewares=authentik`
61+
62+
63+
The following sequence diagram illustrates the authentication mechanism.
64+
65+
```mermaid
66+
67+
sequenceDiagram
68+
autonumber
69+
participant U as User Browser
70+
participant T as Traefik<br/>(reverse-proxy)
71+
participant S as Service Page
72+
participant O as authentik-proxy<br/>(outpost)
73+
participant AO as Authentik outpost
74+
participant AP as Authentik provider
75+
participant I as LDAP<br/>(identity provider)
76+
77+
U -) T: request access to service page
78+
T -) T: is user authenticated (cookie 🔑)?
79+
T -) O: redirect to outpost
80+
O -) AO: redirect to authentication (AUTHENTIK_TOKEN 🔑)
81+
AO -) AP: redirect to login page
82+
AP -) U: ask for username
83+
U -) AP: enter username
84+
AP -) I: check username exists
85+
I -) AP: OK
86+
AP -) I: authorization: username is in allowed groups
87+
I -) AP: OK
88+
AP -) U: ask for password (plus OTP, if needed)
89+
U -) AP: enter password 🔑
90+
AP -) I: check password 🔑
91+
I -) AP: password OK
92+
AP -) O: redirect (cookie 🔑)
93+
O -) T: redirect (cookie 🔑)
94+
T -) S: access service page
95+
96+
loop optional: sync users & groups
97+
AP -) I: get users, groups
98+
I -) AP: users, groups
99+
end
100+
101+
```

0 commit comments

Comments
 (0)