Skip to main content
In this guide you will configure team synchronization so that Okta group membership controls team membership in a GitHub organization. Follow the steps below in order to connect Okta as an identity provider for GitHub Team synchronization, assign groups, and verify membership propagation.

​
Overview — Steps at a glance

  1. Create a team in your GitHub organization.
  2. Create a corresponding group in Okta and add users.
  3. Create an Okta API token and obtain your Okta org base URL.
  4. Enable Team synchronization in GitHub organization Security → Authentication security and provide the Okta token and URL.
  5. Assign the Okta group to the GitHub team via the team’s Identity provider groups field and save. Initial synchronization will populate the team membership.

​
What you’ll need

Helpful references:

​
1. Create the GitHub team

Create a team in your organization (for example, Console Developers with a short name like dev). Set visibility and notification preferences as needed, then create the team. Initially the team will display its creator or the admin as the only member.

​
2. Create and assign users to an Okta group

In Okta, create a group that will represent the GitHub team (for example, GitHub Engineers). Add the users you want to manage centrally in Okta (for example, dev1 and dev2). GitHub will use this Okta group to populate the corresponding team.
A screenshot of the Okta Admin Console on the Groups > Assign page showing a green "Successfully added sid dev2" confirmation and a list of users with their assignment statuses. The left sidebar shows navigation items like Dashboard, Directory, and Groups.
After assigning users, verify the Okta group lists the members you expect. This group is what you will map to the GitHub team in a later step.

​
3. Open the GitHub team settings (prepare to map groups)

Open the target team’s settings page in GitHub (for example, Console-Dev). If organization-level Team synchronization is not yet enabled, the Identity provider groups field may not be visible here — you will enable it in the next section.
A dark-themed screenshot of a GitHub organization "Team settings" page for a team named "Console-Dev," showing fields for team name, description, parent team, visibility and notifications, and a profile picture upload area. The left sidebar shows menu items like General, Code review, and Scheduled reminders.

​
4. Enable Team synchronization in the GitHub organization

  1. In GitHub, go to your Organization → Settings → Security → Authentication security.
  2. Ensure Single sign-on (SSO) is enabled (and 2FA if required by your policies).
  3. In the Team synchronization section, choose to configure an identity provider and select Okta.
A dark-themed browser screenshot of a GitHub organization's Security settings page showing sections for "Team synchronization," "SSH certificate authorities," and an "IP allow list." Visible buttons include "Enable for Okta," "New CA," and options to enable and save IP allow list settings.

​
5. Obtain the Okta API token and org base URL

In the Okta Admin Console:
  • Go to Security → API → Tokens and create a new token (for example, name it GitHub Team Sync).
  • Copy the displayed token immediately — Okta shows it only once.
  • Note your Okta org base URL (for example, https://dev-123456.okta.com). Use the org base URL — do not use the -admin admin-console URL.
A screenshot of the Okta Admin Console with a modal dialog titled "Create token" prompting the user to enter a name for an API token and select origin, plus "Create token" and "Cancel" buttons. The blurred background shows the API page and left-hand admin navigation.
When you create an Okta API token it is shown only once. Copy and securely store the SSWS token immediately — you cannot view it again from the Okta console.

​
6. Configure Okta in GitHub and assign the group to the team

  1. Back in GitHub Organization → Security → Team synchronization, choose Enable for Okta.
  2. Paste the Okta API token into the SSWS token field and enter your Okta org base URL into the URL field. Save the configuration.
  3. Return to the target team’s settings page. The Identity provider groups field should now be available.
  4. Search for and select the Okta group you created earlier (for example, GitHub Engineers), then save the team settings. The group status may initially show as unsynced while the first synchronization runs.
A dark-themed GitHub "Team settings" page for the Console-Dev team, showing fields for team name, description, parent team, identity provider groups, visibility options, and a profile picture with an "Upload new picture" button. Browser tabs and other UI elements are visible across the top.

​
7. Verify synchronization status

After assigning the Okta group to the GitHub team:
  • The Organization Security page will show how many teams are managed by Okta.
  • Initial synchronization may send invitations to users or update membership progressively. Refresh the team page and the organization security page to confirm status.
  • If only one member appears immediately, allow a few minutes for Okta sync to complete — additional members should populate as the sync finishes.
A dark-mode screenshot of a GitHub organization's Security settings page. It shows "Team synchronization" (Okta configured with a Disable button), plus sections for SSH certificate authorities and IP allow list.
A dark-themed GitHub team page for "Console-Dev" showing the team avatar and an empty About section. The Members panel lists one member and there’s an Edit team button plus a banner about an Enterprise trial at the top.
If group members do not appear after several minutes:
  • Confirm the SSWS token and org base URL are correct.
  • Confirm the Okta group actually contains the users you expect.
  • Check for any pending invitations in GitHub (new users may need to accept org invitations).
  • Review audit logs in Okta and GitHub for any API errors.

​
Summary / Best practices

  • Manage who should belong to GitHub teams from Okta groups — this provides centralized identity management.
  • Create and immediately copy the Okta API token; treat it like a secret.
  • Use the Okta org base URL (not the admin URL) when configuring GitHub.
  • Expect a short propagation time after initial mapping; verify membership after a few minutes.
  • Keep documentation of which Okta group maps to which GitHub team for auditability.
Further reading:

Watch Video