diff --git a/.changeset/nice-seahorses-look.md b/.changeset/nice-seahorses-look.md new file mode 100644 index 0000000000..9652898c54 --- /dev/null +++ b/.changeset/nice-seahorses-look.md @@ -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. diff --git a/docs/api/deprecations.md b/docs/api/deprecations.md index aca7e42d96..04c3da92bc 100644 --- a/docs/api/deprecations.md +++ b/docs/api/deprecations.md @@ -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 + + } + /> + } +/> +``` diff --git a/packages/core-plugin-api/api-report.md b/packages/core-plugin-api/api-report.md index d0ac0b5352..ce9d226331 100644 --- a/packages/core-plugin-api/api-report.md +++ b/packages/core-plugin-api/api-report.md @@ -194,7 +194,7 @@ export type AppThemeApi = { // @public export const appThemeApiRef: ApiRef; -// @public +// @alpha export const atlassianAuthApiRef: ApiRef< OAuthApi & ProfileInfoApi & BackstageIdentityApi & SessionApi >; @@ -206,7 +206,7 @@ export function attachComponentData

( 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( 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 = Observable_2; // @public @deprecated export type Observer = Observer_2; -// @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; -// @public +// @alpha export const oneloginAuthApiRef: ApiRef< OAuthApi & OpenIdConnectApi & @@ -738,7 +738,7 @@ export type RouteRef = { title?: string; }; -// @public +// @public @deprecated export const samlAuthApiRef: ApiRef< ProfileInfoApi & BackstageIdentityApi & SessionApi >; diff --git a/packages/core-plugin-api/src/apis/definitions/auth.ts b/packages/core-plugin-api/src/apis/definitions/auth.ts index 37308ec29b..8b799b2dd6 100644 --- a/packages/core-plugin-api/src/apis/definitions/auth.ts +++ b/packages/core-plugin-api/src/apis/definitions/auth.ts @@ -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