Skip to content

Commit b6c22a8

Browse files
committed
docs(authorization): update dex configuration guide
- Replace GitHub App with OAuth App instructions - Update localhost URLs from 0.0.0.0 to localhost - Change storage backend from sqlite3 to memory for easy of demo Signed-off-by: Ervin Rácz <ervin.racz@protonmail.com>
1 parent ea3b2dc commit b6c22a8

File tree

1 file changed

+30
-59
lines changed
  • content/docs/latest/nebraska/authorization

1 file changed

+30
-59
lines changed

content/docs/latest/nebraska/authorization/_index.md

Lines changed: 30 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -115,9 +115,9 @@ Now the member and admin roles are created, the admin role is a composite role w
115115

116116
1. Click on `Client Scopes > nebraska-dedicated`.
117117
2. Click on `Configure a new mapper`
118-
2. Click on `User Client Role`
119-
2. Set the name as `roles`, Select the `Mapper Type` as `User Client Role`, `Token Claim Name` as `roles` and Select `Claim JSON Type` as String.
120-
3. Click `Save`
118+
3. Click on `User Client Role`
119+
4. Set the name as `roles`, Select the `Mapper Type` as `User Client Role`, `Token Claim Name` as `roles` and Select `Claim JSON Type` as String.
120+
5. Click `Save`
121121

122122
{{< presentation "keycloak-scope-token" >}}
123123

@@ -237,35 +237,17 @@ Note: The `oidc-roles-path` argument accepts a JSONPath to fetch roles from the
237237

238238
- Create a new `organization` in Github.
239239

240-
- Now you need a Github app, go to `https://github.com/organizations/<ORG>/settings/apps/new` and fill
241-
the following fields:
242-
- `GitHub App name` - just put some fancy name.
243-
240+
- Now you need to create an OAuth App, go to `https://github.com/organizations/<your-organization>/settings/applications` (Your Organization Settings > Developer Settongs > OAuth Apps) and fill the following fields:
241+
- `Application name` - just put some fancy name.
244242
- `Homepage URL` - `http://localhost:8000`
243+
- `User authorization callback URL` - `http://localhost:5556/dex/callback`
245244

246-
- `User authorization callback URL` - `http://0.0.0.0:5556/dex/callback`
247-
248-
- `Permissions` - `Access: Read-only` to `Organization members`
249-
250-
- `User permissions` - none needed
251-
252-
- `Subscribe to events` - tick `Membership`, `Organization` and `Team`
253-
254-
- `Where can this GitHub App be installed?` - `Only on this account`
255-
256-
- Press `Create GitHub App` button
245+
- Press `Create Application` button
257246

258247
- Next thing you'll get is `OAuth credentials` at the bottom of the
259248
page of the app you just created, we will need both `Client ID` and
260249
`Client secret`
261-
262-
- You also need to install the app you just created
263-
- Go to `https://github.com/organizations/<ORG>/settings/apps`
264-
265-
- Click `Edit` button for your new app
266-
267-
- Choose `Install App` on the left of the page and perform the
268-
installation
250+
- The OAuth app should already be installed to your org.
269251

270252
## Creating Github Teams
271253

@@ -282,15 +264,14 @@ Note: The `oidc-roles-path` argument accepts a JSONPath to fetch roles from the
282264
> example.yaml
283265
284266
```yaml
285-
issuer: http://0.0.0.0:5556/dex
267+
issuer: http://localhost:5556/dex
286268

287269
storage:
288-
type: sqlite3
289-
config:
290-
file: /var/dex/dex.db
270+
type: memory
291271

292272
web:
293273
http: 0.0.0.0:5556
274+
allowedOrigins: ["*"]
294275

295276
staticClients:
296277
- id: nebraska
@@ -306,28 +287,30 @@ connectors:
306287
config:
307288
clientID: <Client ID>
308289
clientSecret: <Client Secret>
309-
redirectURI: http://0.0.0.0:5556/dex/callback
290+
redirectURI: http://localhost:5556/dex/callback
310291
loadAllGroups: true
311292
teamNameField: slug
312293
useLoginAsID: true
313-
314-
enablePasswordDB: true
315294
```
316295
317296
- Run Dex using docker with the example configuration.
318297
319-
> docker run -p 5556:5556 -v ${PWD}/example.yaml:/etc/dex/example.yaml -v ${PWD}/dex.db:/var/dex/dex.db ghcr.io/dexidp/dex:v2.28.1 dex serve /etc/dex/example.yaml
298+
```sh
299+
docker run -p 5556:5556 -v ${PWD}/example.yaml:/etc/dex/example.yaml ghcr.io/dexidp/dex:v2.44.0 dex serve /etc/dex/example.yaml
300+
```
320301

321302
## Running nebraska
322303

323-
> nebraska --auth-mode oidc \
324-
> --oidc-admin-roles <organization>:admin \
325-
> --oidc-viewer-roles <organization>:viewer \
326-
> --oidc-client-id nebraska \
327-
> --oidc-issuer-url http://127.0.0.1:5556/dex \
328-
> --oidc-roles-path groups \
329-
> --oidc-scopes groups,openid,profile \
330-
> --http-static-dir $PWD/frontend/dist
304+
```sh
305+
backend/bin/nebraska --debug --auth-mode oidc \
306+
--oidc-roles-path groups \
307+
--oidc-admin-roles admin \
308+
--oidc-viewer-roles viewer \
309+
--oidc-client-id nebraska \
310+
--oidc-issuer-url http://localhost:5556/dex \
311+
--oidc-scopes groups,openid,profile \
312+
--http-static-dir frontend/dist
313+
```
331314

332315
# Preparing Okta as an OIDC provider for Nebraska
333316

@@ -361,12 +344,12 @@ enablePasswordDB: true
361344
## Start Nebraska with Okta
362345

363346
```bash
364-
nebraska --auth-mode oidc \
347+
backend/bin/nebraska --debug --auth-mode oidc \
365348
--oidc-client-id <your-client-id> \
366349
--oidc-issuer-url https://<your-domain>.okta.com/oauth2/default \
367350
--oidc-admin-roles nebraska_admin \
368351
--oidc-viewer-roles nebraska_viewer \
369-
--http-static-dir $PWD/frontend/dist
352+
--http-static-dir frontend/dist
370353
```
371354

372355
# Preparing Azure AD (Microsoft Entra ID) as an OIDC provider for Nebraska
@@ -405,13 +388,13 @@ nebraska --auth-mode oidc \
405388
## Start Nebraska with Azure AD
406389

407390
```bash
408-
nebraska --auth-mode oidc \
391+
backend/bin/nebraska --debug --auth-mode oidc \
409392
--oidc-client-id <your-application-id> \
410393
--oidc-issuer-url https://login.microsoftonline.com/<your-tenant-id>/v2.0 \
411394
--oidc-admin-roles <admin-group-id> \
412395
--oidc-viewer-roles <viewer-group-id> \
413396
--oidc-roles-path groups \
414-
--http-static-dir $PWD/frontend/dist
397+
--http-static-dir frontend/dist
415398
```
416399

417400
Note: Azure AD returns group IDs (GUIDs) rather than group names in the token. You'll need to use the group IDs in your role configuration.
@@ -496,12 +479,12 @@ $ helm install my-nebraska nebraska/nebraska --values nebraska-values.yaml
496479
- Check for trailing slashes or protocol mismatches (http vs https)
497480

498481
- **JWT validation failed / User has no access**
482+
- Inspect your access token
499483
- Check that roles are correctly configured in your OIDC provider
500484
- Verify the roles path matches your token structure (use `--oidc-roles-path` if needed)
501485
- For Auth0, ensure you created an API and set the audience parameter
502486

503487
- **Frequent re-authentication after page refresh**
504-
- This is expected behavior as tokens are stored in-memory for security
505488
- Configure longer access token expiration in your OIDC provider (1-4 hours recommended)
506489
- SSO session will handle re-authentication transparently if still valid
507490

@@ -510,18 +493,6 @@ $ helm install my-nebraska nebraska/nebraska --values nebraska-values.yaml
510493
- Verify audience parameter is set correctly
511494
- Check that you created an API in Auth0 and using its identifier
512495

513-
## General Issues
514-
515-
- **I'm getting a blank page!**
516-
- You likely visited nebraska frontend website before, so browser
517-
likely has cached the `index.html` page, so it won't get it from
518-
Nebraska, but instead start asking for some CSS and javascript
519-
stuff outright, which it won't get. That results in a blank
520-
page. Force the browser to get `index.html` from Nebraska by
521-
either doing a force refresh (ctrl+f5 on firefox), or by cleaning
522-
the cache for localhost (or the server where the Nebraska instance
523-
is deployed).
524-
525496
# Legacy OIDC Configuration
526497

527498
<details>

0 commit comments

Comments
 (0)