Skip to content

docs: add missing info on required okta roles #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sgtoj merged 1 commit into from
Dec 8, 2025
Merged

docs: add missing info on required okta roles #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions docs/okta-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,30 @@ On the **General** tab, find and save:
These scopes allow read-only access to groups and users - no write access to
Okta is required.

## Step 6: Identify Your Okta Domain
## Step 6: Assign Admin Role

API Services applications require an admin role to access Okta APIs. Without
this, API calls will fail with permission errors even if scopes are granted.

1. Go to the **Admin roles** tab for your application
2. Click **Edit assignments**
3. Select one of the following roles:

| Role | Access Level |
|---------------------|-----------------------------------------------|
| **Read Only Admin** | Read access to all resources (recommended) |
| **Group Admin** | Full access to groups only |

4. If using **Group Admin**, optionally restrict to specific groups:
- Under **Edit constraints for Group Administrator**, select specific
groups or group types the app can access
5. Click **Save changes**

> **Note**: Read Only Admin is recommended for sync operations since it
> provides sufficient access without write permissions. Group Admin is an
> alternative if you need to limit the app's scope to group resources only.

## Step 7: Identify Your Okta Domain

Your Okta domain is the URL you use to access the admin console:

Expand All @@ -85,7 +108,7 @@ Your Okta domain is the URL you use to access the admin console:

Use the domain without `https://` prefix for `APP_OKTA_DOMAIN`.

## Step 7: Configure User Profile Field
## Step 8: Configure User Profile Field

The app needs to map Okta users to GitHub usernames. Determine which Okta user
profile field contains GitHub usernames:
Expand All @@ -111,7 +134,7 @@ profile field contains GitHub usernames:

Then set `APP_OKTA_GITHUB_USER_FIELD=githubUsername`.

## Step 8: Prepare Okta Groups
## Step 9: Prepare Okta Groups

Ensure your Okta groups follow a naming convention that can be matched by sync
rules:
Expand All @@ -129,7 +152,7 @@ Groups can be:
- Groups synced from Active Directory
- Groups from other identity providers

## Step 9: Configure Environment Variables
## Step 10: Configure Environment Variables

```bash
# Required Okta configuration
Expand All @@ -149,7 +172,7 @@ APP_OKTA_PRIVATE_KEY_PATH=/path/to/okta-private-key.pem
APP_OKTA_PRIVATE_KEY=arn:aws:ssm:us-east-1:123456789:parameter/github-bot/okta-key
```

## Step 10: Configure Sync Rules
## Step 11: Configure Sync Rules

Define how Okta groups map to GitHub teams:

Expand Down