docs/auth: add some more information about Identities

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