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

core-plugin-api: deprecated some auth api refs and marked the rest as experimental

Browse Source 
Co-authored-by: Johan Haals <johan.haals@gmail.com>
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2021-12-13 11:49:08 +01:00
parent a3ec122170
commit 8a7372cfd5
4 changed files with 156 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/nice-seahorses-look.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/core-plugin-api': patch
---
Deprecated `auth0AuthApiRef`, `oauth2ApiRef`, `oidcAuthApiRef`, `samlAuthApiRef`, and marked the rest of the auth `ApiRef`s as experimental. For more information on how to address the deprecations, see https://backstage.io/docs/api/deprecations#generic-auth-api-refs.
docs/api/deprecations.md
+122
View File
@@ -61,3 +61,125 @@ breaking change to make `theme` optional. This means that if you currently
construct the themes that you pass on to `createApp` using `AppTheme` as an
intermediate type, you will need to work around this in some way, for example by
passing the themes to `createApp` more directly.
### Generic Auth API Refs
`Released 2021-12-16 in @backstage/core-plugin-api v0.3.1`
There are four auth Utility API references in `@backstage/core-plugin-api` that
were too generic to be useful. The APIs in question are `auth0AuthApiRef`,
`oauth2ApiRef`, `oidcAuthApiRef`, and `samlAuthApiRef`. The issue with these
APIs was that they had no actual contract of what the backing auth provider was.
This made it more or less impossible to use these providers in open source
plugins in any meaningful way. We also did not want to keep these Utility API
references around just as helpers either, instead opting to remove them and let
integrators define their own APIs that are more specific to their auth provider.
This is also falls in line with a long-term goal to unify all auth providers to
not have separate frontend implementations.
If you're currently using one of these API references for either Sign-In or
access delegation within an app, there are a couple of steps you need to take to
migrate to your own custom API.
First, you'll need to define a new Utility API reference. If you're only using
the API for sign-in, you can put the definition in `packages/app/src/apis.ts`.
However, if you need to access your auth API inside plugins you you'll need to
export it from a common package. If you don't already have one we recommended
creating `@internal/apis` and from there export the API reference.
```ts
// `ProfileInfoApi & BackstageIdentityApi & SessionApi` are required for sign-in
// Include `OAuthApi & OpenIdConnectApi` only if applicable
export const acmeAuthApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
ProfileInfoApi &
BackstageIdentityApi &
SessionApi
> = createApiRef({
id: 'internal.auth.acme',
});
```
Next you'll want to wire up the API inside `packages/app/src/apis.ts`, which
varies depending on which API you're replacing. If you for example are replacing
the `oauth2ApiRef`, the factory might look like this:
```ts
// oauth2
createApiFactory({
api: acmeAuthApiRef,
deps: {
discoveryApi: discoveryApiRef,
oauthRequestApi: oauthRequestApiRef,
configApi: configApiRef,
},
factory: ({ discoveryApi, oauthRequestApi, configApi }) =>
OAuth2.create({
discoveryApi,
oauthRequestApi,
environment: configApi.getOptionalString('auth.environment'),
}),
});
```
Provider specific factory implementations, copy the code you need into the
factory method depending on which apiRef you previously used.
```ts
// samlAuthApiRef
SamlAuth.create({
discoveryApi,
environment: configApi.getOptionalString('auth.environment'),
});
// oidcAuthApiRef
OAuth2.create({
discoveryApi,
oauthRequestApi,
provider: {
id: 'oidc',
title: 'Your Identity Provider',
icon: () => null,
},
environment: configApi.getOptionalString('auth.environment'),
});
// auth0AuthApiRef
OAuth2.create({
discoveryApi,
oauthRequestApi,
provider: {
id: 'auth0',
title: 'Auth0',
icon: () => null,
},
defaultScopes: ['openid', 'email', 'profile'],
environment: configApi.getOptionalString('auth.environment'),
});
```
Finally, for the provider to show up in your settings menu, you also need to
update the settings route in `packages/app/src/App.tsx` to pass the
`acmeAuthApiRef` to the `UserSettingsPage`. This replaces all existing provider
items, so you might want to add back any of the default ones that you are using
from the
[DefaultProviderSettings](https://github.com/backstage/backstage/blob/a3ec122170e0205fd3f9c307b98b1c5e4f55bf5f/plugins/user-settings/src/components/AuthProviders/DefaultProviderSettings.tsx#L35).
```tsx
<Route
path="/settings"
element={
<UserSettingsPage
providerSettings={
<ProviderSettingsItem
title="ACME"
description="Provides sign-in via ACME"
apiRef={acmeAuthApiRef}
icon={Star}
/>
}
/>
}
/>
```
packages/core-plugin-api/api-report.md
+12 -12
View File
@@ -194,7 +194,7 @@ export type AppThemeApi = {
// @public
export const appThemeApiRef: ApiRef<AppThemeApi>;
// @public
// @alpha
export const atlassianAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
>;
@@ -206,7 +206,7 @@ export function attachComponentData<P>(
data: unknown,
): void;
// @public
// @public @deprecated
export const auth0AuthApiRef: ApiRef<
OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
>;
@@ -272,7 +272,7 @@ export type BackstageUserIdentity = {
ownershipEntityRefs: string[];
};
// @public
// @alpha
export const bitbucketAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
>;
@@ -512,17 +512,17 @@ export function getComponentData<T>(
type: string,
): T | undefined;
// @public
// @alpha
export const githubAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
>;
// @public
// @alpha
export const gitlabAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
>;
// @public
// @alpha
export const googleAuthApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
@@ -570,7 +570,7 @@ export type MergeParams<
P2 extends AnyParams,
> = (P1[keyof P1] extends never ? {} : P1) & (P2 extends undefined ? {} : P2);
// @public
// @alpha
export const microsoftAuthApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
@@ -579,7 +579,7 @@ export const microsoftAuthApiRef: ApiRef<
SessionApi
>;
// @public
// @public @deprecated
export const oauth2ApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
@@ -616,7 +616,7 @@ export type Observable<T> = Observable_2<T>;
// @public @deprecated
export type Observer<T> = Observer_2<T>;
// @public
// @public @deprecated
export const oidcAuthApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
@@ -625,7 +625,7 @@ export const oidcAuthApiRef: ApiRef<
SessionApi
>;
// @public
// @alpha
export const oktaAuthApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
@@ -637,7 +637,7 @@ export const oktaAuthApiRef: ApiRef<
// @public
export type OldIconComponent = ComponentType<SvgIconProps>;
// @public
// @alpha
export const oneloginAuthApiRef: ApiRef<
OAuthApi &
OpenIdConnectApi &
@@ -738,7 +738,7 @@ export type RouteRef<Params extends AnyParams = any> = {
title?: string;
};
// @public
// @public @deprecated
export const samlAuthApiRef: ApiRef<
ProfileInfoApi & BackstageIdentityApi & SessionApi
>;
packages/core-plugin-api/src/apis/definitions/auth.ts
+17 -15
View File
@@ -282,14 +282,14 @@ export type SessionApi = {
/**
* Provides authentication towards Google APIs and identities.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
*
* @remarks
*
* See {@link https://developers.google.com/identity/protocols/googlescopes} for a full list of supported scopes.
*
* Note that the ID token payload is only guaranteed to contain the user's numerical Google ID,
* email and expiration information. Do not rely on any other fields, as they might not be present.
*
* @public
*/
export const googleAuthApiRef: ApiRef<
OAuthApi &
@@ -304,12 +304,12 @@ export const googleAuthApiRef: ApiRef<
/**
* Provides authentication towards GitHub APIs.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
*
* @remarks
*
* See {@link https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/}
* for a full list of supported scopes.
*
* @public
*/
export const githubAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
@@ -320,12 +320,12 @@ export const githubAuthApiRef: ApiRef<
/**
* Provides authentication towards Okta APIs.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
*
* @remarks
*
* See {@link https://developer.okta.com/docs/guides/implement-oauth-for-okta/scopes/}
* for a full list of supported scopes.
*
* @public
*/
export const oktaAuthApiRef: ApiRef<
OAuthApi &
@@ -340,12 +340,12 @@ export const oktaAuthApiRef: ApiRef<
/**
* Provides authentication towards GitLab APIs.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
*
* @remarks
*
* See {@link https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#limiting-scopes-of-a-personal-access-token}
* for a full list of supported scopes.
*
* @public
*/
export const gitlabAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
@@ -362,6 +362,7 @@ export const gitlabAuthApiRef: ApiRef<
* for a full list of supported scopes.
*
* @public
* @deprecated See https://backstage.io/docs/api/deprecations#generic-auth-api-refs
*/
export const auth0AuthApiRef: ApiRef<
OpenIdConnectApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
@@ -372,13 +373,13 @@ export const auth0AuthApiRef: ApiRef<
/**
* Provides authentication towards Microsoft APIs and identities.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
*
* @remarks
*
* For more info and a full list of supported scopes, see:
* - {@link https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent}
* - {@link https://docs.microsoft.com/en-us/graph/permissions-reference}
*
* @public
*/
export const microsoftAuthApiRef: ApiRef<
OAuthApi &
@@ -394,6 +395,7 @@ export const microsoftAuthApiRef: ApiRef<
* Provides authentication for custom identity providers.
*
* @public
* @deprecated See https://backstage.io/docs/api/deprecations#generic-auth-api-refs
*/
export const oauth2ApiRef: ApiRef<
OAuthApi &
@@ -409,6 +411,7 @@ export const oauth2ApiRef: ApiRef<
* Provides authentication for custom OpenID Connect identity providers.
*
* @public
* @deprecated See https://backstage.io/docs/api/deprecations#generic-auth-api-refs
*/
export const oidcAuthApiRef: ApiRef<
OAuthApi &
@@ -424,6 +427,7 @@ export const oidcAuthApiRef: ApiRef<
* Provides authentication for SAML-based identity providers.
*
* @public
* @deprecated See https://backstage.io/docs/api/deprecations#generic-auth-api-refs
*/
export const samlAuthApiRef: ApiRef<
ProfileInfoApi & BackstageIdentityApi & SessionApi
@@ -434,7 +438,7 @@ export const samlAuthApiRef: ApiRef<
/**
* Provides authentication towards OneLogin APIs.
*
* @public
* @alpha This API is **EXPERIMENTAL** and might change in the future.
*/
export const oneloginAuthApiRef: ApiRef<
OAuthApi &
@@ -449,12 +453,11 @@ export const oneloginAuthApiRef: ApiRef<
/**
* Provides authentication towards Bitbucket APIs.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
* @remarks
*
* See {@link https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/}
* for a full list of supported scopes.
*
* @public
*/
export const bitbucketAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi
@@ -465,12 +468,11 @@ export const bitbucketAuthApiRef: ApiRef<
/**
* Provides authentication towards Atlassian APIs.
*
* @alpha This API is **EXPERIMENTAL** and might change in the future.
* @remarks
*
* See {@link https://developer.atlassian.com/cloud/jira/platform/scopes-for-connect-and-oauth-2-3LO-apps/}
* for a full list of supported scopes.
*
* @public
*/
export const atlassianAuthApiRef: ApiRef<
OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi