From 5caff90bff1e90e7d9a53bdbeb5a307c666ab441 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 2 May 2022 11:55:20 +0200 Subject: [PATCH 1/4] docs: initial auth troubleshooting docs Signed-off-by: Patrik Oldsberg --- docs/auth/troubleshooting.md | 21 +++++++++++++++++++++ microsite/sidebars.json | 1 + mkdocs.yml | 1 + 3 files changed, 23 insertions(+) create mode 100644 docs/auth/troubleshooting.md diff --git a/docs/auth/troubleshooting.md b/docs/auth/troubleshooting.md new file mode 100644 index 0000000000..caae343407 --- /dev/null +++ b/docs/auth/troubleshooting.md @@ -0,0 +1,21 @@ +--- +id: troubleshooting +title: Troubleshooting Auth +description: Guidance for various issues that one might run into when setting up authentication +--- + +Auth is tricky and doesn't always work as expected. Below you'll find some of the common +problems one might run into when setting up authentication, as well as some general +troubleshooting tips. + +## Sign-in fails with "... provider is not configured to support sign-in" + +This happens if you try to sign in using an auth provider that has not been +configured to allow sign-in. See the [Sign-in Identities and Resolvers](./identity-resolver.md) +page for information about how to configure and customize sign-in. + +As part of the 1.1 release of Backstage we removed the default implementations +of all sign-in resolvers. This was a necessary security fix as well as a step +towards providing more clarity in the configuration of the sign-in process. +You may encounter this error if you are upgrading from a previous version, in +which case you would need to configure a sign-in resolver as described above. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 43e9dd3978..af37b44bac 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -254,6 +254,7 @@ "auth/auth-backend", "auth/oauth", "auth/auth-backend-classes", + "auth/troubleshooting", "auth/glossary" ], "Deployment": [ diff --git a/mkdocs.yml b/mkdocs.yml index 0e56dcbd73..6e4e795f95 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -157,6 +157,7 @@ nav: - Auth backend: 'auth/auth-backend.md' - OAuth and OpenID Connect: 'auth/oauth.md' - Auth backend classes: 'auth/auth-backend-classes.md' + - Troubleshooting Auth: 'auth/troubleshooting.md' - Glossary: 'auth/glossary.md' - Deployment: - Deploying Backstage: 'deployment/index.md' From cce23c31fba345985928b79a5b32313ec3e20913 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 2 May 2022 12:06:03 +0200 Subject: [PATCH 2/4] docs/auth/troubleshooting: add section for misconfigured auth providers Signed-off-by: Patrik Oldsberg --- docs/auth/troubleshooting.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/auth/troubleshooting.md b/docs/auth/troubleshooting.md index caae343407..6a57c75270 100644 --- a/docs/auth/troubleshooting.md +++ b/docs/auth/troubleshooting.md @@ -19,3 +19,16 @@ of all sign-in resolvers. This was a necessary security fix as well as a step towards providing more clarity in the configuration of the sign-in process. You may encounter this error if you are upgrading from a previous version, in which case you would need to configure a sign-in resolver as described above. + +## Auth fails with "Auth provider registered for ... is misconfigured" + +This will typically only happen during development, as in a production build the auth +backend will fail to start up altogether if a provider is misconfigured. + +Double check that your configuration for the provider is correct. Note that environment variables +such as `AUTH_OAUTH2_CLIENT_ID` must be set and will **NOT** be picked up from `.env` files. +You can use the `yarn backstage-cli config:print --lax` command to print your local configuration. + +The backend logs should also provide insight into why the configuration of the provider +fails. In working setup the backend should log something like `"Configuring provider, oauth2"`, +while it with otherwise log a warning like `"Skipping oauth2 auth provider, ..."`. From df6701a5d823425d5a08f0b5e73a02a86ca7c467 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 2 May 2022 12:18:43 +0200 Subject: [PATCH 3/4] docs/auth/troubleshooting: add sections for origin and user not found errors Signed-off-by: Patrik Oldsberg --- docs/auth/troubleshooting.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/auth/troubleshooting.md b/docs/auth/troubleshooting.md index 6a57c75270..4c01ad207a 100644 --- a/docs/auth/troubleshooting.md +++ b/docs/auth/troubleshooting.md @@ -32,3 +32,24 @@ You can use the `yarn backstage-cli config:print --lax` command to print your lo The backend logs should also provide insight into why the configuration of the provider fails. In working setup the backend should log something like `"Configuring provider, oauth2"`, while it with otherwise log a warning like `"Skipping oauth2 auth provider, ..."`. + +## Auth fails with "Login failed; caused by NotAllowedError: Origin '...' is not allowed" + +This will happen if the origin of the configured `app.baseUrl` in the auth backend does not +match the origin that the frontend is being accessed at. Make sure that `app.baseUrl` matches +what a user sees in the browser address bar. + +If you wish to support multiple different origins at once, there is an experimental configuration +that lets you do this. The `auth.experimentalExtraAllowedOrigins` key accepts a list of origin +glob patterns where sign-in should be allowed from. + +## Sign-in fails with the error "User not found" + +Many built-in sign-in resolvers require user entities to be present in the catalog. This +error is encountered if authentication is successful, but a matching user entity is not +present in the catalog. If you wish to enable sign-in without having users be represented +in the catalog data, see the method that's documented in the +[sign-in resolver documentation](./identity-resolver.md#sign-in-without-users-in-the-catalog). + +If you want to customize this error message, you can create a custom sign-in resolver and +catch the `NotFoundError` thrown by `ctx.signInWithCatalogUser` or `ctx.findCatalogUser`. From d768deeac2c82bdb146e86eb12e2c39fb7469b6b Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 2 May 2022 13:04:36 +0200 Subject: [PATCH 4/4] docs/auth/troubleshooting: add general troubleshooting section Signed-off-by: Patrik Oldsberg --- docs/auth/troubleshooting.md | 46 ++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/auth/troubleshooting.md b/docs/auth/troubleshooting.md index 4c01ad207a..657809292a 100644 --- a/docs/auth/troubleshooting.md +++ b/docs/auth/troubleshooting.md @@ -53,3 +53,49 @@ in the catalog data, see the method that's documented in the If you want to customize this error message, you can create a custom sign-in resolver and catch the `NotFoundError` thrown by `ctx.signInWithCatalogUser` or `ctx.findCatalogUser`. + +## General troubleshooting + +This section contains some general troubleshooting tips. + +### Stepping through authentication manually + +Authentication happens in a popup window that redirects to the identity providers authorization +endpoint. Once auth is complete the identity provider will redirect back to the auth backend, +which immediately serves a simple HTML page that posts the result back to the main window, which +then closes the popup. + +Because the popup is closed automatically it can sometimes be difficult to inspect the auth +flow, especially if one wants to debug the cookies that are being set. One way around this is to +manually head to the `/start` endpoint of the provider, which is the page that the popup will +point to initially. For example, if you want to troubleshoot GitHub auth locally, you'd head +to `http://localhost:7007/api/auth/github/start?env=development`. Note that the `env` parameter +needs to be set, and it's possible that you may need to set the `scope` parameter for some providers +as well. + +Once you've stepped through the auth flow you should end up at the `/handler/frame` endpoint, which displays +an empty page. This is where the result is normally posted back to the main window, but since we've +reached it using the manual flow that won't happen. You can still inspect the result though, both +by viewing the source code of the page, or printing the value of the `authResponse` variable in the console. + +### Inspecting the refresh call + +If you're running into problems with session persistence, such as users being signed out when reloading +the page, it will be something that's going wrong with the call to the `/refresh` endpoint of the +auth provider. Head to the network inspector and filter by `/refresh`. Find the `GET` request towards +`/api/auth//refresh` and inspect the request. + +Note that extra calls to the refresh endpoint may be made by the frontend in order to check whether +auth providers have an existing session. This means that there might be multiple calls, including some +that are failing. Make sure you're looking at the refresh call to the provider that you're troubleshooting, +and don't worry about other failing refresh calls. + +### Inspecting the contents of a Backstage token + +The Backstage token that's issues during sign-in is a plain JWT. You can inspect the contents using +any tool that supports JWTs, or you can parse the payload yourself in for example the browser console +or a Node.js REPL: + +```js +atob(token.split('.')[1]); +```