review-1

Author: v-thpra

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

@@ -1,25 +1,26 @@
-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.
+After a user successfully authenticates through your identity provider (IdP) by using SAML single sign-on (SSO), the next critical step is authorization—granting tools like personal access tokens (PATs), SSH keys, or OAuth apps with the ability to access organization resources.
 
 ## Automating User Authorization with SAML SSO and SCIM
 
-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.
+Security assertion markup language (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 access control by automating user provisioning and deprovisioning.
 
 :::image type="content" source="../media/enable-scim-user-provisioning-example.png" alt-text="Screenshot of the SCIM setting." :::
 
 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.
 
 > [!NOTE]
-> Without SCIM, SAML SSO alone does not support automatic deprovisioning of organization members.
+> Without SCIM, SAML SSO alone doesn't support automatic deprovisioning of organization members.
 
-SCIM also revokes stale tokens after a session ends, reducing security risks. Without SCIM, this must be done manually.
+SCIM also revokes stale tokens after a session ends, reducing security risks. Without SCIM, revoking stale tokens must be done manually.
 
 ## Managing SSH Keys and PATs with SAML SSO
 
-SAML SSO and SCIM work together to reflect identity changes in GitHub. To support this:
+SAML SSO and SCIM work together to reflect identity changes in GitHub. To support this cohesion:
+
 - `NameID` and `userName` must match between the SAML IdP and SCIM client.
 - Group changes in your IdP trigger SCIM updates in GitHub.
 
-Users accessing APIs or Git must use an authorized PAT or SSH key. These are auditable and securely tied to SAML SSO.
+Users accessing APIs or Git must use an authorized PAT or SSH key. These methods are auditable and securely tied to SAML SSO.
 
 :::image type="content" source="../media/saml-sso-ssh-key-example.png" alt-text="Screenshot of the SSH key." :::
 
@@ -34,8 +35,9 @@ SCIM streamlines identity management in GitHub Enterprise Cloud by supporting bo
 ### Supported SCIM Providers
 
 GitHub natively supports:
+
 - Okta
-- Azure AD
+- Microsoft Entra ID
 - OneLogin
 - Ping Identity
 - Google Workspace
@@ -49,10 +51,12 @@ If your IdP isn't natively supported, use GitHub’s SCIM API to build custom in
 #### SCIM API Overview
 
 The SCIM 2.0 API allows you to:
+
 - Create, update, and delete users
 - Manage groups
 
-#### Example Request to Provision a User:
+#### Example Request to Provision a User
+
 ```http
 POST /scim/v2/Users
 Content-Type: application/json
@@ -76,17 +80,19 @@ GitHub processes this request and adds the user to your organization.
 
 ### Getting Started
 
-#### For Supported Providers:
-1. Log into your IdP admin console.
-2. Enable SCIM provisioning.
-3. Provide GitHub’s SCIM base URL and bearer token.
+#### For Supported Providers
+
+1. Sign in to your IdP admin console.
+1. Enable SCIM provisioning.
+1. Provide GitHub’s SCIM base URL and bearer token.
 
 :::image type="content" source="../media/scim-configuration-steps.png" alt-text="Screenshot of SCIM configuration steps in IdP's administrative console." :::
 
-#### For Custom IdPs:
+#### For Custom IdPs
+
 1. Use GitHub's SCIM REST API.
-2. Authenticate with a PAT.
-3. Test the integration with sample requests.
+1. Authenticate with a PAT.
+1. Test the integration with sample requests.
 
 ### Key Benefits of SCIM Integration
 
@@ -108,20 +114,24 @@ GitHub processes this request and adds the user to your organization.
 
 You can use a supported identity provider or bring your own SAML 2.0 IdP.
 
-### Supported (Paved Path) IdPs:
+### Supported (Paved Path) IdPs
+
 - Okta
-- Azure Active Directory
+- Microsoft Entra ID
 - Google Workspace
 
 Some advantages of using the supported IdPs are:
+
 - Seamless integration
 - GitHub-supported
 - Lower setup effort
 
-### Bring Your Own IdP:
-Bringing your own IdP requires it isSAML 2.0 support. The advantage of this is that it allows for full flexibility.
+### Bring Your Own IdP
+
+Bring your own IdP requires SAML 2.0 support. It has the advantage of allowing for full flexibility.
 
 ### Integration Steps
+
 | Type               | Steps                 |
 |--------------------|-----------------------|
 | **Paved Path:**    | 1. Navigate to enterprise security settings. <br>2. Select your IdP. <br>3. Follow setup instructions. |
@@ -141,15 +151,17 @@ Bringing your own IdP requires it isSAML 2.0 support. The advantage of this is t
 ## Managing Identities and Access
 
 ### SAML SSO Configuration
+
 1. Configure your SAML SSO URL.
-2. Provide your public certificate.
-3. Add IdP metadata.
+1. Provide your public certificate.
+1. Add IdP metadata.
 
 ### Credential Management
 
 PATs and SSH keys must be explicitly authorized and linked to IdP identities to access organization resources securely.
 
 ### Auditing SAML Sessions
+
 - View active sessions in settings.
 - Revoke individual sessions as needed.
 
@@ -158,6 +170,5 @@ PATs and SSH keys must be explicitly authorized and linked to IdP identities to
 | Type                 | Consideration            |
 |-------------------------|----------------------------|
 | GitHub Instance Membership | - Access to public repositories <br>- Create personal projects <br> - Public profile visibility |
-| Organization Membership | - Role-based internal access <br> - Profile visible to org admins <br> - May affect billing |
+| Organization Membership | - Role-based internal access <br> - Profile visible to org admins <br> - Might affect billing |
 | Multiple Organization Memberships| - Different roles across orgs <br>- Broader resource access <br>- Complex permission and billing <br> - Requires strict governance |
-