Skip to content

Commit 59dd9bd

Browse files
wolz-CODElifewolz-CODElife
authored
Update 4-authorization.md
1 parent 554c56a commit 59dd9bd

File tree

1 file changed

+140
-25
lines changed

1 file changed

+140
-25
lines changed

‎learn-pr/github/authenticate-authorize-user-identities-github/includes/4-authorization.md

Lines changed: 140 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,164 @@
1-
Here, we introduce the authorization for GitHub users, which is the next step after user authentication.
1+
After a user successfully authenticates through your identity provider (IdP) using SAML single sign-on (SSO), the next critical step is authorization—granting tools like personal access tokens (PATs), SSH keys, or OAuth apps the ability to access organization resources.
22

3-
As we learned previously, you can grant a user access to a GitHub organization that uses SAML single sign-on (SSO) by authenticating through the identity provider (IdP). But after you authenticate the user with the IdP successfully from GitHub, you must now authorize any personal access token, SSH key, or OAuth App that you'd like the user to use to access your organization's resources. Let's look a little deeper into this authentication process with SAML single sign-on.
3+
## Automating User Authorization with SAML SSO and SCIM
44

5-
## Authorization with SAML SSO through SCIM
6-
7-
SAML single sign-on (SSO) gives organization owners and enterprise owners on GitHub a way to control and secure access to organization resources like repositories, issues, and pull requests. If you use SAML SSO in your organization, you can implement SCIM or *System for Cross-domain Identity Management*. SCIM lets you add, manage, or remove organization member access within GitHub. SCIM was developed to allow synchronization of information between an IdP and multiple applications.
5+
SAML SSO enables enterprise and organization owners to control access to GitHub resources like repositories, issues, and pull requests. Integrating SCIM (System for Cross-domain Identity Management) enhances this by automating user provisioning and deprovisioning.
86

97
:::image type="content" source="../media/enable-scim-user-provisioning-example.png" alt-text="Screenshot of the SCIM setting." :::
108

11-
SCIM is a protocol that tells the directory an account has been created and allows you to automate the exchange of user identity information between systems. For example, while onboarding a new employee, using a central directory allows you to automatically provision the user to access services like GitHub. An administrator can deprovision an organization member using SCIM and automatically remove the member from the organization.
9+
With SCIM, new employees added to your IdP are granted access to GitHub automatically, while departing users are removed, reducing manual steps and improving security.
1210

1311
> [!NOTE]
14-
> If you use SAML SSO without implementing SCIM, you won't have automatic deprovisioning.
12+
> Without SCIM, SAML SSO alone does not support automatic deprovisioning of organization members.
1513
16-
SCIM integrations allow the secure exchange of user identity data between your IdP and your enterprise on GitHub. SCIM was developed to allow the synchronization of information between an IdP and multiple applications. When organization members' sessions expire after their access is removed from the IdP, they aren't automatically removed from the organization. Authorized tokens grant access to the organization even after their sessions expire. To remove this access, you can either manually remove the authorized token from the organization or automate its removal with SCIM.
14+
SCIM also revokes stale tokens after a session ends, reducing security risks. Without SCIM, this must be done manually.
1715

18-
### SSH key and PAT with SAML SSO
16+
## Managing SSH Keys and PATs with SAML SSO
1917

20-
Once these systems are implemented, user lifecycle-management changes you make in your IdP are reflected in your GitHub enterprise automatically. The SAML IdP and the SCIM client must use matching NameID and userName values for each user. This process allows a user authenticating through SAML to be linked to their provisioned SCIM identity. Each time you make changes to group membership in your IdP, the IdP will make a SCIM call to GitHub.com to update the corresponding organization's membership. Each time an enterprise member accesses a resource protected by your enterprise account's SAML configuration, that SAML assertion will trigger provisioning.
18+
SAML SSO and SCIM work together to reflect identity changes in GitHub. To support this:
19+
- `NameID` and `userName` must match between the SAML IdP and SCIM client.
20+
- Group changes in your IdP trigger SCIM updates in GitHub.
2121

22-
To access your organization's protected resources using the API and Git on the command line, your users will need to authorize and authenticate with a PAT (personal access token) or SSH key. Users can authorize an existing PAT or SSH key, or create a new PAT or SSH key and then authorize it. As the administrator, you're able to review each personal access token and SSH key that a member has authorized for API and Git access.
22+
Users accessing APIs or Git must use an authorized PAT or SSH key. These are auditable and securely tied to SAML SSO.
2323

2424
:::image type="content" source="../media/saml-sso-ssh-key-example.png" alt-text="Screenshot of the SSH key." :::
2525

26-
After you enable SAML SSO, there are multiple ways you can add new members to your organization. Organization owners can invite new members manually on GitHub or by using the API. To provision new users without an invitation from an organization owner, you can use the URL `https://github.com/orgs/ORGANIZATION/sso/sign_up`, replacing *ORGANIZATION* with the name of your organization. For example, you can configure your IdP so that anyone with access to the IdP can click a link on the IdP's dashboard to join your GitHub organization.
26+
To simplify onboarding, provision users using: `https://github.com/orgs/ORGANIZATION/sso/sign_up`. Display this link in your IdP dashboard.
27+
28+
When users first authenticate, GitHub links their account and SCIM data to your organization. Admins can later audit or revoke sessions and credentials to automate offboarding.
2729

28-
SCIM and SAML SSO also have security benefits. The first time a member uses SAML SSO to access your organization, GitHub automatically creates a record that links your organization, the member's GitHub account, and the member's account on your IdP. You can review the SAML SSO identity that a member has linked to their GitHub account. When available, the entry will include SCIM data for the user. You can also view and revoke the linked SAML identity, active sessions, and authorized credentials for members of your organization or enterprise account. When an employee leaves the company, the off-boarding process is automated, and deprovisioning happens automatically. When you unassign the application from a user or deactivate a user's account on your IdP, it will communicate with GitHub.com to invalidate any SAML sessions for that user. Automating these tasks reduces the time required for an administrator to manage user credentials and the risk of error associated with manually entering and updating user information is also mitigated.
30+
## SCIM Integration with GitHub
2931

30-
### Connect your IdP to your organization
32+
SCIM streamlines identity management in GitHub Enterprise Cloud by supporting both native integrations and custom configurations.
3133

32-
To use SAML single sign-on and SCIM, you must connect your identity provider to your GitHub organization. When you enable SAML SSO for your GitHub organization, you connect your identity provider to your organization. Keep in mind that not all SAML identity providers are currently supported by GitHub for SCIM. Following is a list of the GitHub supported identity providers for SCIM:
34+
### Supported SCIM Providers
3335

34-
- Microsoft Entra ID
36+
GitHub natively supports:
3537
- Okta
38+
- Azure AD
3639
- OneLogin
40+
- Ping Identity
41+
- Google Workspace
42+
43+
These integrations ensure reliable configuration and compatibility.
44+
45+
### Custom SCIM Integrations
46+
47+
If your IdP isn't natively supported, use GitHub’s SCIM API to build custom integrations.
48+
49+
#### SCIM API Overview
50+
51+
The SCIM 2.0 API allows you to:
52+
- Create, update, and delete users
53+
- Manage groups
54+
55+
#### Example Request to Provision a User:
56+
```http
57+
POST /scim/v2/Users
58+
Content-Type: application/json
59+
60+
{
61+
"userName": "jdoe",
62+
"name": {
63+
"givenName": "John",
64+
"familyName": "Doe"
65+
},
66+
"emails": [
67+
{
68+
"value": "[email protected]",
69+
"primary": true
70+
}
71+
]
72+
}
73+
```
74+
75+
GitHub processes this request and adds the user to your organization.
76+
77+
### Getting Started
78+
79+
#### For Supported Providers:
80+
1. Log into your IdP admin console.
81+
2. Enable SCIM provisioning.
82+
3. Provide GitHub’s SCIM base URL and bearer token.
83+
84+
:::image type="content" source="../media/image-6.png" alt-text="Screenshot of SCIM configuration steps in IdP's administrative console." :::
85+
86+
#### For Custom IdPs:
87+
1. Use GitHub's SCIM REST API.
88+
2. Authenticate with a PAT.
89+
3. Test the integration with sample requests.
90+
91+
### Key Benefits of SCIM Integration
92+
93+
- **Provisioning:** Automatically create accounts.
94+
- **Updates:** Synchronize roles and departments.
95+
- **Deprovisioning:** Remove access promptly upon user exit.
96+
97+
## SCIM vs. Manual User Management
98+
99+
| Aspect | SCIM-Based Management | Manual Management |
100+
|--------------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
101+
| **Automation** | Automates provisioning and deprovisioning | Manual intervention required |
102+
| **Consistency** | Standardized user data across systems | Risk of inconsistencies |
103+
| **Security** | Timely deactivation of access | Delayed or missed revocations |
104+
| **Scalability** | Scales with large user bases | Cumbersome at scale |
105+
| **Compliance** | Helps meet policy and audit requirements | Harder to track and report |
106+
107+
## Connecting Your IdP to GitHub
108+
109+
You can use a supported identity provider or bring your own SAML 2.0 IdP.
110+
111+
### Supported (Paved Path) IdPs:
112+
- Okta
113+
- Azure Active Directory
114+
- Google Workspace
115+
116+
Some advantages of using the supported IdPs are:
117+
- Seamless integration
118+
- GitHub-supported
119+
- Lower setup effort
120+
121+
### Bring Your Own IdP:
122+
Bringing your own IdP requires it isSAML 2.0 support. The advantage of this is that if allows for full flexibility.
123+
124+
### Integration Steps
125+
| Type | Steps |
126+
|--------------------|-----------------------|
127+
| **Paved Path:** | 1. Navigate to enterprise security settings. <br>2. Select your IdP. <br>3. Follow setup instructions. |
128+
| **Custom IdP:** | 1. Go to security settings. <br>2. Choose custom IdP. <br>3. Enter SAML metadata. 4. Validate the connection. |
129+
130+
:::image type="content" source="../media/image-7.png" alt-text="Diagram showing the steps to integrate a pre-configured identity provider." :::
131+
132+
## Comparing IdP Integration Paths
133+
134+
| Feature | Paved Path | Bring Your Own IdP |
135+
|----------------------|------------------------------------|----------------------------------|
136+
| Setup Process | ✅ Guided setup | ⚠️ Manual configuration |
137+
| Flexibility | ⚠️ Limited to listed IdPs | ✅ Any SAML 2.0 IdP |
138+
| Maintenance | ✅ GitHub-managed | ⚠️ Organization-managed |
139+
| Customization | ⚠️ Minimal | ✅ Fully customizable |
140+
| Support & Updates | ✅ GitHub-supported | ⚠️ Self-managed |
141+
142+
## Managing Identities and Access
143+
144+
### SAML SSO Configuration
145+
1. Configure your SAML SSO URL.
146+
2. Provide your public certificate.
147+
3. Add IdP metadata.
148+
149+
### Credential Management
150+
151+
PATs and SSH keys must be explicitly authorized and linked to IdP identities to access organization resources securely.
37152

38-
If your support request is outside of the scope of what our team can help you with, we might recommend next steps to resolve your issue outside of GitHub Support. Your support request is possibly out of GitHub Support's scope if the request is primarily about:
153+
### Auditing SAML Sessions
154+
- View active sessions in settings.
155+
- Revoke individual sessions as needed.
39156

40-
- Third-party integrations
41-
- Hardware setup
42-
- CI/CD, such as Jenkins
43-
- Writing scripts
44-
- Configuration of external authentication systems, such as SAML identity providers
45-
- Open-source projects
157+
## GitHub Membership Considerations
46158

47-
Some companies may have built their own system and synchronize their accounts in a custom way. GitHub doesn't support these custom-created accounts with technical assistance. Technical support by GitHub for changes in the way GitHub.com uses SCIM and SAML is available for enterprises that are using one of the providers listed previously.
159+
| Type | Consideration |
160+
|-------------------------|----------------------------|
161+
| GitHub Instance Membership | - Access to public repositories <br>- Create personal projects <br> - Public profile visibility |
162+
| Organization Membership | - Role-based internal access <br> - Profile visible to org admins <br> - May affect billing |
163+
| Multiple Organization Memberships| - Different roles across orgs <br>- Broader resource access <br>- Complex permission and billing <br> - Requires strict governance |
48164

49-
If you're uncertain if the issue is out of scope, open a ticket with GitHub support, and they'll be happy to help you determine the best way to continue.

0 commit comments

Comments
 (0)