paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 29 Packages Projects Releases Wiki Activity

docs: update auth introduction docs + inline usage docs

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2022-04-25 15:23:51 +02:00
parent b653a5595c
commit 4e80f266ce
6 changed files with 91 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/styles/vocab.txt
+1 -1
View File
@@ -322,7 +322,7 @@ toolchain
toolsets
tooltip
tooltips
touchpoints
touchpoint
transpilation
transpiled
transpiler
docs/auth/index.md
+89 -28
View File
@@ -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/
+ <SignInPage
+ {...props}
+ auto
+ provider={githubProvider}
+ provider={{
+ id: 'github-auth-provider',
+ title: 'GitHub',
+ message: 'Sign in using GitHub',
+ apiRef: githubAuthApiRef,
+ }}
+ />
+ ),
+ },
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 => (
+ <SignInPage
+ {...props}
+ providers={['guest', githubProvider]}
+ providers={['guest', {
+ id: 'github-auth-provider',
+ title: 'GitHub',
+ message: 'Sign in using GitHub',
+ apiRef: githubAuthApiRef,
+ }]}
+ />
+ ),
+ },
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
docs/auth/using-auth.md
-98
View File
@@ -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.
docs/getting-started/configuration.md
+1 -3
View File
@@ -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
microsite/sidebars.json
-1
View File
@@ -249,7 +249,6 @@
]
},
"auth/add-auth-provider",
"auth/using-auth",
"auth/identity-resolver",
"auth/auth-backend",
"auth/oauth",
mkdocs.yml
-1
View File
@@ -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'