You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
1. Deploy your Directory instance (see [Getting Started](https://docs.agntcy.org/dir/getting-started/))
51
-
2. Setup federation (see [Client Onboarding Guide](onboarding/README.md) after deployment)
52
-
53
-
As of `dir``v1.3.0`, the Helm chart provides a default DHT bootstrap address for the public testbed. In most cases you should leave bootstrap-peer settings unset in your values unless you intentionally need to override that default.
54
-
55
-
---
56
-
57
-
## Optional OIDC/SPIFFE Authentication Gateway
58
-
59
-
The default Directory deployment in this repository uses SPIFFE/SPIRE-oriented authentication that works well for in-cluster workloads. If you also want to support `dirctl`, SDKs, or automation running **outside** the cluster, deploy the standalone `oidc-gateway` application alongside `dir`.
60
-
61
-
The public gateway chart lives in the dedicated repository:
1. A remote client presents an OIDC JWT, SPIFFE JWT-SVID, or SPIFFE X.509-SVID.
68
-
2. Envoy validates bearer JWTs with `jwt_authn` or downstream SPIFFE mTLS when enabled.
69
-
3. The ext-authz service normalizes the caller to a canonical principal and checks allowed gRPC methods.
70
-
4. Only authorized requests are forwarded to the internal Directory apiserver with the configured principal header.
71
-
72
-
### When to Use It
73
-
74
-
Use the OIDC gateway when:
75
-
76
-
- You want remote `dirctl` access from a laptop or workstation outside the cluster
77
-
- You want a human login flow backed by Dex
78
-
- You want GitHub Actions or other external automation to call Directory with OIDC tokens
79
-
80
-
You do not need this gateway if you only use in-cluster, SPIFFE-based access.
81
-
82
-
### What to Configure
83
-
84
-
The staging example now includes a separate `oidc-gateway` app under `applications/oidc-gateway/dev/`. The main settings are:
85
-
86
-
-`envoy.backend.*`: points Envoy at the internal Directory service
87
-
-`envoy.oidc.issuers[]`: configures Envoy `jwt_authn` providers and JWKS lookup for bearer-token validation
88
-
-`envoy.oidc.github.*`: configures GitHub Actions OIDC for automation
89
-
-`authServer.oidc.issuers`: maps verified token issuers to stable provider keys such as `dex` or `github`
90
-
-`authServer.oidc.headers.authPrincipal`: sets the canonical principal header forwarded to Directory (`x-auth-principal` by default)
91
-
-`authServer.oidc.roles`: maps canonical principals such as `oidc:dex:alice`, `oidc:github:repo:...`, or `spiffe:spiffe://...` to allowed gRPC methods
92
-
-`ingress.*`: exposes the Envoy gateway for external access over gRPC
93
-
94
-
### Dex and Remote Clients
95
-
96
-
If you want interactive user login, configure Dex in `applications/dex/dev/values.yaml` and make sure:
97
-
98
-
-`config.issuer` matches the public URL where Dex is reachable
99
-
- your GitHub OAuth app credentials are supplied through a Kubernetes Secret
100
-
- the Dex issuer values in `applications/dex/dev/values.yaml` and `applications/oidc-gateway/dev/values.yaml` match
101
-
102
-
Enabling Dex by itself is not enough for remote Directory access. Remote clients also need the standalone `oidc-gateway` deployed so their OIDC tokens can be validated before requests reach Directory.
103
-
104
-
### Canonical Field Reference
105
-
106
-
The staging values file is a user-facing example. For the complete public source of truth for all supported fields, see:
## Next Steps: Connecting to the Directory Network
114
-
115
-
After deploying your Directory instance (see [Getting Started](https://docs.agntcy.org/dir/getting-started/)), it will be **isolated** and cannot discover agents from other organizations.
116
-
117
-
### Why Join the Network?
118
-
119
-
**Current State (Standalone):**
120
-
- ✅ Your Directory works for your organization
121
-
- ❌ Cannot discover agents from other organizations
122
-
- ❌ Your agents are not discoverable by others
123
-
- ❌ Limited to your own trust domain
124
-
125
-
**After Federation:**
126
-
- ✅ All standalone benefits
127
-
- ✅ Discover agents across multiple organizations
128
-
- ✅ Your agents become globally discoverable
129
-
- ✅ Part of decentralized discovery network
130
-
131
-
### How to Setup Federation
132
-
133
-
Federation requires configuring SPIRE to exchange trust bundles with other Directory instances.
134
-
135
-
**Follow these steps:**
136
-
137
-
1.**Choose a Federation Profile**
138
-
-**https_web** (recommended): Uses standard HTTPS + Let's Encrypt, no SSL passthrough needed
1. Deploy your Directory instance (see [Getting Started](https://docs.agntcy.org/dir/getting-started/))
30
+
2. Setup federation (see [Client Onboarding Guide](../onboarding/README.md) after deployment)
31
+
32
+
As of `dir``v1.3.0`, the Helm chart provides a default DHT bootstrap address for the public testbed. In most cases you should leave bootstrap-peer settings unset in your values unless you intentionally need to override that default.
33
+
34
+
## Related Documentation
35
+
36
+
-[Federation Profiles](dir-federation-profiles.md) — compare `https_web` and `https_spiffe` bundle endpoint profiles
37
+
-[Partner Federation with Prod](dir-federation-setup.md) — federate with the public Directory at `spire.ads.outshift.io`
The default Directory deployment in this repository uses SPIFFE/SPIRE-oriented authentication that works well for in-cluster workloads. If you also want to support `dirctl`, SDKs, or automation running **outside** the cluster, deploy the standalone `oidc-gateway` application alongside `dir`.
4
+
5
+
The public gateway chart lives in the dedicated repository:
1. A remote client presents an OIDC JWT, SPIFFE JWT-SVID, or SPIFFE X.509-SVID.
12
+
2. Envoy validates bearer JWTs with `jwt_authn` or downstream SPIFFE mTLS when enabled.
13
+
3. The ext-authz service normalizes the caller to a canonical principal and checks allowed gRPC methods.
14
+
4. Only authorized requests are forwarded to the internal Directory apiserver with the configured principal header.
15
+
16
+
## When to Use It
17
+
18
+
Use the OIDC gateway when:
19
+
20
+
- You want remote `dirctl` access from a laptop or workstation outside the cluster
21
+
- You want a human login flow backed by Dex
22
+
- You want GitHub Actions or other external automation to call Directory with OIDC tokens
23
+
24
+
You do not need this gateway if you only use in-cluster, SPIFFE-based access.
25
+
26
+
## What to Configure
27
+
28
+
The staging example includes a separate `oidc-gateway` app under `applications/oidc-gateway/dev/`. The main settings are:
29
+
30
+
-`envoy.backend.*`: points Envoy at the internal Directory service
31
+
-`envoy.oidc.issuers[]`: configures Envoy `jwt_authn` providers and JWKS lookup for bearer-token validation
32
+
-`envoy.oidc.github.*`: configures GitHub Actions OIDC for automation
33
+
-`authServer.oidc.issuers`: maps verified token issuers to stable provider keys such as `dex` or `github`
34
+
-`authServer.oidc.headers.authPrincipal`: sets the canonical principal header forwarded to Directory (`x-auth-principal` by default)
35
+
-`authServer.oidc.roles`: maps canonical principals such as `oidc:dex:alice`, `oidc:github:repo:...`, or `spiffe:spiffe://...` to allowed gRPC methods
36
+
-`ingress.*`: exposes the Envoy gateway for external access over gRPC
37
+
38
+
## Dex and Remote Clients
39
+
40
+
If you want interactive user login, configure Dex in `applications/dex/dev/values.yaml` and make sure:
41
+
42
+
-`config.issuer` matches the public URL where Dex is reachable
43
+
- your GitHub OAuth app credentials are supplied through a Kubernetes Secret
44
+
- the Dex issuer values in `applications/dex/dev/values.yaml` and `applications/oidc-gateway/dev/values.yaml` match
45
+
46
+
Enabling Dex by itself is not enough for remote Directory access. Remote clients also need the standalone `oidc-gateway` deployed so their OIDC tokens can be validated before requests reach Directory.
47
+
48
+
## Canonical Field Reference
49
+
50
+
The staging values file is a user-facing example. For the complete public source of truth for all supported fields, see:
0 commit comments