From 38e185b2beaffb6d296ac4538f6cf7486f1c592b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Tue, 18 Aug 2020 15:50:43 +0200 Subject: [PATCH] docs(auth-backend): some minor tweaks (#1989) --- docs/auth/auth-backend-classes.md | 92 ++++++++++++++++--------------- 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/docs/auth/auth-backend-classes.md b/docs/auth/auth-backend-classes.md index 1a476fa2f0..42ee48c5e0 100644 --- a/docs/auth/auth-backend-classes.md +++ b/docs/auth/auth-backend-classes.md @@ -1,11 +1,11 @@ -# Authentication backend class layout and description. +# Authentication Backend Classes Layout and Description -## How does authentication work ? +## How Does Authentication Work? -The Backstage application can use various authentication `providers` for -authentication. A provider has to implement an `AuthProviderRouterHandlers` -interface for handling authentication. This interface consists of 4 methods. -Each of this method is hosted at an endpoint `/auth/[provider]/method`, where +The Backstage application can use various authentication providers for +authentication. A provider has to implement an `AuthProviderRouteHandlers` +interface for handling authentication. This interface consists of four methods. +Each of these methods is hosted at an endpoint `/auth/[provider]/method`, where `method` performs a certain operation as follows: ``` @@ -16,44 +16,45 @@ Each of this method is hosted at an endpoint `/auth/[provider]/method`, where ``` For more information on how these methods are used and for which purpose, refer -to the documentation [here](oauth.md) +to the documentation [here](oauth.md). For details on the parameters, input and output conditions for each method, refer to the type documentation under -`backstage/plugins/auth-backend/src/providers/types.ts` +`plugins/auth-backend/src/providers/types.ts`. -There are currently 2 different classes for 2 authentication mechanisms that -implement this interface: `OAuthProvider` for `OAuth` based Mechanism and a -`SAMLAuthProvider` for a `SAML` based mechanism +There are currently two different classes for two authentication mechanisms that +implement this interface: an `OAuthProvider` for [OAuth](https://oauth.net/2/) +based mechanisms and a `SAMLAuthProvider` for +[SAML](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html) +based mechanisms. -### `OAuth` mechanisms +### OAuth mechanisms -Currently `OAuth` is assumed to be the defacto authentication mechanism for -backstage based applications. +Currently OAuth is assumed to be the de facto authentication mechanism for +Backstage based applications. -Backstage comes with `batteries-included` set of OAuth Providers for some -commonly used Providers : `Okta`, `Github`, `Google` , `Gitlab` and a generic -`oauth2` provider. +Backstage comes with a "batteries-included" set of supported commonly used OAuth +providers: Okta, Github, Google, Gitlab, and a generic OAuth2 provider. -All of these use the `authorization` flow of OAuth2 to implement authentication. +All of these use the authorization flow of OAuth2 to implement authentication. -If your `authentication` provider is any of the above mentioned (except -`oauth2`) providers, you can configure them by setting the right variables in -`app-config.yaml` under then `auth` section. +If your authentication provider is any of the above mentioned (except generic +OAuth2) providers, you can configure them by setting the right variables in +`app-config.yaml` under the `auth` section. ### Configuration -Each authentication (except SAML )provider needs 5 parameters: an `oauth` -client_id, client_secret, an authorization endpoint and a token endpoint, and an -app origin. The `appOrigin` value is the URL at which the frontend of the -application is hosted. This is required because, the application opens a popup -window to perform the authentication and once the flow is completed, the popup +Each authentication provider (except SAML) needs five parameters: an OAuth +client ID, a client secret, an authorization endpoint and a token endpoint, and +an app origin. The app origin is the URL at which the frontend of the +application is hosted. This is required because the application opens a popup +window to perform the authentication, and once the flow is completed, the popup window sends a `postMessage` to the frontend application to indicate the result of the operation. Also this URL is used to verify that authentication requests are coming from only this endpoint. These values are configured via the `app-config.yaml` present in the root of -your app folder +your app folder. ``` auth: @@ -87,36 +88,37 @@ auth: secure: false clientId: $secret: + ... ``` -## Technical notes +## Technical Notes ### EnvironmentHandler -The concept of an `env` is core to the way the `auth-backend` works. `Spotify` -uses an `env` query parameter to identify the environment in which the -application is running (`dev`, `staging`, `prod`, etc). Each runtime can support +The concept of an "env" is core to the way the auth backend works. It uses an +`env` query parameter to identify the environment in which the application is +running (`development`, `staging`, `production`, etc). Each runtime can support multiple environments at the same time and the right handler for each request is identified and dispatched to based on the `env` parameter. All -`AuthProviderRouterHandlers` are wrapped within a `EnvironmentHandler`. +`AuthProviderRouteHandlers` are wrapped within an `EnvironmentHandler`. -An `EnvironmentHandler` takes an `id` for each provider that it wraps, the -handlers for each of the `env` the provider is supported in, and a `function` -that given a `Request` as argument, can extract the information about the `env` -under which it should be processed. +An `EnvironmentHandler` takes an ID for each provider that it wraps, the +handlers for each env the provider is supported in, and a function that, given a +`Request` as argument, can extract the information about the env under which it +should be processed. -Each provider exposes a factory function `createXProvider` (where X = name of -the Provider) that takes the globalconfig, env and other parameters and returns -a `AuthProviderRouteHandler` for each env, AND, a `envIdentifier` fn to identify -the `env` in a request. +Each provider exposes a factory function `createXProvider` (where X is the name +of the provider) that takes the global config, env and other parameters and +returns an `AuthProviderRouteHandlers` for each env, and an `envIdentifier` +function to identify the env of a request. For a list of currently available providers, look in the `factories` module -located in `backstage/plugins/auth-backend/src/providers/factories.ts` +located in `plugins/auth-backend/src/providers/factories.ts` -### `oauth2` provider +### OAuth2 provider -The `oauth2` provider abstracts a generic **OAuth2+OIDC** based authentication +The `oauth2` provider abstracts a generic **OAuth2 + OIDC** based authentication provider. What this means is that after the application has been given -permission by the user, the`authorization code` will be exchanged for an -`access_token` , a `refresh_token` and an `id_token`. This `id_token` is used to +permission by the user, the `authorization code` will be exchanged for an +`access_token`, a `refresh_token` and an `id_token`. This `id_token` is used to obtain an email id of the user, which is then used for creating the session.