diff --git a/docs/auth/auth0/provider.md b/docs/auth/auth0/provider.md index 383cda2014..b546285c94 100644 --- a/docs/auth/auth0/provider.md +++ b/docs/auth/auth0/provider.md @@ -46,29 +46,5 @@ The Auth0 provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend To add the provider to the frontend, add the `auth0AuthApi` reference and -`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: - -```diff -+ import { auth0AuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; - -+ const auth0Provider: SignInConfig = { -+ id: 'auth0-auth-provider', -+ title: 'Auth0', -+ message: 'Sign in using Auth0', -+ apiRef: auth0AuthApiRef, -+}; -+ -const app = createApp({ - apis, - plugins: Object.values(plugins), -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { -``` +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/auth/github/provider.md b/docs/auth/github/provider.md index 6e194f36f7..4b65c8c3c2 100644 --- a/docs/auth/github/provider.md +++ b/docs/auth/github/provider.md @@ -49,29 +49,5 @@ The GitHub provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend To add the provider to the frontend, add the `githubAuthApi` reference and -`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: - -```diff -+ import { githubAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; - -+ const githubProvider: SignInConfig = { -+ id: 'github-auth-provider', -+ title: 'GitHub', -+ message: 'Sign in using GitHub', -+ apiRef: githubAuthApiRef, -+}; -+ -const app = createApp({ - apis, - plugins: Object.values(plugins), -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { -``` +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/auth/gitlab/provider.md b/docs/auth/gitlab/provider.md index e9cfdfa98e..8e9c499dc4 100644 --- a/docs/auth/gitlab/provider.md +++ b/docs/auth/gitlab/provider.md @@ -48,29 +48,5 @@ The GitLab provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend To add the provider to the frontend, add the `gitlabAuthApi` reference and -`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: - -```diff -+ import { gitlabAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; - -+ const gitlabProvider: SignInConfig = { -+ id: 'gitlab-auth-provider', -+ title: 'GitLab', -+ message: 'Sign in using GitLab', -+ apiRef: gitlabAuthApiRef, -+}; -+ -const app = createApp({ - apis, - plugins: Object.values(plugins), -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { -``` +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/auth/google/provider.md b/docs/auth/google/provider.md index 2765b509f3..457224b2db 100644 --- a/docs/auth/google/provider.md +++ b/docs/auth/google/provider.md @@ -53,29 +53,5 @@ The Google provider is a structure with two configuration keys: ## Adding the provider to the Backstage frontend To add the provider to the frontend, add the `googleAuthApi` reference and -`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: - -```diff -+ import { googleAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; - -+ const googleProvider: SignInConfig = { -+ id: 'google-auth-provider', -+ title: 'Google', -+ message: 'Sign in using Google', -+ apiRef: googleAuthApiRef, -+}; -+ -const app = createApp({ - apis, - plugins: Object.values(plugins), -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { -``` +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/auth/index.md b/docs/auth/index.md index a8ddf17c6b..0a6bb2c899 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -1,99 +1,121 @@ --- id: index -title: User Authentication and Authorization in Backstage -description: Documentation on User Authentication and Authorization in Backstage +title: Adding Authentication +description: How to add authentication to a Backstage application --- -## Summary +Authentication in Backstage identifies the user, and provides a way for plugins +to make requests on behalf of a user to third-party services. Backstage can have +zero (guest access), one, or many authentication providers. The default +`@backstage/create-app` template uses guest access for easy startup. -The purpose of the Auth APIs in Backstage is to identify the user, and to -provide a way for plugins to request access to 3rd party services on behalf of -the user (OAuth). This documentation focuses on the implementation of that -solution and how to extend it. For documentation on how to consume the Auth APIs -in a plugin, see [TODO](#TODO). +See [Using authentication and identity](using-auth.md) for tips on using +Backstage identity information in your app or plugins. -### Accessing Third Party Services +## Adding an authentication provider -The main pattern for talking to third party services in Backstage is -user-to-server requests, where short-lived OAuth Access Tokens are requested by -plugins to authenticate calls to external services. These calls can be made -either directly to the services or through a backend plugin or service. +Backstage comes with many common authentication providers in the core library: -By relying on user-to-server calls we keep the coupling between the frontend and -backend low, and provide a much lower barrier for plugins to make use of third -party services. This is in comparison to for example a session-based system, -where access tokens are stored server-side. Such a solution would require a much -deeper coupling between the auth backend plugin, its session storage, and other -backend plugins or separate services. A goal of Backstage is to make it as easy -as possible to create new plugins, and an auth solution based on user-to-server -OAuth helps in that regard. +- [Auth0](auth0/provider.md) +- [Azure](microsoft/provider.md) +- [GitHub](github/provider.md) +- [GitLab](gitlab/provider.md) +- [Google](google/provider.md) +- [Okta](okta/provider.md) +- OneLogin -The method with which frontend plugins request access to third party services is -through [Utility APIs](../api/utility-apis.md) for each service provider. For a -full list of providers, see the -[Utility API References](../reference/utility-apis/README.md). +These built-in providers handle the authentication flow for a particular service +including required scopes, callbacks, etc. These providers are each added to a +Backstage app in a similar way. -### Identity - WIP +### Adding provider configuration -> NOTE: Identity management and the `SignInPage` in Backstage is NOT a method -> for blocking access for unauthorized users, that either requires additional -> backend implementation or a separate service like Google's Identity-Aware -> Proxy. The identity system only serves to provide a personalized experience -> and access to a Backstage Identity Token, which can be passed to backend -> plugins. +Each built-in provider has a configuration block under the `auth` section of +`app-config.yaml`. For example, the GitHub provider: -Identity management is still work in progress, but there are already a couple of -pieces in place that can be used. +```yaml +auth: + environment: development + providers: + github: + development: + clientId: ${AUTH_GITHUB_CLIENT_ID} + clientSecret: ${AUTH_GITHUB_CLIENT_SECRET} +``` -#### Identity for Plugin Developers +See the documentation for a particular provider to see what configuration is +needed. -As a plugin developer, there are two main touchpoints for identities: the -`IdentityApi` exported by `@backstage/core` via the `identityApiRef`, and a not -yet existing middleware exported by `@backstage/backend-common`. +The `providers` key may have several authentication providers, if multiple +authentication methods are supported. Each provider may also have configuration +for different authentication environments (development, production, etc). This +allows a single auth backend to serve multiple environments, such as running a +local frontend against a deployed backend. The provider configuration matching +the local `auth.environment` setting will be selected. -The `IdentityApi` gives access to the signed-in user's identity in the frontend. -It provides access to the user's ID, lightweight profile information, and an ID -token used to make authenticated calls within Backstage. +### Adding the provider to the sign-in page -The middleware that will be provided by `@backstage/backend-common` allows -verification of Backstage ID tokens, and optionally loading additional -information about the user. The progress is tracked in -https://github.com/backstage/backstage/issues/1435. +After configuring an authentication provider, the `app` frontend package needs a +small update to show this provider as a login option. The `SignInPage` component +handles this, and takes either a `provider` or `providers` (array) prop of +`SignInConfig` definitions. -#### Identity for App Developers +These reference the [ApiRef](../reference/utility-apis/README.md) exported by +the provider. Again, an example using GitHub that can be adapted to any of the +built-in providers: -If you're setting up your own Backstage app, or want to add a new identity -provider, there are three touchpoints: the frontend auth APIs in -`@backstage/core-api`, the backend auth providers in `auth-backend`, and the -`SignInPage` component configured in the Backstage app via `createApp`. +```diff +# packages/app/src/App.tsx ++ import { githubAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; -The frontend APIs and backend providers are tightly coupled together for each -auth provider, and together they implement an e2e auth flow. Only some auth -providers also act as identity providers though. For example, at the moment of -writing, the Google Auth provider is able to act as a Backstage identity -provider, but the GitHub one can not. For an auth provider to also act as an -identity provider, it needs to implement the `BackstageIdentityApi` in the -frontend, and in the backend it needs to return a `BackstageIdentity` structure. ++ const githubProvider: SignInConfig = { ++ id: 'github-auth-provider', ++ title: 'GitHub', ++ message: 'Sign in using GitHub', ++ apiRef: githubAuthApiRef, ++}; ++ +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` -It is up to each provider to implement the mapping between a provider identity -and the corresponding Backstage identity. That is currently still work in -progress, and as a stop-gap for example the Google provider returns the local -part of the user's email as the user ID. +To also allow unauthenticated guest access, use the `providers` prop for +`SignInPage`: -The final piece of the puzzle is the `SignInPage` component that can be -configured as part of the app. Without a sign-in page, Backstage will fall back -to a `guest` identity for all users, without any ID token. To enable sign-in, a -`SignInPage` needs to be configured, which in turn has to supply a user to the -app. The `@backstage/core` package provides a basic sign-in page that allows -both the user and the app developer to choose between a couple of different -sign-in methods, or to designate a single provider that may also be logged in to -automatically. +```diff +const app = createApp({ + apis, + plugins: Object.values(plugins), ++ components: { ++ SignInPage: props => ( ++ ++ ), ++ }, + bindRoutes({ bind }) { +``` -## Further Reading +## Adding a custom authentication provider -More details are provided in dedicated sections of the documentation. +There are generic authentication providers for OAuth2 and SAML. These can reduce +the amount of code needed to implement a custom authentication provider that +adheres to these standards. -- [OAuth](./oauth.md): Description of the generic OAuth flow implemented by the - [auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend). -- [Glossary](./glossary.md): Glossary of some common terms related to the auth - flows. +Backstage uses [Passport](http://www.passportjs.org/) under the hood, which has +a wide library of authentication strategies for different providers. See +[Add authentication provider](add-auth-provider.md) for details on adding a new +Passport-supported authentication method. diff --git a/docs/auth/microsoft/provider.md b/docs/auth/microsoft/provider.md index 3aa9de0df1..b64f9b1902 100644 --- a/docs/auth/microsoft/provider.md +++ b/docs/auth/microsoft/provider.md @@ -49,29 +49,5 @@ The Microsoft provider is a structure with three configuration keys: ## Adding the provider to the Backstage frontend To add the provider to the frontend, add the `microsoftAuthApi` reference and -`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: - -```diff -+ import { microsoftAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; - -+ const microsoftProvider: SignInConfig = { -+ id: 'microsoft-auth-provider', -+ title: 'Microsoft Azure', -+ message: 'Sign in using Azure', -+ apiRef: microsoftAuthApiRef, -+}; -+ -const app = createApp({ - apis, - plugins: Object.values(plugins), -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { -``` +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/auth/okta/provider.md b/docs/auth/okta/provider.md index 091c5fffb6..da54a30add 100644 --- a/docs/auth/okta/provider.md +++ b/docs/auth/okta/provider.md @@ -62,29 +62,5 @@ The values referenced are found on the Application page on your Okta site. ## Adding the provider to the Backstage frontend To add the provider to the frontend, add the `oktaAuthApi` reference and -`SignInPage` component to `createApp` in `packages/app/src/App.tsx`: - -```diff -+ import { oktaAuthApiRef, SignInConfig, SignInPage } from '@backstage/core'; - -+ const oktaProvider: SignInConfig = { -+ id: 'okta-auth-provider', -+ title: 'Okta', -+ message: 'Sign in using Okta', -+ apiRef: oktaAuthApiRef, -+}; -+ -const app = createApp({ - apis, - plugins: Object.values(plugins), -+ components: { -+ SignInPage: props => ( -+ -+ ), -+ }, - bindRoutes({ bind }) { -``` +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/auth/using-auth.md b/docs/auth/using-auth.md new file mode 100644 index 0000000000..fbc6017272 --- /dev/null +++ b/docs/auth/using-auth.md @@ -0,0 +1,96 @@ +--- +id: using-auth +title: Using authentication and identity +description: How to use authentication and identity in Backstage +--- + +The Auth APIs in Backstage identify the user, and provide a way for plugins to +request access to 3rd party services on behalf of the user (OAuth). This +documentation focuses on the implementation of that solution and how to extend +it. + +### Accessing Third Party Services + +The main pattern for talking to third party services in Backstage is +user-to-server requests, where short-lived OAuth Access Tokens are requested by +plugins to authenticate calls to external services. These calls can be made +either directly to the services or through a backend plugin or service. + +By relying on user-to-server calls we keep the coupling between the frontend and +backend low, and provide a much lower barrier for plugins to make use of third +party services. This is in comparison to for example a session-based system, +where access tokens are stored server-side. Such a solution would require a much +deeper coupling between the auth backend plugin, its session storage, and other +backend plugins or separate services. A goal of Backstage is to make it as easy +as possible to create new plugins, and an auth solution based on user-to-server +OAuth helps in that regard. + +The method with which frontend plugins request access to third party services is +through [Utility APIs](../api/utility-apis.md) for each service provider. For a +full list of providers, see the +[Utility API References](../reference/utility-apis/README.md). + +### Identity - WIP + +> NOTE: Identity management and the `SignInPage` in Backstage is NOT a method +> for blocking access for unauthorized users, that either requires additional +> backend implementation or a separate service like Google's Identity-Aware +> Proxy. The identity system only serves to provide a personalized experience +> and access to a Backstage Identity Token, which can be passed to backend +> plugins. + +Identity management is still work in progress, but there are already a couple of +pieces in place that can be used. + +#### Identity for Plugin Developers + +As a plugin developer, there are two main touchpoints for identities: the +`IdentityApi` exported by `@backstage/core` via the `identityApiRef`, and a not +yet existing middleware exported by `@backstage/backend-common`. + +The `IdentityApi` gives access to the signed-in user's identity in the frontend. +It provides access to the user's ID, lightweight profile information, and an ID +token used to make authenticated calls within Backstage. + +The middleware that will be provided by `@backstage/backend-common` allows +verification of Backstage ID tokens, and optionally loading additional +information about the user. The progress is tracked in +https://github.com/backstage/backstage/issues/1435. + +#### Identity for App Developers + +If you're setting up your own Backstage app, or want to add a new identity +provider, there are three touchpoints: the frontend auth APIs in +`@backstage/core-api`, the backend auth providers in `auth-backend`, and the +`SignInPage` component configured in the Backstage app via `createApp`. + +The frontend APIs and backend providers are tightly coupled together for each +auth provider, and together they implement an e2e auth flow. Only some auth +providers also act as identity providers though. For example, at the moment of +writing, the Google Auth provider is able to act as a Backstage identity +provider, but the GitHub one can not. For an auth provider to also act as an +identity provider, it needs to implement the `BackstageIdentityApi` in the +frontend, and in the backend it needs to return a `BackstageIdentity` structure. + +It is up to each provider to implement the mapping between a provider identity +and the corresponding Backstage identity. That is currently still work in +progress, and as a stop-gap for example the Google provider returns the local +part of the user's email as the user ID. + +The final piece of the puzzle is the `SignInPage` component that can be +configured as part of the app. Without a sign-in page, Backstage will fall back +to a `guest` identity for all users, without any ID token. To enable sign-in, a +`SignInPage` needs to be configured, which in turn has to supply a user to the +app. The `@backstage/core` package provides a basic sign-in page that allows +both the user and the app developer to choose between a couple of different +sign-in methods, or to designate a single provider that may also be logged in to +automatically. + +## Further Reading + +More details are provided in dedicated sections of the documentation. + +- [OAuth](./oauth.md): Description of the generic OAuth flow implemented by the + [auth-backend](https://github.com/backstage/backstage/tree/master/plugins/auth-backend). +- [Glossary](./glossary.md): Glossary of some common terms related to the auth + flows. diff --git a/docs/integrations/azure/locations.md b/docs/integrations/azure/locations.md index 4ce19bad4e..163674f00a 100644 --- a/docs/integrations/azure/locations.md +++ b/docs/integrations/azure/locations.md @@ -2,8 +2,8 @@ id: locations title: Azure DevOps Locations sidebar_label: Locations -description: - Integrating source code stored in Azure DevOps into the Backstage catalog +# prettier-ignore +description: Integrating source code stored in Azure DevOps into the Backstage catalog --- The Azure integration supports loading catalog entities from Azure DevOps. diff --git a/docs/integrations/bitbucket/discovery.md b/docs/integrations/bitbucket/discovery.md index b31071be7f..b24734abde 100644 --- a/docs/integrations/bitbucket/discovery.md +++ b/docs/integrations/bitbucket/discovery.md @@ -2,8 +2,8 @@ id: discovery title: Bitbucket Discovery sidebar_label: Discovery -description: - Automatically discovering catalog entities from repositories in Bitbucket +# prettier-ignore +description: Automatically discovering catalog entities from repositories in Bitbucket --- The Bitbucket integration has a special discovery processor for discovering diff --git a/docs/integrations/bitbucket/locations.md b/docs/integrations/bitbucket/locations.md index 588d8b3bcc..992a240290 100644 --- a/docs/integrations/bitbucket/locations.md +++ b/docs/integrations/bitbucket/locations.md @@ -2,8 +2,8 @@ id: locations title: Bitbucket Locations sidebar_label: Locations -description: - Integrating source code stored in Bitbucket into the Backstage catalog +# prettier-ignore +description: Integrating source code stored in Bitbucket into the Backstage catalog --- The Bitbucket integration supports loading catalog entities from bitbucket.org diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index fe52feab6e..a578d0893d 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -2,9 +2,8 @@ id: discovery title: GitHub Discovery sidebar_label: Discovery -description: - Automatically discovering catalog entities from repositories in a GitHub - organization +# prettier-ignore +description: Automatically discovering catalog entities from repositories in a GitHub organization --- The GitHub integration has a special discovery processor for discovering catalog diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 6c12aa8666..94f18daa09 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -2,9 +2,8 @@ id: index title: Integrations sidebar_label: Overview -description: - Configuring Backstage to read or publish data with external providers using - integrations +# prettier-ignore +description: Configuring Backstage to read or publish data with external providers using integrations --- Integrations allow Backstage to read or publish data using external providers diff --git a/docs/tutorials/switching-sqlite-postgres.md b/docs/tutorials/switching-sqlite-postgres.md index dfb82ddc51..72e5589baf 100644 --- a/docs/tutorials/switching-sqlite-postgres.md +++ b/docs/tutorials/switching-sqlite-postgres.md @@ -1,8 +1,8 @@ --- id: switching-sqlite-postgres title: Switching Backstage from SQLite to PostgreSQL -description: - How to get ready for deploying Backstage to production with PostgreSQL +# prettier-ignore +description: How to get ready for deploying Backstage to production with PostgreSQL --- The default `@backstage/create-app` database is SQLite, an in-memory database diff --git a/microsite/sidebars.json b/microsite/sidebars.json index fd21726271..0a438b7653 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -186,7 +186,6 @@ ], "Auth and identity": [ "auth/index", - "auth/add-auth-provider", { "type": "subcategory", "label": "Included providers", @@ -199,10 +198,12 @@ "auth/okta/provider" ] }, + "auth/add-auth-provider", + "auth/using-auth", "auth/auth-backend", "auth/oauth", - "auth/glossary", - "auth/auth-backend-classes" + "auth/auth-backend-classes", + "auth/glossary" ], "Designing for Backstage": [ "dls/design",