Merge pull request #5143 from backstage/timbonicus/auth-provider-docs
Add documentation for included auth providers
This commit is contained in:
Ben Lambert
@@ -0,0 +1,74 @@
|
||||
---
|
||||
id: provider
|
||||
title: Auth0 Authentication Provider
|
||||
sidebar_label: Auth0
|
||||
description: Adding Auth0 as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
The Backstage `core-api` package comes with an Auth0 authentication provider
|
||||
that can authenticate users using OAuth.
|
||||
|
||||
## Create an Auth0 Application
|
||||
|
||||
1. Log in to the [Auth0 dashboard](https://manage.auth0.com/dashboard/)
|
||||
2. Navigate to **Applications**
|
||||
3. Create an Application
|
||||
- Name: Backstage (or your custom app name)
|
||||
- Application type: Single Page Web Application
|
||||
4. Click on the Settings tab
|
||||
5. Add under `Application URIs` > `Allowed Callback URLs`:
|
||||
`http://localhost:7000/api/auth/auth0/handler/frame`
|
||||
6. Click `Save Changes`
|
||||
|
||||
## Configuration
|
||||
|
||||
The provider configuration can then be added to your `app-config.yaml` under the
|
||||
root `auth` configuration:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
auth0:
|
||||
development:
|
||||
clientId: ${AUTH_AUTH0_CLIENT_ID}
|
||||
clientSecret: ${AUTH_AUTH0_CLIENT_SECRET}
|
||||
domain: ${AUTH_AUTH0_DOMAIN_ID}
|
||||
```
|
||||
|
||||
The Auth0 provider is a structure with three configuration keys:
|
||||
|
||||
- `clientId`: The Application client ID, found on the Auth0 Application page
|
||||
- `clientSecret`: The Application client secret, found on the Auth0 Application
|
||||
page
|
||||
- `domain`: The Application domain, found on the Auth0 Application page
|
||||
|
||||
## Adding the provider to the Backstage frontend
|
||||
|
||||
To add the provider to the frontend, add the `auth0AuthApi` reference and
|
||||
`SignInPage` component to `createApp` in `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import { auth0AuthApiRef, SignInConfig, SignInPage } from '@backstage/core';
|
||||
|
||||
+ const auth0Provider: SignInConfig = {
|
||||
+ id: 'auth0-auth-provider',
|
||||
+ title: 'Auth0',
|
||||
+ message: 'Sign in using Auth0',
|
||||
+ apiRef: auth0AuthApiRef,
|
||||
+};
|
||||
+
|
||||
const app = createApp({
|
||||
apis,
|
||||
plugins: Object.values(plugins),
|
||||
+ components: {
|
||||
+ SignInPage: props => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ provider={auth0Provider}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
bindRoutes({ bind }) {
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: provider
|
||||
title: GitHub Authentication Provider
|
||||
sidebar_label: GitHub
|
||||
description: Adding GitHub OAuth as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
The Backstage `core-api` package comes with a GitHub authentication provider
|
||||
that can authenticate users using GitHub or GitHub Enterprise OAuth.
|
||||
|
||||
## Create an OAuth App on GitHub
|
||||
|
||||
To add GitHub authentication, you must create an OAuth App from the GitHub
|
||||
[developer settings](https://github.com/settings/developers). The `Homepage URL`
|
||||
should point to Backstage's frontend, while the `Authorization callback URL`
|
||||
will point to the auth backend.
|
||||
|
||||
Settings for local development:
|
||||
|
||||
- Application name: Backstage (or your custom app name)
|
||||
- Homepage URL: `http://localhost:3000`
|
||||
- Authorization callback URL: `http://localhost:7000/api/auth/github`
|
||||
|
||||
## Configuration
|
||||
|
||||
The provider configuration can then be added to your `app-config.yaml` under the
|
||||
root `auth` configuration:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
github:
|
||||
development:
|
||||
clientId: ${AUTH_GITHUB_CLIENT_ID}
|
||||
clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
|
||||
## uncomment if using GitHub Enterprise
|
||||
# enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
|
||||
```
|
||||
|
||||
The GitHub provider is a structure with three configuration keys:
|
||||
|
||||
- `clientId`: The client ID that you generated on GitHub, e.g.
|
||||
`b59241722e3c3b4816e2`
|
||||
- `clientSecret`: The client secret tied to the generated client ID.
|
||||
- `enterpriseInstanceUrl` (optional): The base URL for a GitHub Enterprise
|
||||
instance, e.g. `https://ghe.<company>.com`. Only needed for GitHub Enterprise.
|
||||
|
||||
## Adding the provider to the Backstage frontend
|
||||
|
||||
To add the provider to the frontend, add the `githubAuthApi` reference and
|
||||
`SignInPage` component to `createApp` in `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import { githubAuthApiRef, SignInConfig, SignInPage } from '@backstage/core';
|
||||
|
||||
+ 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 }) {
|
||||
```
|
||||
@@ -0,0 +1,76 @@
|
||||
---
|
||||
id: provider
|
||||
title: GitLab Authentication Provider
|
||||
sidebar_label: GitLab
|
||||
description: Adding GitLab OAuth as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
The Backstage `core-api` package comes with a GitLab authentication provider
|
||||
that can authenticate users using GitLab OAuth.
|
||||
|
||||
## Create an OAuth App on GitLab
|
||||
|
||||
To support GitLab authentication, you must create an Application from the
|
||||
[GitLab settings](https://gitlab.com/-/profile/applications). The `Redirect URI`
|
||||
should point to your Backstage backend auth handler.
|
||||
|
||||
Settings for local development:
|
||||
|
||||
- Name: Backstage (or your custom app name)
|
||||
- Redirect URI: `http://localhost:7000/api/auth/gitlab/handler/frame`
|
||||
- Scopes: read_user
|
||||
|
||||
## Configuration
|
||||
|
||||
The provider configuration can then be added to your `app-config.yaml` under the
|
||||
root `auth` configuration:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
gitlab:
|
||||
development:
|
||||
clientId: ${AUTH_GITLAB_APPLICATION_ID}
|
||||
clientSecret: ${AUTH_GITLAB_SECRET}
|
||||
## uncomment if using self-hosted GitLab
|
||||
# audience: https://gitlab.company.com
|
||||
```
|
||||
|
||||
The GitLab provider is a structure with three configuration keys:
|
||||
|
||||
- `clientId`: The Application ID that you generated on GitLab, e.g.
|
||||
`4928c033ab3d592845c044a653bc20583baf84f2e67b954c6fdb32a532ab76c9`
|
||||
- `clientSecret`: The Application secret
|
||||
- `audience` (optional): The base URL for the self-hosted GitLab instance, e.g.
|
||||
`https://gitlab.company.com`
|
||||
|
||||
## Adding the provider to the Backstage frontend
|
||||
|
||||
To add the provider to the frontend, add the `gitlabAuthApi` reference and
|
||||
`SignInPage` component to `createApp` in `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import { gitlabAuthApiRef, SignInConfig, SignInPage } from '@backstage/core';
|
||||
|
||||
+ const gitlabProvider: SignInConfig = {
|
||||
+ id: 'gitlab-auth-provider',
|
||||
+ title: 'GitLab',
|
||||
+ message: 'Sign in using GitLab',
|
||||
+ apiRef: gitlabAuthApiRef,
|
||||
+};
|
||||
+
|
||||
const app = createApp({
|
||||
apis,
|
||||
plugins: Object.values(plugins),
|
||||
+ components: {
|
||||
+ SignInPage: props => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ provider={gitlabProvider}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
bindRoutes({ bind }) {
|
||||
```
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
id: provider
|
||||
title: Google Authentication Provider
|
||||
sidebar_label: Google
|
||||
description: Adding Google OAuth as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
The Backstage `core-api` package comes with a Google authentication provider
|
||||
that can authenticate users using Google OAuth.
|
||||
|
||||
## Create OAuth Credentials
|
||||
|
||||
To support Google authentication, you must create OAuth credentials:
|
||||
|
||||
1. Log in to the [Google Console](https://console.cloud.google.com)
|
||||
2. Select or create a new project from the dropdown menu on the top bar
|
||||
3. Navigate to
|
||||
[APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials)
|
||||
4. Click **Create Credentials** and choose `OAuth client ID`
|
||||
5. Configure an OAuth consent screen, if required
|
||||
- For local development, you do not need to enter any Authorized domain
|
||||
- For scopes, select `openid`, `auth/userinfo.email` and
|
||||
`auth/userinfo.profile`
|
||||
- Add yourself as a test user, if using External user type
|
||||
6. Set **Application Type** to `Web Application` with these settings:
|
||||
- `Name`: Backstage (or your custom app name)
|
||||
- `Authorized JavaScript origins`: http://localhost:3000
|
||||
- `Authorized Redirect URIs`:
|
||||
http://localhost:7000/api/auth/google/handler/frame
|
||||
7. Click Create
|
||||
|
||||
## Configuration
|
||||
|
||||
The provider configuration can then be added to your `app-config.yaml` under the
|
||||
root `auth` configuration:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
google:
|
||||
development:
|
||||
clientId: ${AUTH_GOOGLE_CLIENT_ID}
|
||||
clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET}
|
||||
```
|
||||
|
||||
The Google provider is a structure with two configuration keys:
|
||||
|
||||
- `clientId`: The client ID that you generated, e.g.
|
||||
`10023341500512-beui241gjwwkrdkr2eh7dprewj2pp1q.apps.googleusercontent.com`
|
||||
- `clientSecret`: The client secret tied to the generated client ID.
|
||||
|
||||
## Adding the provider to the Backstage frontend
|
||||
|
||||
To add the provider to the frontend, add the `googleAuthApi` reference and
|
||||
`SignInPage` component to `createApp` in `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import { googleAuthApiRef, SignInConfig, SignInPage } from '@backstage/core';
|
||||
|
||||
+ const googleProvider: SignInConfig = {
|
||||
+ id: 'google-auth-provider',
|
||||
+ title: 'Google',
|
||||
+ message: 'Sign in using Google',
|
||||
+ apiRef: googleAuthApiRef,
|
||||
+};
|
||||
+
|
||||
const app = createApp({
|
||||
apis,
|
||||
plugins: Object.values(plugins),
|
||||
+ components: {
|
||||
+ SignInPage: props => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ provider={googleProvider}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
bindRoutes({ bind }) {
|
||||
```
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: provider
|
||||
title: Microsoft Azure Authentication Provider
|
||||
sidebar_label: Azure
|
||||
description: Adding Microsoft Azure as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
The Backstage `core-api` package comes with a Microsoft authentication provider
|
||||
that can authenticate users using Azure OAuth.
|
||||
|
||||
## Create an App Registration on Azure
|
||||
|
||||
To support Azure authentication, you must create an App Registration:
|
||||
|
||||
1. Log in to the [Azure Portal](https://portal.azure.com/)
|
||||
2. Create an
|
||||
[Active Directory Tenant](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview),
|
||||
if one does not yet exist
|
||||
3. Navigate to
|
||||
[Azure Active Directory > App Registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps)
|
||||
4. Register an application
|
||||
- Name: Backstage (or your custom app name)
|
||||
- Redirect URI: Web >
|
||||
`http://localhost:7000/api/auth/microsoft/handler/frame`
|
||||
5. Navigate to **Certificates & secrets > New client secret** to create a secret
|
||||
|
||||
## Configuration
|
||||
|
||||
The provider configuration can then be added to your `app-config.yaml` under the
|
||||
root `auth` configuration:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
microsoft:
|
||||
development:
|
||||
clientId: ${AUTH_MICROSOFT_CLIENT_ID}
|
||||
clientSecret: ${AUTH_MICROSOFT_CLIENT_SECRET}
|
||||
tenantId: ${AUTH_MICROSOFT_TENANT_ID}
|
||||
```
|
||||
|
||||
The Microsoft provider is a structure with three configuration keys:
|
||||
|
||||
- `clientId`: Application (client) ID, found on App Registration > Overview
|
||||
- `clientSecret`: Secret, found on App Registration > Certificates & secrets
|
||||
- `tenentId`: Directory (tenant) ID, found on App Registration > Overview
|
||||
|
||||
## Adding the provider to the Backstage frontend
|
||||
|
||||
To add the provider to the frontend, add the `microsoftAuthApi` reference and
|
||||
`SignInPage` component to `createApp` in `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import { microsoftAuthApiRef, SignInConfig, SignInPage } from '@backstage/core';
|
||||
|
||||
+ const microsoftProvider: SignInConfig = {
|
||||
+ id: 'microsoft-auth-provider',
|
||||
+ title: 'Microsoft Azure',
|
||||
+ message: 'Sign in using Azure',
|
||||
+ apiRef: microsoftAuthApiRef,
|
||||
+};
|
||||
+
|
||||
const app = createApp({
|
||||
apis,
|
||||
plugins: Object.values(plugins),
|
||||
+ components: {
|
||||
+ SignInPage: props => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ provider={microsoftProvider}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
bindRoutes({ bind }) {
|
||||
```
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
id: provider
|
||||
title: Okta Authentication Provider
|
||||
sidebar_label: Okta
|
||||
description: Adding Okta OAuth as an authentication provider in Backstage
|
||||
---
|
||||
|
||||
The Backstage `core-api` package comes with a Okta authentication provider that
|
||||
can authenticate users using Okta OpenID Connect.
|
||||
|
||||
## Create an Application on Okta
|
||||
|
||||
To add Okta authentication, you must create an Application from Okta:
|
||||
|
||||
1. Log into Okta (generally company.okta.com)
|
||||
2. Navigation to Applications > Applications
|
||||
3. Click `Add Application`
|
||||
4. Click `Create New App` and select Web + OpenID Connect
|
||||
5. Fill out the OpenID Connect App Integration form:
|
||||
- `Application name`: Backstage (or your custom app name)
|
||||
- `Login redirect URIs`: `Add URI` >
|
||||
`http://localhost:7000/api/auth/okta/handler/frame`
|
||||
6. Click Save
|
||||
7. Under `General Settings`, click Edit and check the `Refresh Token` box
|
||||
8. Click Save
|
||||
|
||||
## Assign the Application
|
||||
|
||||
Okta login is only permitted to those people or groups that have this new
|
||||
Application **assigned**. This can be done from Okta's Directory.
|
||||
|
||||
These are the steps to assign Backstage login permission to **everyone**:
|
||||
|
||||
1. Navigate to Directory > Groups on Okta
|
||||
2. Click on the `Everyone` group
|
||||
3. Click `Manage Apps` and then `Assign` next to Backstage
|
||||
|
||||
# Configuration
|
||||
|
||||
The provider configuration can then be added to your `app-config.yaml` under the
|
||||
root `auth` configuration:
|
||||
|
||||
```yaml
|
||||
auth:
|
||||
environment: development
|
||||
providers:
|
||||
okta:
|
||||
development:
|
||||
clientId: ${AUTH_OKTA_CLIENT_ID}
|
||||
clientSecret: ${AUTH_OKTA_CLIENT_SECRET}
|
||||
audience: ${AUTH_OKTA_DOMAIN}
|
||||
```
|
||||
|
||||
The values referenced are found on the Application page on your Okta site.
|
||||
|
||||
- `clientId`: The client ID that you generated on Okta, e.g.
|
||||
`3abe134ejxzF21HU74c1`
|
||||
- `clientSecret`: The client secret shown for the Application.
|
||||
- `audience`: The Okta domain shown for your Application, e.g.
|
||||
`https://company.okta.com`
|
||||
|
||||
## Adding the provider to the Backstage frontend
|
||||
|
||||
To add the provider to the frontend, add the `oktaAuthApi` reference and
|
||||
`SignInPage` component to `createApp` in `packages/app/src/App.tsx`:
|
||||
|
||||
```diff
|
||||
+ import { oktaAuthApiRef, SignInConfig, SignInPage } from '@backstage/core';
|
||||
|
||||
+ const oktaProvider: SignInConfig = {
|
||||
+ id: 'okta-auth-provider',
|
||||
+ title: 'Okta',
|
||||
+ message: 'Sign in using Okta',
|
||||
+ apiRef: oktaAuthApiRef,
|
||||
+};
|
||||
+
|
||||
const app = createApp({
|
||||
apis,
|
||||
plugins: Object.values(plugins),
|
||||
+ components: {
|
||||
+ SignInPage: props => (
|
||||
+ <SignInPage
|
||||
+ {...props}
|
||||
+ auto
|
||||
+ provider={oktaProvider}
|
||||
+ />
|
||||
+ ),
|
||||
+ },
|
||||
bindRoutes({ bind }) {
|
||||
```
|
||||
@@ -13,6 +13,10 @@ is a hierarchy of
|
||||
[`Group`](../../features/software-catalog/descriptor-format.md#kind-group) kind
|
||||
entities that mirror your org setup.
|
||||
|
||||
> Note: This adds `User` and `Group` entities to the catalog, but does not
|
||||
> provide authentication. See the
|
||||
> [GitHub auth provider](../../auth/github/provider.md) for that.
|
||||
|
||||
## Installation
|
||||
|
||||
The processor that performs the import, `GithubOrgReaderProcessor`, comes
|
||||
|
||||
@@ -184,6 +184,18 @@
|
||||
"Auth and identity": [
|
||||
"auth/index",
|
||||
"auth/add-auth-provider",
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "Included providers",
|
||||
"ids": [
|
||||
"auth/auth0/provider",
|
||||
"auth/microsoft/provider",
|
||||
"auth/github/provider",
|
||||
"auth/gitlab/provider",
|
||||
"auth/google/provider",
|
||||
"auth/okta/provider"
|
||||
]
|
||||
},
|
||||
"auth/auth-backend",
|
||||
"auth/oauth",
|
||||
"auth/glossary",
|
||||
|
||||
Reference in New Issue
Block a user