From eb4e894a24f96d44fa112446af9ceba3bbf50784 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 24 Jun 2020 12:05:11 +0200 Subject: [PATCH 1/2] docs/auth: rename overview to README --- docs/auth/{overview.md => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/auth/{overview.md => README.md} (100%) diff --git a/docs/auth/overview.md b/docs/auth/README.md similarity index 100% rename from docs/auth/overview.md rename to docs/auth/README.md From 0fa04efb971e37ac7cbf1ba8123bf58e3d2c23bc Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 24 Jun 2020 18:03:35 +0200 Subject: [PATCH 2/2] docs/auth: add some more information about Identities --- docs/auth/README.md | 50 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 46 insertions(+), 4 deletions(-) diff --git a/docs/auth/README.md b/docs/auth/README.md index 2806b2dccf..081d10add6 100644 --- a/docs/auth/README.md +++ b/docs/auth/README.md @@ -28,11 +28,53 @@ The method with which frontend plugins request access to third party services is through [Utility APIs](../getting-started/utility-apis.md) for each service provider. For a full list of providers, see [TODO](#TODO). -### Identity - TODO +### Identity - WIP -This documentation currently only covers the OAuth use-case, as identity -management is not settled yet and part of an -[upcoming milestone](https://github.com/spotify/backstage/milestone/12). +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/spotify/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. ## Further Reading