From aba260dd10a344787e939e810b79f9761b911a1f Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Fri, 20 Aug 2021 16:50:18 +0200 Subject: [PATCH] docs/auth/github: updated documentation to reflect app support Signed-off-by: Patrik Oldsberg --- docs/auth/github/provider.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md index 4b65c8c3c2..81b2e98f2c 100644 --- a/docs/auth/github/provider.md +++ b/docs/auth/github/provider.md @@ -10,11 +10,16 @@ that can authenticate users using GitHub or GitHub Enterprise OAuth. ## Create an OAuth App on GitHub -To add GitHub authentication, you must create an OAuth App from the GitHub +To add GitHub authentication, you must create either a GitHub App, or an OAuth +App from the GitHub [developer settings](https://github.com/settings/developers). The `Homepage URL` should point to Backstage's frontend, while the `Authorization callback URL` will point to the auth backend. +Note that if you're using a GitHub App, the allowed scopes are configured as +part of that app. This means you need to verify what scopes the plugins you use +require, so be sure to check the plugin READMEs for that information. + Settings for local development: - Application name: Backstage (or your custom app name) @@ -51,3 +56,11 @@ The GitHub provider is a structure with three configuration keys: To add the provider to the frontend, add the `githubAuthApi` reference and `SignInPage` component as shown in [Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). + +## Difference between GitHub Apps and GitHub OAuth Apps + +GitHub Apps handle OAuth scope at the app installation level, meaning that the +`scope` parameter for the call to `getAccessToken` in the frontend has no +effect. When calling `getAccessToken` in open source plugins, one should still +include the appropriate scope, but also document in the plugin README what +scopes are required for GitHub Apps.