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
| Auth works locally but fails when ORB runs as a system service | The service env does not inherit `$HOME`| Set `ORB_K8S_KUBECONFIG_PATH` to an absolute path. |
132
132
| Auth works initially then 401s after some hours (EKS) | Federated token expired | Use `aws eks update-kubeconfig` with a long-lived identity, or run ORB in-cluster with IRSA. |
133
133
134
+
## Inbound TokenReview auth
135
+
136
+
ORB can optionally validate Bearer tokens on its own REST API by
137
+
submitting them to the Kubernetes
138
+
`authentication.k8s.io/v1 TokenReview` endpoint. This lets callers
139
+
of ORB's REST API authenticate with a Kubernetes ServiceAccount token
140
+
instead of a separate credential system.
141
+
142
+
### Enabling
143
+
144
+
Set `inbound_auth_enabled: true` in the provider config (or
145
+
`ORB_K8S_INBOUND_AUTH_ENABLED=true`) to register the
146
+
`KubeAuthStrategy` with ORB's auth registry.
147
+
148
+
```json
149
+
{
150
+
"providers": {
151
+
"k8s": {
152
+
"provider_type": "k8s",
153
+
"namespace": "orb",
154
+
"inbound_auth_enabled": true
155
+
}
156
+
}
157
+
}
158
+
```
159
+
160
+
### How it works
161
+
162
+
1. An inbound REST request arrives with an `Authorization: Bearer <token>` header.
163
+
2. ORB extracts the token and submits it to `authentication.k8s.io/v1 TokenReview`
164
+
on the cluster.
165
+
3. If the API server reports the token is authenticated, the
166
+
`system:serviceaccount:<namespace>:<name>` principal is extracted.
167
+
4. The principal is mapped to an ORB role using the `sa_role_mapping`
168
+
in the auth config. Principals not in the map receive the default
169
+
`["user"]` role. Exact matches (`namespace:sa-name`) take priority;
170
+
wildcard namespace matches (`*:sa-name`) are tried next.
171
+
172
+
TokenReview is preferred over local JWKS validation because the API
173
+
server is the authoritative signer — there is no possibility of ORB
174
+
accepting a token the cluster itself would reject.
175
+
176
+
### Required RBAC
177
+
178
+
The ORB pod's ServiceAccount must be able to create `TokenReview`
179
+
objects. The recommended approach is to bind the
180
+
`system:auth-delegator` ClusterRole (a standard Kubernetes role that
181
+
grants precisely this permission):
182
+
183
+
```yaml
184
+
apiVersion: rbac.authorization.k8s.io/v1
185
+
kind: ClusterRoleBinding
186
+
metadata:
187
+
name: orb-auth-delegator
188
+
subjects:
189
+
- kind: ServiceAccount
190
+
name: orb
191
+
namespace: orb
192
+
roleRef:
193
+
apiGroup: rbac.authorization.k8s.io
194
+
kind: ClusterRole
195
+
name: system:auth-delegator
196
+
```
197
+
198
+
Alternatively, grant only `tokenreviews: create` on the
199
+
`authentication.k8s.io` API group via a targeted ClusterRole:
200
+
201
+
```yaml
202
+
apiVersion: rbac.authorization.k8s.io/v1
203
+
kind: ClusterRole
204
+
metadata:
205
+
name: orb-tokenreview
206
+
rules:
207
+
- apiGroups: ["authentication.k8s.io"]
208
+
resources: ["tokenreviews"]
209
+
verbs: ["create"]
210
+
```
211
+
212
+
Both options are included (commented out) in [`rbac.yaml`](rbac.yaml).
213
+
214
+
### Role mapping
215
+
216
+
Configure which ServiceAccounts map to which ORB roles in the auth
217
+
config section (not the provider config):
218
+
219
+
```json
220
+
{
221
+
"auth": {
222
+
"provider_auth": {
223
+
"kubernetes": {
224
+
"sa_role_mapping": {
225
+
"orb-system:orb-admin": ["admin"],
226
+
"orb-system:orb-operator": ["operator"],
227
+
"*:ci-runner": ["user"]
228
+
}
229
+
}
230
+
}
231
+
}
232
+
}
233
+
```
234
+
235
+
Principals not matched by any entry default to `["user"]`.
236
+
237
+
### Troubleshooting
238
+
239
+
| Symptom | Likely cause | Fix |
240
+
|---|---|---|
241
+
| `403 Forbidden` when ORB submits a `TokenReview` | ORB's ServiceAccount lacks `tokenreviews: create` | Apply the auth-delegator ClusterRoleBinding from [`rbac.yaml`](rbac.yaml). |
242
+
| Callers get `Token rejected by Kubernetes API server` | Token has expired or is not a valid projected SA token | The caller must obtain a fresh projected token via `kubectl create token`. |
243
+
| Auth succeeds but the caller gets the wrong role | SA principal not in `sa_role_mapping` | Add the `namespace:sa-name` entry to the mapping; or it matched a wildcard entry — check the order. |
0 commit comments