Update auth index to be more "getting started" focused
Signed-off-by: Tim Hansen <timbonicus@gmail.com>
This commit is contained in:
Tim Hansen
+97
-75
@@ -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 => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ provider={githubProvider}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
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 => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ providers={['guest', githubProvider]}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user