website/integrations add GHEC EMU and fix-up GHES (#11677)

* website/integrations add GHEC EMU and fix-up GHES

* fix duplicate mapping

Signed-off-by: Jens Langhammer <jens@goauthentik.io>

* Optimised images with calibre/image-actions

---------

Signed-off-by: Jens Langhammer <jens@goauthentik.io>
Co-authored-by: TheGuyDanish <5776313+TheGuyDanish@users.noreply.github.com>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>

website/integrations/services/github-enterprise-emu/index.md

@@ -0,0 +1,106 @@
+---
+title: Integrate with GitHub Enterprise Cloud - Enterprise Managed Users
+sidebar_label: GitHub Enterprise Cloud EMU
+---
+
+# GitHub Enterprise Cloud - Enterprise Managed Users
+
+<span class="badge badge--secondary">Support level: Community</span>
+
+## What is GitHub Enterprise Cloud - Enterprise Managed Users
+
+> With Enterprise Managed Users, you manage the lifecycle and authentication of your users on GitHub from an external identity management system, or IdP:
+>
+> -   Your IdP provisions new user accounts on GitHub, with access to your enterprise.
+> -   Users must authenticate on your IdP to access your enterprise's resources on GitHub.
+> -   You control usernames, profile data, organization membership, and repository access from your IdP.
+> -   If your enterprise uses OIDC SSO, GitHub will validate access to your enterprise and its resources using your IdP's Conditional Access Policy (CAP). See "About support for your IdP's Conditional Access Policy."
+> -   Managed user accounts cannot create public content or collaborate outside your enterprise. See "Abilities and restrictions of managed user accounts."
+>
+> -- https://docs.github.com/en/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users
+
+## Preparation
+
+The following placeholders will be used:
+
+-   `github.com/enterprises/foo` is your GitHub organization, where `foo` is the name of your enterprise
+-   `authentik.company` is the FQDN of the authentik Install
+-   `GitHub Users` is an authentik group used for holding GitHub users.
+-   `GitHub Admins` is an authentik group used for indicating GitHub administrators.
+
+Note that in order to use the EMU Enterprise, you _must_ set up both SAML and SCIM.
+
+First, create the two groups, in authentik, go to _Groups_, click _Create_ and put in `GitHub Users`, or your chosen user group name. Repeat this step with your Admin group as well.
+
+## SAML Provider
+
+Create a SAML provider with the following parameters:
+
+-   ACS URL: `https://github.com/enterprises/foo/saml/consume`
+-   Audience: `https://github.com/enterprises/foo`
+-   Issuer: `https://github.com/enterprises/foo`
+-   Binding: `Post`
+
+Under _Advanced protocol settings_, set a certificate for _Signing Certificate_. Also set your _NameID Property Mapping_ to the _Email_ field. GitHub will create a username for your EMU users based on the SAML NameID, this NameID must also match the SCIM _userName_ attribute. This is covered later.
+
+Once the provider is created, it is advised to download the signing certificate as you will need it later.
+
+## GitHub SAML Configuration
+
+When your EMU is provisioned by GitHub, you will receive an email inviting you reset the password of your 'setup user'. This user cannot be linked with SSO and is an emergency access account, as it will be the only account that can bypass SSO requirements.
+
+Before enabling SAML, go to your [Personal access tokens](https://github.com/settings/tokens) on your EMU setup user and Generate a new _personal access token (classic)_. This should have a descriptive note like `SCIM Token`. It is advisable to set this to not expire. For scopes, select only _admin:enterprise_ and click _Generate token_.
+
+Copy the resulting token to a safe location.
+
+After you have set a password for this account and generated your SCIM token, navigate to your enterprise settings by clicking your GitHub user portrait in the top right of GitHub.com, select `Your enterprise`, click the `Settings` link, then click `Authentication security`.
+
+On this page:
+
+-   Select the `Require SAML authentication` checkbox.
+-   In `Sign on URL`, input the _SSO URL (Redirect)_ entry from the SAML provider you created.
+-   For `Issuer`, input the `Issuer` you set in authentik
+-   For `Public certificate`, paste the _full_ signing certificate into this field.
+-   Verify that the `Signature method` and `Digest method` match your SAML provider settings in authentik.
+
+![Screenshot showing populated GitHub enterprise SAML settings](ghec_emu_settings.png)
+
+Once these fields are populated, you can use the `Test SAML configuration` button to test the authentication flow. If the flow completes successfully, you will see a green tick next to the Test button.
+
+Scroll down to hit the `Save SAML settings` button below.
+
+You will now be prompted to save your SAML recovery codes, these will be necessary if you need to disable or change your SAML settings, so keep them safe!
+
+## SCIM Provider
+
+Before we create a SCIM provider, we also have to create a new Property Mapping. In authentik, go to _Customization_, then _Property Mappings_. Here, click _Create_, select _SCIM Provider Mapping_. Name the mapping something memorable and paste the following code in the _Expression_ field:
+
+```python
+roles = []
+# Edit this if statement if you need to add more GitHub roles.
+# Valid roles include:
+# user, guest_collaborator, enterprise_owner, billing_manager
+if ak_is_group_member(request.user, name='GitHub Admins'):
+    roles.append({'value': 'enterprise_owner', 'primary': True})
+else:
+    roles.append({'value': 'user', 'primary': True})
+return {
+    "roles": roles,
+}
+```
+
+If you named your group anything other than `GitHub Admins`, please ensure you change it in the code above.
+
+Create a new SCIM provider with the following parameters:
+
+-   URL: `https://api.github.com/scim/v2/enterprises/foo/` (Replacing `foo` with your Enterprise slug.)
+-   Token: Paste the token provided from GitHub here.
+-   In the _User filtering_ section, you can select your `GitHub Users` group.
+-   In the _Attribute mapping_ section, de-select the `authentik default SCIM Mapping: User` mapping by selecting it on the right-hand side and clicking the left-facing single chevron.
+-   Select the property mapping you created in the previous step and add it by clicking the right-facing single chevron.
+-   You can leave the _Group Property Mappings_ as is.
+-   Click _Finish_.
+
+Go back to your GitHub EMU Application created in the first step and add your new SCIM provider in the _Backchannel Providers_ field, then click the _Update_ button.
+
+You should now be ready to assign users to your _GitHub Users_ and _GitHub Admins_ groups, which will be provisioend by the SCIM provisioner. If you do not see your users being provisioned, go to your SCIM provider and click the _Run sync again_ option. A few seconds later, you should see results of the SCIM sync.

website/integrations/services/github-enterprise-server/index.md

@@ -19,8 +19,12 @@ The following placeholders will be used:
 
 -   `https://github.company` is your GitHub Enterprise Server installation
 -   `authentik.company` is the FQDN of the authentik Install
+-   `GitHub Users` is an authentik group used for holding GitHub users.
+-   `GitHub Admins` is an authentik group used for indicating GitHub administrators.
 
-Create an application in authentik and note the slug, as this will be used later. Create a SAML provider with the following parameters:
+First, create the two groups, in authentik, go to _Groups_, click _Create_ and put in `GitHub Users`, or your chosen user group name. Repeat this step with your Admin group as well.
+
+Create a SAML provider with the following parameters:
 
 -   ACS URL: `https://github.company/saml/consume`
 -   Audience: `https://github.company`
@@ -31,19 +35,64 @@ Under _Advanced protocol settings_, set a certificate for _Signing Certificate_.
 
 Once the provider is created, it is advised to download the signing certificate as you will need it later.
 
-## GitHub Configuration
+Create a matching application for your SAML provider.
+
+## SAML Configuration
 
-Navigate to your appliance maintenance settings. These are found at `https://github.company:8443`. Here, sign in with an administrator user and go to the Authentication section.
+If you are planning to use SCIM, (available from GHES 3.14.0) you should create a first admin user on your instance and go to your personal access tokens at `https://github.company/settings/tokens/new`, click _Generate new token_ and click _Generate new token (classic)_. Your token should have a descriptive name and ideally, no expiration date. For permission scopes, you need to select _admin:enterprise_. Click _Generate token_ and store the resulting token in a safe location.
+
+To enable SAML, navigate to your appliance maintenance settings. These are found at `https://github.company:8443`. Here, sign in with an administrator user and go to the Authentication section.
 
 On this page:
 
--   Select the `SAML` option.
--   In `Sign on URL`, type `https://authentik.company/application/saml/<authentik application slug>/sso/binding/redirect/` (This is your `SSO URL (Redirect)` in Authentik)
--   For `Issuer`, type `https://github.company` or the `Audience` you set in authentik
--   Verify that the `Signature method` and `Digest method` match your SAML provider settings in authentik.
--   For `Validation certificate`, upload the signing certificate you downloaded after creating the provider.
+-   Select the _SAML_ option.
+-   In _Sign on URL_, input your _SSO URL (Redirect)_ from authentik.
+-   For _Issuer_, use the _Audience_ you set in authentik.
+-   Verify that the _Signature method_ and _Digest method_ match your SAML provider settings in authentik.
+-   For _Validation certificate_, upload the signing certificate you downloaded after creating the provider.
+-   If you plan to enable SCIM, select _Allow creation of accounts with built-in authentication_ and _Disable administrator demotion/promotion_ options. These are selected so you can use your admin user as an emergency non-SSO account, as well as create machine users, and to ensure users are not promoted outside your IdP.
+-   In the _User attributes_ section, enter `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` in the _Username_ field to ensure the emails become normalized into usernames in GitHub.
 -   Press Save settings on the left-hand side and wait for the changes to apply.
 
 ![Screenshot showing populated GitHub Enterprise Server SAML settings](ghes_saml_settings.png)
 
 Once the appliance has saved the settings and reloaded the services, you should be able to navigate to your instance URL at `https://github.company` and sign in with SAML.
+
+## SCIM Configuration
+
+This section only applies if you have taken the steps prior to prepare the instance for SCIM enablement.
+
+After enabling SAML, log into your initial admin account again. Click the user portrait in tee top right, click _Enterprise settings_, click _Settigs_ in the left-hand sidebar, click _Authentication security_. On this page you have to check _Enable SCIM configuration_ and press _Save_. After which you should get a message reading _SCIM Enabled_.
+
+Before we create a SCIM provider, we have to create a new Property Mapping. In authentik, go to _Customization_, then _Property Mappings_. Here, click _Create_, select _SCIM Provider Mapping_. Name the mapping something memorable and paste the following code in the _Expression_ field:
+
+```python
+roles = []
+# Edit this if statement if you need to add more GitHub roles.
+# Valid roles include:
+# user, guest_collaborator, enterprise_owner, billing_manager
+if ak_is_group_member(request.user, name='GitHub Admins'):
+    roles.append({'value': 'enterprise_owner', 'primary': True})
+else:
+    roles.append({'value': 'user', 'primary': True})
+
+return {
+    "roles": roles,
+}
+```
+
+If you named your group anything other than `GitHub Admins`, please ensure you change it in the code above.
+
+Create a new SCIM provider with the following parameters:
+
+-   URL: `https://github.company/api/v3/scim/v2`
+-   Token: Paste the token you generated earlier here.
+-   In the _User filtering_ section, you can select your `GitHub Users` group.
+-   In the _Attribute mapping_ section, de-select the `authentik default SCIM Mapping: User` mapping from the _User Property Mappings_ by selecting it on the right-hand side and clicking the left-facing single chevron.
+-   Select the property mapping you created in the previous step and add it by clicking the right-facing single chevron.
+-   Ensure that `authentik default SCIM Mapping: Group` is the only one active in the _Group Property Mappings_.
+-   Click _Finish_.
+
+Go back to your GitHub Enterprise Server Application created in the first step and add your new SCIM provider in the _Backchannel Providers_ field, then click the _Update_ button.
+
+You should now be ready to assign users to your _GitHub Users_ and _GitHub Admins_ groups, which will be provisioend by the SCIM provisioner. If you do not see your users being provisioned, go to your SCIM provider and click the _Run sync again_ option. A few seconds later, you should see results of the SCIM sync.

website/sidebarsIntegrations.js

@@ -157,9 +157,10 @@ module.exports = {
                     label: "Version Control Systems",
                     items: [
                         "services/gitea/index",
+                        "services/github-organization/index",
                         "services/github-enterprise-cloud/index",
+                        "services/github-enterprise-emu/index",
                         "services/github-enterprise-server/index",
-                        "services/github-organization/index",
                         "services/gitlab/index",
                     ],
                 },