From b653a5595c64b0ae66b3c7aa7ca040d9a9d057ab Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 25 Apr 2022 14:54:59 +0200 Subject: [PATCH 1/2] core-plugin-api: stop marking auth APIs as alpha Signed-off-by: Patrik Oldsberg --- .changeset/empty-mugs-bow.md | 5 +++++ packages/core-plugin-api/api-report.md | 16 +++++++------- .../src/apis/definitions/auth.ts | 21 +++++++------------ 3 files changed, 21 insertions(+), 21 deletions(-) create mode 100644 .changeset/empty-mugs-bow.md diff --git a/.changeset/empty-mugs-bow.md b/.changeset/empty-mugs-bow.md new file mode 100644 index 0000000000..d9d63e7f89 --- /dev/null +++ b/.changeset/empty-mugs-bow.md @@ -0,0 +1,5 @@ +--- +'@backstage/core-plugin-api': patch +--- + +The authentication APIs are no longer `@alpha`. Since the `@backstage/core-plugin-api` has no `/alpha` entrypoint, the only effect of marking the APIs as `@alpha` was to hide them in documentation. They are still expected to be widely used and there will be a migration path if they are changed in the future. diff --git a/packages/core-plugin-api/api-report.md b/packages/core-plugin-api/api-report.md index 89361419ba..8289e863e0 100644 --- a/packages/core-plugin-api/api-report.md +++ b/packages/core-plugin-api/api-report.md @@ -172,7 +172,7 @@ export type AppThemeApi = { // @public export const appThemeApiRef: ApiRef; -// @alpha +// @public export const atlassianAuthApiRef: ApiRef< OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi >; @@ -230,7 +230,7 @@ export type BackstageUserIdentity = { ownershipEntityRefs: string[]; }; -// @alpha +// @public export const bitbucketAuthApiRef: ApiRef< OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi >; @@ -462,17 +462,17 @@ export function getComponentData( type: string, ): T | undefined; -// @alpha +// @public export const githubAuthApiRef: ApiRef< OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi >; -// @alpha +// @public export const gitlabAuthApiRef: ApiRef< OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi >; -// @alpha +// @public export const googleAuthApiRef: ApiRef< OAuthApi & OpenIdConnectApi & @@ -517,7 +517,7 @@ export type MergeParams< P2 extends AnyParams, > = (P1[keyof P1] extends never ? {} : P1) & (P2 extends undefined ? {} : P2); -// @alpha +// @public export const microsoftAuthApiRef: ApiRef< OAuthApi & OpenIdConnectApi & @@ -559,7 +559,7 @@ export type OAuthRequesterOptions = { // @public export type OAuthScope = string | string[]; -// @alpha +// @public export const oktaAuthApiRef: ApiRef< OAuthApi & OpenIdConnectApi & @@ -568,7 +568,7 @@ export const oktaAuthApiRef: ApiRef< SessionApi >; -// @alpha +// @public export const oneloginAuthApiRef: ApiRef< OAuthApi & OpenIdConnectApi & diff --git a/packages/core-plugin-api/src/apis/definitions/auth.ts b/packages/core-plugin-api/src/apis/definitions/auth.ts index 497ce8233b..163ae74806 100644 --- a/packages/core-plugin-api/src/apis/definitions/auth.ts +++ b/packages/core-plugin-api/src/apis/definitions/auth.ts @@ -295,8 +295,7 @@ export type SessionApi = { /** * Provides authentication towards Google APIs and identities. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. - * + * @public * @remarks * * See {@link https://developers.google.com/identity/protocols/googlescopes} for a full list of supported scopes. @@ -317,8 +316,7 @@ export const googleAuthApiRef: ApiRef< /** * Provides authentication towards GitHub APIs. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. - * + * @public * @remarks * * See {@link https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/} @@ -333,8 +331,7 @@ export const githubAuthApiRef: ApiRef< /** * Provides authentication towards Okta APIs. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. - * + * @public * @remarks * * See {@link https://developer.okta.com/docs/guides/implement-oauth-for-okta/scopes/} @@ -353,8 +350,7 @@ export const oktaAuthApiRef: ApiRef< /** * Provides authentication towards GitLab APIs. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. - * + * @public * @remarks * * See {@link https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#limiting-scopes-of-a-personal-access-token} @@ -369,8 +365,7 @@ export const gitlabAuthApiRef: ApiRef< /** * Provides authentication towards Microsoft APIs and identities. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. - * + * @public * @remarks * * For more info and a full list of supported scopes, see: @@ -390,7 +385,7 @@ export const microsoftAuthApiRef: ApiRef< /** * Provides authentication towards OneLogin APIs. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. + * @public */ export const oneloginAuthApiRef: ApiRef< OAuthApi & @@ -405,7 +400,7 @@ export const oneloginAuthApiRef: ApiRef< /** * Provides authentication towards Bitbucket APIs. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. + * @public * @remarks * * See {@link https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/} @@ -420,7 +415,7 @@ export const bitbucketAuthApiRef: ApiRef< /** * Provides authentication towards Atlassian APIs. * - * @alpha This API is **EXPERIMENTAL** and might change in the future. + * @public * @remarks * * See {@link https://developer.atlassian.com/cloud/jira/platform/scopes-for-connect-and-oauth-2-3LO-apps/} From 4e80f266ce0ad816fe27cebdc9614e4214a3a893 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 25 Apr 2022 15:23:51 +0200 Subject: [PATCH 2/2] docs: update auth introduction docs + inline usage docs Signed-off-by: Patrik Oldsberg --- .github/styles/vocab.txt | 2 +- docs/auth/index.md | 117 ++++++++++++++++++++------ docs/auth/using-auth.md | 98 --------------------- docs/getting-started/configuration.md | 4 +- microsite/sidebars.json | 1 - mkdocs.yml | 1 - 6 files changed, 91 insertions(+), 132 deletions(-) delete mode 100644 docs/auth/using-auth.md diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index 003979a1a7..acbc47a861 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -322,7 +322,7 @@ toolchain toolsets tooltip tooltips -touchpoints +touchpoint transpilation transpiled transpiler diff --git a/docs/auth/index.md b/docs/auth/index.md index 6bda35232a..3beae72d0b 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -1,18 +1,16 @@ --- id: index -title: Adding Authentication -description: How to add authentication to a Backstage application +title: Authentication in Backstage +description: Introduction to authentication in Backstage --- -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 authentication system in Backstage serves two distinct purposes: sign-in and +identification of users, as well as delegating access to third-party resources. It is possible to +configure Backstage to have any number of authentication providers, but only +one of these will typically be used for sign-in, with the rest being used to provide +access external resources. -See [Using authentication and identity](using-auth.md) for tips on using -Backstage identity information in your app or plugins. - -## Adding an authentication provider +## Built-in Authentication Providers Backstage comes with many common authentication providers in the core library: @@ -31,7 +29,7 @@ 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. -### Adding provider configuration +## Configuring Authentication Providers Each built-in provider has a configuration block under the `auth` section of `app-config.yaml`. For example, the GitHub provider: @@ -56,25 +54,37 @@ 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. -## Using an authentication provider for sign-in +## Sign-In Configuration -If you want to use an authentication provider for sign-in, as opposed to just accessing external resources, you'll need to configure that in your app as well. This is done by providing a custom `SignInPage` component to the app, which will require the user to sign in before they can access the app. Note that this does not block access to the app, which you can read more about [here](./using-auth.md). +> 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. -If you want to, you can use the `SignInPage` component that is provided by `@backstage/core-components`, which takes either a `provider` or `providers` (array) prop of `SignInProviderConfig` definitions. These reference the `ApiRef` exported for the provider. +Using an authentication provide for sign-in is something you need to configure +both in the frontend app, as well as the `auth` backend plugin. For information +on how to configure the backend app, see [Sign-in Identities and Resolvers](./identity-resolver.md). +The rest of this section will focus on how to configure sign-in for the frontend app. -Again, the following example for GitHub shows the additions needed to `packages/app/src/App.tsx`, and can be adapted to any of the built-in providers: +Sign-in is configured by providing a custom `SignInPage` app component. It will +rendered before any other routes in the app and is responsible for providing the +identity of the current user. The `SignInPage` can render any number of pages and +components, or just blank space with logic running in the background. In the end +however it must provide a valid Backstage user identity through the `onSignInSuccess` +callback prop, at which point the rest of the app is rendered. + +If you want to, you can use the `SignInPage` component that is provided by `@backstage/core-components`, +which takes either a `provider` or `providers` (array) prop of `SignInProviderConfig` definitions. + +The following example for GitHub shows the additions needed to `packages/app/src/App.tsx`, +and can be adapted to any of the built-in providers: ```diff + import { githubAuthApiRef } from '@backstage/core-plugin-api'; -+ import { SignInProviderConfig, SignInPage } from '@backstage/core-components'; ++ import { SignInPage } from '@backstage/core-components'; -+ const githubProvider: SignInProviderConfig = { -+ id: 'github-auth-provider', -+ title: 'GitHub', -+ message: 'Sign in using GitHub', -+ apiRef: githubAuthApiRef, -+}; -+ const app = createApp({ apis, + components: { @@ -82,15 +92,20 @@ Again, the following example for GitHub shows the additions needed to `packages/ + + ), + }, bindRoutes({ bind }) { ``` -To also allow unauthenticated guest access, use the `providers` prop for -`SignInPage`: +You can also use the `providers` prop to enable multiple sign-in methods, for example +allows allowing guest access: ```diff const app = createApp({ @@ -99,14 +114,60 @@ To also allow unauthenticated guest access, use the `providers` prop for + SignInPage: props => ( + + ), + }, bindRoutes({ bind }) { ``` -## Adding a custom authentication provider +## For Plugin Developers + +The Backstage frontend core APIs provide a set of Utility APIs for plugin developers +to use, both to access the user identity, as well as third party resources. + +### Identity for Plugin Developers + +For plugin developers, there is one main touchpoint for accessing the user identity: the +`IdentityApi` exported by `@backstage/core-plugin-api` via the `identityApiRef`. + +The `IdentityApi` gives access to the signed-in user's identity in the frontend. +It provides access to the user's entity reference, lightweight profile information, and +a Backstage token that identifies the user when making authenticated calls within Backstage. + +When making calls to backend plugins, we recommend that the `FetchApi` is used, which +is exported via the `fetchApiRef` from `@backstage/core-plugin-api`. The `FetchApi` will +automatically include a Backstage token in the request, meaning there is no need +to interact directly with the `IdentityApi`. + +### Accessing Third Party Resources + +A common 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. These +are all suffixed with `*AuthApiRef`, for example `githubAuthApiRef`. For a +full list of providers, see the +[@backstage/core-plugin-api](../reference/core-plugin-api.md#variables) reference. + +## Custom Authentication Provider There are generic authentication providers for OAuth2 and SAML. These can reduce the amount of code needed to implement a custom authentication provider that diff --git a/docs/auth/using-auth.md b/docs/auth/using-auth.md deleted file mode 100644 index 067c43e8a0..0000000000 --- a/docs/auth/using-auth.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -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 -[@backstage/core-plugin-api](../reference/core-plugin-api.md#variables) -reference. - -### 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-plugin-api` 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-app-api` and `@backstage/core-plugin-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-components` 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/getting-started/configuration.md b/docs/getting-started/configuration.md index e7d100f410..d894230e31 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -193,9 +193,7 @@ go to your Backstage portal in your browser, you should have your login prompt! To learn more about Authentication in Backstage, here are some docs you could read: -- [Adding Authentication](../auth/) -- [Adding a new Authentication Provider](../auth/add-auth-provider.md) -- [Using authentication and identity](../auth/using-auth.md) +- [Authentication in Backstage](../auth/) - [Using organizational data from GitHub](../integrations/github/org.md) ### Setting up a GitHub Integration diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 71911bed2b..81ad453429 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -249,7 +249,6 @@ ] }, "auth/add-auth-provider", - "auth/using-auth", "auth/identity-resolver", "auth/auth-backend", "auth/oauth", diff --git a/mkdocs.yml b/mkdocs.yml index 26e18fbfc0..0e56dcbd73 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -153,7 +153,6 @@ nav: - OAuth2Proxy: 'auth/oauth2-proxy/provider.md' - Bitbucket: 'auth/bitbucket/provider.md' - Adding authentication providers: 'auth/add-auth-provider.md' - - Using authentication and identity: 'auth/using-auth.md' - Sign in resolvers: 'auth/identity-resolver.md' - Auth backend: 'auth/auth-backend.md' - OAuth and OpenID Connect: 'auth/oauth.md'