Skip to content

Commit 038e415

Browse files
themr0cJessicaJHeepabel-rh
committed
RHIDP-9017 Updated authenticating with GitHub (#1429)
Co-authored-by: Jessica He <[email protected]> Co-authored-by: Priyanka Abel <[email protected]>
1 parent 1f79987 commit 038e415

6 files changed

+126
-63
lines changed

‎assemblies/assembly-enabling-authentication-with-github.adoc‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
:optional-steps: enable
3+
4+
[id='enabling-authentication-with-github']
5+
= Enabling authentication with GitHub
6+
7+
include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
8+
9+
10+
include::modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc[leveloffset=+1]
11+

‎assemblies/assembly-enabling-authentication.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ include::assembly-authenticating-with-the-guest-user.adoc[leveloffset=+1]
1313
include::assembly-authenticating-with-rhbk.adoc[leveloffset=+1]
1414

1515

16-
include::modules/authentication/proc-enabling-user-authentication-with-github.adoc[leveloffset=+1]
16+
include::assembly-enabling-authentication-with-github.adoc[leveloffset=+1]
1717

1818

1919
include::modules/authentication/proc-enabling-user-authentication-with-microsoft-azure.adoc[leveloffset=+1]

‎modules/authentication/proc-enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider"]
4+
= Enabling user authentication with GitHub as an auxiliary authentication provider
5+
6+
To allow users to access GitHub templates or plugins that require GitHub authentication, configure GitHub as an auxiliary authentication provider. This method relies on a primary authentication provider for user identity management, and skips resolving user identity from this provider.
7+
8+
.Prerequisites
9+
* You have {configuring-book-link}[added a custom {product-short} application configuration] with another authentication provider enabled, and have enough permissions to change it.
10+
11+
include::snip-enabling-user-authentication-with-github-common-steps.adoc[]
12+
13+
. To set up the GitHub authentication provider as an auxiliary authentication provider, add the `auth.providers.github` section to your `{my-app-config-file}` file:
14+
+
15+
[source,yaml]
16+
----
17+
auth:
18+
providers:
19+
github:
20+
production:
21+
clientId: ${GITHUB_CLIENT_ID}
22+
clientSecret: ${GITHUB_CLIENT_SECRET}
23+
disableIdentityResolution: true
24+
----
25+
+
26+
where:
27+
`clientId`::
28+
Enter the configured secret variable name: `$\{GITHUB_CLIENT_ID}`.
29+
30+
`clientSecret`::
31+
Enter the configured secret variable name: `$\{GITHUB_CLIENT_SECRET}`.
32+
33+
`disableIdentityResolution`::
34+
Enter `true`to skip user identity resolution for this provider to enable sign-in from an auxiliary authentication provider.
35+
Do not enable this setting on the primary authentication provider you plan on using for sign-in and identity management.
36+
37+
.Verification
38+
39+
. Go to the {product-short} login page.
40+
. Log in with your primary authentication provider account.
41+
. In the top user menu, go to *Settings* > *Authentication Providers*.
42+
. In the *GitHub* line, click the *Sign in* button and log in.
43+
. In the *GitHub* line, the button displays *Sign out*.
44+
45+
.Additional resources
46+
* {integrating-with-github-book-link}[{integrating-with-github-book-title}]
47+

‎modules/authentication/proc-enabling-user-authentication-with-github.adoc‎

Lines changed: 1 addition & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -8,68 +8,7 @@ Authenticate users with GitHub by provisioning the users and groups from GitHub
88
.Prerequisites
99
* You {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.
1010

11-
* You have enough permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
12-
Alternatively, you can ask your GitHub administrator to prepare the required GitHub App.
13-
14-
.Procedure
15-
. To allow {product-short} to authenticate with GitHub, create a GitHub App.
16-
Opt for a GitHub App instead of an OAuth app to use fine-grained permissions and use short-lived tokens.
17-
18-
.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
19-
20-
GitHub App name::
21-
Enter a unique name identifying your GitHub App, such as `authenticating-with-rhdh-__<GUID>__`.
22-
23-
Homepage URL::
24-
Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
25-
26-
Authorization callback URL::
27-
Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`.
28-
29-
Webhook::
30-
Clear "Active", as this is not needed for authentication and catalog providers.
31-
32-
Organization permissions::
33-
Enable `Read-only` access to *Members*.
34-
35-
Where can this GitHub App be installed?::
36-
Select `Only on this account`.
37-
38-
.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*.
39-
40-
.. In the *Install App* tab, choose an account to install your GitHub App on.
41-
42-
.. Save the following values for the next step:
43-
44-
* **Client ID**
45-
* **Client secret**
46-
47-
. To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets].
48-
You can use these secrets in the {product-short} configuration files by using their environment variable name.
49-
50-
`GITHUB_CLIENT_ID`::
51-
Enter the saved **Client ID**.
52-
53-
`GITHUB_CLIENT_SECRET`::
54-
Enter the saved **Client Secret**.
55-
56-
`GITHUB_URL`::
57-
Enter the GitHub host domain: `github.com`.
58-
59-
`GITHUB_ORG`::
60-
Enter your GitHub organization name, such as `__<your_github_organization_name>__`.
61-
62-
. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
63-
This plugin imports GitHub users and groups to the {product-short} software catalog.
64-
+
65-
`dynamic-plugins.yaml` file fragment:
66-
+
67-
[source,yaml]
68-
----
69-
plugins:
70-
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
71-
disabled: false
72-
----
11+
include::snip-enabling-user-authentication-with-github-common-steps.adoc[]
7312

7413
. Provision GitHub users and groups to the {product-short} software catalog by adding the `catalog.providers.githubOrg` section to your custom {product-short} `{my-app-config-file}` configuration file:
7514
+

‎modules/authentication/snip-enabling-user-authentication-with-github-common-steps.adoc‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
:_mod-docs-content-type: SNIPPET
2+
3+
* You have enough permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
4+
Alternatively, you can ask your GitHub administrator to prepare the required GitHub App.
5+
6+
.Procedure
7+
. To allow {product-short} to authenticate with GitHub, create a GitHub App.
8+
Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, use short-lived tokens, scale with the number of installations by avoiding rate limits, and have a more transparent integration by avoiding to request user input.
9+
10+
.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
11+
12+
GitHub App name::
13+
Enter a unique name identifying your GitHub App, such as `authenticating-with-rhdh-__<GUID>__`.
14+
15+
Homepage URL::
16+
Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
17+
18+
Authorization callback URL::
19+
Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`.
20+
21+
Webhook::
22+
Clear "Active", as this is not needed for authentication and catalog providers.
23+
24+
Organization permissions::
25+
Enable `Read-only` access to *Members*.
26+
27+
Where can this GitHub App be installed?::
28+
Select `Only on this account`.
29+
30+
.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*.
31+
32+
.. In the *Install App* tab, choose an account to install your GitHub App on.
33+
34+
.. Save the following values for the next step:
35+
36+
* **Client ID**
37+
* **Client secret**
38+
39+
. To add your GitHub credentials to {product-short}, add the following key/value pairs to {configuring-book-link}#provisioning-your-custom-configuration[your {product-short} secrets].
40+
You can use these secrets in the {product-short} configuration files by using their environment variable name.
41+
42+
`GITHUB_CLIENT_ID`::
43+
Enter the saved **Client ID**.
44+
45+
`GITHUB_CLIENT_SECRET`::
46+
Enter the saved **Client Secret**.
47+
48+
`GITHUB_URL`::
49+
Enter the GitHub host domain: `github.com`.
50+
51+
`GITHUB_ORG`::
52+
Enter your GitHub organization name, such as `__<your_github_organization_name>__`.
53+
54+
. Enable the GitHub organization provisioning plugin (`backstage-plugin-catalog-backend-module-github-org`).
55+
This plugin imports GitHub users and groups to the {product-short} software catalog.
56+
+
57+
`dynamic-plugins.yaml` file fragment:
58+
+
59+
[source,yaml]
60+
----
61+
plugins:
62+
- package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org'
63+
disabled: false
64+
----

‎modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ If a repository contains a `catalog-info.yaml` file, {product-short} ingests the
1111

1212
* You have sufficient permissions in GitHub to create and manage a link:https://docs.github.com/en/apps/overview[GitHub App].
1313

14+
* To allow users to access GitHub templates or plugins that require GitHub authentication, you have configured GitHub either {authentication-book-link}#enabling-user-authentication-with-github-as-an-auxiliary-authentication-provider[as an auxiliary authentication provider] or {authentication-book-link}#enabling-user-authentication-with-github[as your main authentication provider].
15+
1416
.Procedure
1517
. To allow {product-short} to access the GitHub API, create a GitHub App.
1618
Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens.

0 commit comments

Comments
 (0)