paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 45 Packages Projects Releases Wiki Activity

Add titles to codeblocks and switch from diff codeblock to language codeblock

Browse Source 
Signed-off-by: Paul Schultz <pschultz@pobox.com>
This commit is contained in:
Paul Schultz
2023-03-01 13:30:38 -06:00
parent adf9fe58f5
commit 9c95f91c0a
44 changed files with 2257 additions and 1869 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auth/cloudflare/access.md
+12 -6
View File
@@ -38,7 +38,7 @@ add the provider itself.
Add a `providerFactories` entry to the router in
`packages/backend/plugin/auth.ts`.
```ts
```ts title="packages/backend/plugin/auth.ts"
import { providers } from '@backstage/plugin-auth-backend';
export default async function createPlugin(
@@ -89,12 +89,18 @@ the user's behalf.
It is recommended to use the `ProxiedSignInPage` for this provider, which is
installed in `packages/app/src/App.tsx` like this:
```diff
+import { ProxiedSignInPage } from '@backstage/core-components';
```tsx title="packages/app/src/App.tsx"
/* highlight-add-next-line */
import { ProxiedSignInPage } from '@backstage/core-components';
const app = createApp({
components: {
+ SignInPage: props => <ProxiedSignInPage {...props} provider="cfaccess" />,
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => <ProxiedSignInPage {...props} provider="cfaccess" />,
},
/* highlight-add-end */
// ..
})
```
See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for pointers on how to set up the sign-in page to also work smoothly for local development.
docs/auth/google/gcp-iap-auth.md
+12 -6
View File
@@ -45,7 +45,7 @@ callbacks in actual code as well as described below.
Add a `providerFactories` entry to the router in
`packages/backend/src/plugins/auth.ts`.
```ts
```ts title="packages/backend/src/plugins/auth.ts"
import { providers } from '@backstage/plugin-auth-backend';
import { stringifyEntityRef } from '@backstage/catalog-model';
@@ -99,12 +99,18 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf.
It is recommended to use the `ProxiedSignInPage` for this provider, which is
installed in `packages/app/src/App.tsx` like this:
```diff
+import { ProxiedSignInPage } from '@backstage/core-components';
```tsx title="packages/app/src/App.tsx"
/* highlight-add-next-line */
import { ProxiedSignInPage } from '@backstage/core-components';
const app = createApp({
components: {
+ SignInPage: props => <ProxiedSignInPage {...props} provider="gcp-iap" />,
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => <ProxiedSignInPage {...props} provider="gcp-iap" />,
},
/* highlight-add-end */
// ..
})
```
See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information.
docs/auth/index.md
+64 -54
View File
@@ -84,49 +84,55 @@ which takes either a `provider` or `providers` (array) prop of `SignInProviderCo
The following example for GitHub shows the additions needed to `packages/app/src/App.tsx`,
and can be adapted to any of the built-in providers:
```diff
+ import { githubAuthApiRef } from '@backstage/core-plugin-api';
+ import { SignInPage } from '@backstage/core-components';
```tsx title="packages/app/src/App.tsx"
/* highlight-add-start */
import { githubAuthApiRef } from '@backstage/core-plugin-api';
import { SignInPage } from '@backstage/core-components';
/* highlight-add-end */
const app = createApp({
apis,
+ components: {
+ SignInPage: props => (
+ <SignInPage
+ {...props}
+ auto
+ provider={{
+ id: 'github-auth-provider',
+ title: 'GitHub',
+ message: 'Sign in using GitHub',
+ apiRef: githubAuthApiRef,
+ }}
+ />
+ ),
+ },
bindRoutes({ bind }) {
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => (
<SignInPage
{...props}
auto
provider={{
id: 'github-auth-provider',
title: 'GitHub',
message: 'Sign in using GitHub',
apiRef: githubAuthApiRef,
}}
/>
),
},
/* highlight-add-end */
// ..
});
```
You can also use the `providers` prop to enable multiple sign-in methods, for example
allows allowing guest access:
```diff
const app = createApp({
apis,
+ components: {
+ SignInPage: props => (
+ <SignInPage
+ {...props}
+ providers={['guest', {
+ id: 'github-auth-provider',
+ title: 'GitHub',
+ message: 'Sign in using GitHub',
+ apiRef: githubAuthApiRef,
+ }]}
+ />
+ ),
+ },
bindRoutes({ bind }) {
```tsx title="packages/app/src/App.tsx"
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => (
<SignInPage
{...props}
providers={['guest', {
id: 'github-auth-provider',
title: 'GitHub',
message: 'Sign in using GitHub',
apiRef: githubAuthApiRef,
}]}
/>
),
},
/* highlight-add-end */
// ..
});
```
## Sign-In with Proxy Providers
@@ -142,12 +148,12 @@ All the sign-in page needs to do is to call the `/refresh` endpoint of the auth
to get the existing session, which is exactly what the `ProxiedSignInPage` does. The only
thing you need to do to configure the `ProxiedSignInPage` is to pass the ID of the provider like this:
```tsx
```tsx title="packages/app/src/App.tsx"
const app = createApp({
...,
components: {
SignInPage: props => <ProxiedSignInPage {...props} provider="awsalb" />,
},
// ..
});
```
@@ -159,6 +165,7 @@ Example:
<ProxiedSignInPage
{...props}
provider="my-custom-provider"
/* highlight-next-line */
headers={{ 'x-some-key': someValue }}
/>
```
@@ -169,10 +176,12 @@ Headers can also be returned in an async manner:
<ProxiedSignInPage
{...props}
provider="my-custom-provider"
/* highlight-start */
headers={async () => {
const someValue = await someFn();
return { 'x-some-key': someValue };
}}
/* highlight-end */
/>
```
@@ -184,9 +193,8 @@ select the sign-in method based on the `process.env.NODE_ENV` environment variab
by checking the `hostname` of the current location, or by accessing the configuration API
to read a configuration value. For example:
```tsx
```tsx title="packages/app/src/App.tsx"
const app = createApp({
...,
components: {
SignInPage: props => {
const configApi = useApi(configApiRef);
@@ -206,6 +214,7 @@ const app = createApp({
return <ProxiedSignInPage {...props} provider="gcpiap" />;
},
},
// ..
});
```
@@ -218,7 +227,7 @@ If you want to use the authentication capabilities of the [Repository Picker](..
To set it up, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The example below sets up the `ScmAuthApi` for an already configured GitLab authentication provider:
```ts
```ts title="packages/app/src/apis.ts"
createApiFactory({
api: scmAuthApiRef,
deps: {
@@ -294,23 +303,24 @@ If you require only a subset of these integrations, then you will need a custom
The first step is to remove the code that creates the default providers.
```diff
import {
ScmIntegrationsApi,
scmIntegrationsApiRef,
+ ScmAuth,
} from '@backstage/integration-react';
```ts title="packages/app/src/apis.ts"
import {
ScmIntegrationsApi,
scmIntegrationsApiRef,
/* highlight-add-next-line */
ScmAuth,
} from '@backstage/integration-react';
export const apis: AnyApiFactory[] = [
...
+ ScmAuth.createDefaultApiFactory(),
...
];
export const apis: AnyApiFactory[] = [
/* highlight-add-next-line */
ScmAuth.createDefaultApiFactory(),
// ...
];
```
Then replace it with something like this, which will create an `ApiFactory` with only a github provider.
```ts
```ts title="packages/app/src/apis.ts"
export const apis: AnyApiFactory[] = [
createApiFactory({
api: scmAuthApiRef,
docs/auth/microsoft/azure-easyauth.md
+11 -5
View File
@@ -60,12 +60,18 @@ sign-in mechanism to poll that endpoint through the IAP, on the user's behalf.
It is recommended to use the `ProxiedSignInPage` for this provider, which is
installed in `packages/app/src/App.tsx` like this:
```diff
+import { ProxiedSignInPage } from '@backstage/core-components';
```tsx title="packages/app/src/App.tsx"
/* highlight-add-next-line */
import { ProxiedSignInPage } from '@backstage/core-components';
const app = createApp({
components: {
+ SignInPage: props => <ProxiedSignInPage {...props} provider="azure-easyauth" />,
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => <ProxiedSignInPage {...props} provider="azure-easyauth" />,
},
/* highlight-add-end */
// ..
})
```
See the [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) section for more information.
docs/auth/oauth2-proxy/provider.md
+12 -6
View File
@@ -18,7 +18,7 @@ for more details check this
The provider configuration can be added to your `app-config.yaml` under the root
`auth` configuration:
```yaml
```yaml title="app-config.yaml"
auth:
providers:
oauth2Proxy: {}
@@ -63,12 +63,18 @@ providerFactories: {
It is recommended to use the `ProxiedSignInPage` for this provider, which is
installed in `packages/app/src/App.tsx` like this:
```diff
+import { ProxiedSignInPage } from '@backstage/core-components';
```tsx title="packages/app/src/App.tsx"
/* highlight-add-next-line */
import { ProxiedSignInPage } from '@backstage/core-components';
const app = createApp({
components: {
+ SignInPage: props => <ProxiedSignInPage {...props} provider="oauth2Proxy" />,
const app = createApp({
/* highlight-add-start */
components: {
SignInPage: props => <ProxiedSignInPage {...props} provider="oauth2Proxy" />,
},
/* highlight-add-end */
// ..
})
```
See [Sign-In with Proxy Providers](../index.md#sign-in-with-proxy-providers) for pointers on how to set up the sign-in page to also work smoothly for local development.
docs/auth/oidc.md
+61 -49
View File
@@ -77,34 +77,39 @@ the instance is cached by the DI library, a singleton.
Let's add our OIDC API factory to the APIs array in the `packages/app/src/apis.ts` file:
```diff
+ import { OAuth2 } from '@backstage/core-app-api';
```ts title="packages/app/src/apis.ts"
/* highlight-add-next-line */
import { OAuth2 } from '@backstage/core-app-api';
export const apis: AnyApiFactory[] = [
+ createApiFactory({
+ api: azureOIDCAuthApiRef,
+ deps: {
+ discoveryApi: discoveryApiRef,
+ oauthRequestApi: oauthRequestApiRef,
+ configApi: configApiRef,
+ },
+ factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
+ OAuth2.create({
+ discoveryApi,
+ oauthRequestApi,
+ provider: {
+ id: 'my-auth-provider',
+ title: 'My custom auth provider',
+ icon: () => null,
+ },
+ environment: configApi.getOptionalString('auth.environment'),
+ defaultScopes: [
+ 'openid',
+ 'profile',
+ 'email',
+ ],
+ }),
+ }),
/* highlight-add-start */
createApiFactory({
api: azureOIDCAuthApiRef,
deps: {
discoveryApi: discoveryApiRef,
oauthRequestApi: oauthRequestApiRef,
configApi: configApiRef,
},
factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
OAuth2.create({
discoveryApi,
oauthRequestApi,
provider: {
id: 'my-auth-provider',
title: 'My custom auth provider',
icon: () => null,
},
environment: configApi.getOptionalString('auth.environment'),
defaultScopes: [
'openid',
'profile',
'email',
],
}),
}),
/* highlight-add-end */
// ..
]
```
@@ -125,7 +130,7 @@ the ID you picked to represent the Auth provider, this ID has to match with the
callback URI provider segment (you'll have to configure your IDP to handle the callback
URI properly).
```diff
```ts
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
@@ -137,9 +142,11 @@ export default async function createPlugin(
tokenManager: env.tokenManager,
providerFactories: {
...defaultAuthProviderFactories,
+ 'my-auth-provider': providers.oidc.create({
+ }),
}
/* highlight-add-next-line */
'my-auth-provider': providers.oidc.create({}),
},
// ..
})
```
### The Resolver
@@ -154,10 +161,11 @@ adding a resolver for a SignIn request.
The OIDC provider doesn't provide any build-in resolvers, so we'll need to define our own:
```diff
```ts
import {
DEFAULT_NAMESPACE,
+ stringifyEntityRef,
/* highlight-add-next-line */
stringifyEntityRef,
} from '@backstage/catalog-model';
export default async function createPlugin(
@@ -172,23 +180,27 @@ export default async function createPlugin(
providerFactories: {
...defaultAuthProviderFactories,
'my-auth-provider': providers.oidc.create({
+ signIn: {
+ resolver(info, ctx) {
+ const userRef = stringifyEntityRef({
+ kind: 'User',
+ name: info.result.userinfo.sub,
+ namespace: DEFAULT_NAMESPACE,
+ });
+ return ctx.issueToken({
+ claims: {
+ sub: userRef, // The user's own identity
+ ent: [userRef], // A list of identities that the user claims ownership through
+ },
+ });
+ },
+ },
/* highlight-add-start */
signIn: {
resolver(info, ctx) {
const userRef = stringifyEntityRef({
kind: 'User',
name: info.result.userinfo.sub,
namespace: DEFAULT_NAMESPACE,
});
return ctx.issueToken({
claims: {
sub: userRef, // The user's own identity
ent: [userRef], // A list of identities that the user claims ownership through
},
});
},
},
/* highlight-add-end */
}),
}
},
// ..
})
```
### The configuration
@@ -206,7 +218,7 @@ Then we need to configure the env variables for the provider, based on the provi
in `plugins/auth-backend/src/providers/oidc/provider.ts` we need the following variables
in the `app-config.yaml`:
```yaml
```yaml title="app-config.yaml"
auth:
environment: development
### Providing an auth.session.secret will enable session support in the auth-backend
docs/auth/service-to-service-auth.md
+5 -3
View File
@@ -23,9 +23,11 @@ that incoming requests are not validated. If you want to enable
service-to-service auth, the first step is to switch out the following line in
your backend setup at `packages/backend/src/index.ts`:
```diff
- const tokenManager = ServerTokenManager.noop();
+ const tokenManager = ServerTokenManager.fromConfig(config, { logger: root });
```ts title="packages/backend/src/index.ts"
/* highlight-remove-next-line */
const tokenManager = ServerTokenManager.noop();
/* highlight-add-next-line */
const tokenManager = ServerTokenManager.fromConfig(config, { logger: root });
```
By switching from the no-op `ServiceTokenManager` to one created from config,