message: docs/auth: add some more information about Identities
diff: @@ -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
  