Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@backstage/plugin-auth-node

backstage1mApache-2.00.6.7TypeScript support: included

null

readme

headline

Backstage

English | 한국어 | 中文版 | Français

License CNCF Status Discord Code style Codecov OpenSSF Best Practices OpenSSF Scorecard

What is Backstage?

Backstage is an open source framework for building developer portals. Powered by a centralized software catalog, Backstage restores order to your microservices and infrastructure and enables your product teams to ship high-quality code quickly without compromising autonomy.

Backstage unifies all your infrastructure tooling, services, and documentation to create a streamlined development environment from end to end.

software-catalog

Out of the box, Backstage includes:

  • Backstage Software Catalog for managing all your software such as microservices, libraries, data pipelines, websites, and ML models
  • Backstage Software Templates for quickly spinning up new projects and standardizing your tooling with your organization’s best practices
  • Backstage TechDocs for making it easy to create, maintain, find, and use technical documentation, using a "docs like code" approach
  • Plus, a growing ecosystem of open source plugins that further expand Backstage’s customizability and functionality

Backstage was created by Spotify but is now hosted by the Cloud Native Computing Foundation (CNCF) as an Incubation level project. For more information, see the announcement.

Project roadmap

For information about the detailed project roadmap including delivered milestones, see the Roadmap.

Getting Started

To start using Backstage, see the Getting Started documentation.

Documentation

The documentation of Backstage includes:

Community

To engage with our community, you can use the following resources:

Governance

See the GOVERNANCE.md document in the backstage/community repository.

License

Copyright 2020-2025 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

Security

Please report sensitive security issues using Spotify's bug-bounty program rather than GitHub.

For further details, see our complete security release process.

changelog

@backstage/plugin-auth-node

0.6.7

Patch Changes

0.6.7-next.1

Patch Changes

0.6.7-next.0

Patch Changes

0.6.6

Patch Changes

0.6.6-next.0

Patch Changes

0.6.5

Patch Changes

0.6.5-next.0

Patch Changes

0.6.4

Patch Changes

0.6.4-next.1

Patch Changes

0.6.4-next.0

Patch Changes

0.6.3

Patch Changes

  • 332e934: Added the identity property to BackstageSignInResult.

    The prepareBackstageIdentityResponse function will now also forward the identity to the response if present in the provided sign-in result.

  • ab53e6f: Added a new dangerousEntityRefFallback option to the signInWithCatalogUser method in AuthResolverContext. The option will cause the provided entity reference to be used as a fallback in case the user is not found in the catalog. It is up to the caller to provide the fallback entity reference.

    Auth providers that include pre-defined sign-in resolvers are encouraged to define a flag named dangerouslyAllowSignInWithoutUserInCatalog in their config, which in turn enables use of the dangerousEntityRefFallback option. For example:

    export const usernameMatchingUserEntityName = createSignInResolverFactory({
  optionsSchema: z
    .object({
      dangerouslyAllowSignInWithoutUserInCatalog: z.boolean().optional(),
    })
    .optional(),
  create(options = {}) {
    return async (
      info: SignInInfo<OAuthAuthenticatorResult<PassportProfile>>,
      ctx,
    ) => {
      const { username } = info.result.fullProfile;
      if (!username) {
        throw new Error('User profile does not contain a username');
      }

      return ctx.signInWithCatalogUser(
        { entityRef: { name: username } },
        {
          dangerousEntityRefFallback:
            options?.dangerouslyAllowSignInWithoutUserInCatalog
              ? { entityRef: { name: username } }
              : undefined,
        },
      );
    };
  },
});

  • Updated dependencies

0.6.3-next.2

Patch Changes

  • ab53e6f: Added a new dangerousEntityRefFallback option to the signInWithCatalogUser method in AuthResolverContext. The option will cause the provided entity reference to be used as a fallback in case the user is not found in the catalog. It is up to the caller to provide the fallback entity reference.

    Auth providers that include pre-defined sign-in resolvers are encouraged to define a flag named dangerouslyAllowSignInWithoutUserInCatalog in their config, which in turn enables use of the dangerousEntityRefFallback option. For example:

    export const usernameMatchingUserEntityName = createSignInResolverFactory({
  optionsSchema: z
    .object({
      dangerouslyAllowSignInWithoutUserInCatalog: z.boolean().optional(),
    })
    .optional(),
  create(options = {}) {
    return async (
      info: SignInInfo<OAuthAuthenticatorResult<PassportProfile>>,
      ctx,
    ) => {
      const { username } = info.result.fullProfile;
      if (!username) {
        throw new Error('User profile does not contain a username');
      }

      return ctx.signInWithCatalogUser(
        { entityRef: { name: username } },
        {
          dangerousEntityRefFallback:
            options?.dangerouslyAllowSignInWithoutUserInCatalog
              ? { entityRef: { name: username } }
              : undefined,
        },
      );
    };
  },
});

  • Updated dependencies

0.6.3-next.1

Patch Changes

0.6.3-next.0

Patch Changes

0.6.2

Patch Changes

0.6.1

Patch Changes

0.6.1-next.1

Patch Changes

0.6.1-next.0

Patch Changes

0.6.0

Minor Changes

  • 61f464e: Added auth.providers.<providerId>.sessionDuration config for auth providers to allow the lifespan of user sessions to be configured.

Patch Changes

0.6.0-next.2

Patch Changes

0.6.0-next.1

Minor Changes

  • 61f464e: Added auth.providers.<providerId>.sessionDuration config for auth providers to allow the lifespan of user sessions to be configured.

Patch Changes

0.5.7-next.0

Patch Changes

0.5.6

Patch Changes

0.5.6-next.1

Patch Changes

0.5.6-next.0

Patch Changes

0.5.5

Patch Changes

0.5.5-next.2

Patch Changes

0.5.5-next.1

Patch Changes

0.5.5-next.0

Patch Changes

0.5.4

Patch Changes

0.5.4-next.2

Patch Changes

0.5.4-next.1

Patch Changes

0.5.4-next.0

Patch Changes

0.5.3

Patch Changes

0.5.3-next.1

Patch Changes

0.5.3-next.0

Patch Changes

0.5.2

Patch Changes

0.5.2-next.2

Patch Changes

0.5.2-next.1

Patch Changes

0.5.2-next.0

Patch Changes

0.5.0

Minor Changes

  • 579afd0: BREAKING: Sign-in resolvers configured via .signIn.resolvers now take precedence over sign-in resolvers passed to signInResolver option of createOAuthProviderFactory. This effectively makes sign-in resolvers passed via the signInResolver the default one, which you can then override through configuration.

Patch Changes

0.5.0-next.3

Patch Changes

0.5.0-next.2

Minor Changes

  • 579afd0: BREAKING: Sign-in resolvers configured via .signIn.resolvers now take precedence over sign-in resolvers passed to signInResolver option of createOAuthProviderFactory. This effectively makes sign-in resolvers passed via the signInResolver the default one, which you can then override through configuration.

Patch Changes

0.4.18-next.1

Patch Changes

0.4.18-next.0

Patch Changes

0.4.17

Patch Changes

0.4.17-next.1

Patch Changes

0.4.16-next.0

Patch Changes

0.4.14

Patch Changes

  • 798ec37: Updated scope management for OAuth providers, where the createOAuthAuthenticator now accepts a new collection of scopes options:

    • scopes.persist - Whether scopes should be persisted, replaces the shouldPersistScopes option.
    • scopes.required - A list of required scopes that will always be requested.
    • scopes.transform - A function that can be used to transform the scopes before they are requested.

    The createOAuthProviderFactory has also received a new additionalScopes option, and will also read additionalScopes from the auth provider configuration. Both of these can be used to add additional scopes that should always be requested.

    A significant change under the hood that this new scope management brings is that providers that persist scopes will now always merge the already granted scopes with the requested ones. The previous behavior was that the full authorization flow would not include existing scopes, while the refresh flow would only include the existing scopes.

  • d44a20a: Added additional plugin metadata to package.json.

  • Updated dependencies

0.4.14-next.3

Patch Changes

  • 798ec37: Updated scope management for OAuth providers, where the createOAuthAuthenticator now accepts a new collection of scopes options:

    • scopes.persist - Whether scopes should be persisted, replaces the shouldPersistScopes option.
    • scopes.required - A list of required scopes that will always be requested.
    • scopes.transform - A function that can be used to transform the scopes before they are requested.

    The createOAuthProviderFactory has also received a new additionalScopes option, and will also read additionalScopes from the auth provider configuration. Both of these can be used to add additional scopes that should always be requested.

    A significant change under the hood that this new scope management brings is that providers that persist scopes will now always merge the already granted scopes with the requested ones. The previous behavior was that the full authorization flow would not include existing scopes, while the refresh flow would only include the existing scopes.

  • d44a20a: Added additional plugin metadata to package.json.

  • Updated dependencies

0.4.14-next.2

Patch Changes

0.4.14-next.1

Patch Changes

0.4.14-next.0

Patch Changes

0.4.13

Patch Changes

0.4.13-next.1

Patch Changes

0.4.13-next.0

Patch Changes

0.4.12

Patch Changes

0.4.12-next.1

Patch Changes

0.4.12-next.0

Patch Changes

0.4.11

Patch Changes

0.4.10

Patch Changes

0.4.9

Patch Changes

0.4.9-next.2

Patch Changes

0.4.9-next.1

Patch Changes

0.4.8-next.0

Patch Changes

0.4.4

Patch Changes

0.4.4-next.3

Patch Changes

0.4.4-next.2

Patch Changes

0.4.4-next.1

Patch Changes

0.4.4-next.0

Patch Changes

0.4.3

Patch Changes

0.4.3-next.2

Patch Changes

0.4.3-next.1

Patch Changes

0.4.3-next.0

Patch Changes

0.4.2

Patch Changes

0.4.2-next.3

Patch Changes

0.4.2-next.2

Patch Changes

0.4.2-next.1

Patch Changes

0.4.2-next.0

Patch Changes

0.4.1

Patch Changes

0.4.1-next.2

Patch Changes

0.4.1-next.1

Patch Changes

0.4.1-next.0

Patch Changes

0.4.0

Minor Changes

  • 6f142d5356: BREAKING: The recently introduced ProxyAuthenticator.initialize() method is no longer async to match the way the OAuth equivalent is implemented.

Patch Changes

0.4.0-next.2

Minor Changes

  • 6f142d5356: BREAKING: The recently introduced ProxyAuthenticator.initialize() method is no longer async to match the way the OAuth equivalent is implemented.

Patch Changes

0.3.2-next.1

Patch Changes

0.3.2-next.0

Patch Changes

0.3.0

Minor Changes

  • 8513cd7d00e3: Introduced a new system for building auth providers for @backstage/plugin-auth-backend, which both increases the amount of code re-use across providers, and also works better with the new backend system.

    Many existing types have been moved from @backstage/plugin-auth-backend in order to avoid a direct dependency on the plugin from modules.

    Auth provider integrations are now primarily implemented through a pattern of creating "authenticators", which are in turn specific to each kind of integrations. Initially there are two types: createOAuthAuthenticator and createProxyAuthenticator. These come paired with functions that let you create the corresponding route handlers, createOAuthRouteHandlers and createProxyAuthRouteHandlers, as well as provider factories, createOAuthProviderFactory and createProxyAuthProviderFactory. This new authenticator pattern allows the sign-in logic to be separated from the auth integration logic, allowing it to be completely re-used across all providers of the same kind.

    The new provider factories also implement a new declarative way to configure sign-in resolvers, rather than configuration through code. Sign-in resolvers can now be configured through the resolvers configuration key, where the first resolver that provides an identity will be used, for example:

    auth:
  providers:
    google:
      development:
        clientId: ...
        clientSecret: ...
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityAnnotation
            - resolver: emailLocalPartMatchingUserEntityName

    These configurable resolvers are created with a new createSignInResolverFactory function, which creates a sign-in resolver factory, optionally with an options schema that will be used both when configuring the sign-in resolver through configuration and code.

    The internal helpers from @backstage/plugin-auth-backend that were used to implement auth providers using passport strategies have now also been made available as public API, through PassportHelpers and PassportOAuthAuthenticatorHelper.

Patch Changes

0.3.0-next.3

Patch Changes

0.3.0-next.2

Patch Changes

0.3.0-next.1

Patch Changes

0.3.0-next.0

Minor Changes

  • 8513cd7d00e3: Introduced a new system for building auth providers for @backstage/plugin-auth-backend, which both increases the amount of code re-use across providers, and also works better with the new backend system.

    Many existing types have been moved from @backstage/plugin-auth-backend in order to avoid a direct dependency on the plugin from modules.

    Auth provider integrations are now primarily implemented through a pattern of creating "authenticators", which are in turn specific to each kind of integrations. Initially there are two types: createOAuthAuthenticator and createProxyAuthenticator. These come paired with functions that let you create the corresponding route handlers, createOAuthRouteHandlers and createProxyAuthRouteHandlers, as well as provider factories, createOAuthProviderFactory and createProxyAuthProviderFactory. This new authenticator pattern allows the sign-in logic to be separated from the auth integration logic, allowing it to be completely re-used across all providers of the same kind.

    The new provider factories also implement a new declarative way to configure sign-in resolvers, rather than configuration through code. Sign-in resolvers can now be configured through the resolvers configuration key, where the first resolver that provides an identity will be used, for example:

    auth:
  providers:
    google:
      development:
        clientId: ...
        clientSecret: ...
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityAnnotation
            - resolver: emailLocalPartMatchingUserEntityName

    These configurable resolvers are created with a new createSignInResolverFactory function, which creates a sign-in resolver factory, optionally with an options schema that will be used both when configuring the sign-in resolver through configuration and code.

    The internal helpers from @backstage/plugin-auth-backend that were used to implement auth providers using passport strategies have now also been made available as public API, through PassportHelpers and PassportOAuthAuthenticatorHelper.

Patch Changes

0.2.17

Patch Changes

0.2.17-next.2

Patch Changes

0.2.17-next.1

Patch Changes

0.2.17-next.0

Patch Changes

0.2.16

Patch Changes

0.2.16-next.0

Patch Changes

0.2.15

Patch Changes

0.2.15-next.2

Patch Changes

0.2.15-next.1

Patch Changes

0.2.15-next.0

Patch Changes

0.2.14

Patch Changes

0.2.14-next.1

Patch Changes

0.2.14-next.0

Patch Changes

0.2.13

Patch Changes

0.2.13-next.2

Patch Changes

0.2.13-next.1

Patch Changes

0.2.13-next.0

Patch Changes

0.2.12

Patch Changes

0.2.12-next.2

Patch Changes

0.2.12-next.1

Patch Changes

0.2.12-next.0

Patch Changes

0.2.11

Patch Changes

0.2.11-next.2

Patch Changes

0.2.11-next.1

Patch Changes

0.2.11-next.0

Patch Changes

0.2.9

Patch Changes

0.2.9-next.1

Patch Changes

0.2.9-next.0

Patch Changes

0.2.8

Patch Changes

0.2.8-next.3

Patch Changes

0.2.8-next.2

Patch Changes

0.2.8-next.1

Patch Changes

0.2.8-next.0

Patch Changes

0.2.7

Patch Changes

0.2.7-next.1

Patch Changes

0.2.7-next.0

Patch Changes

0.2.6

Patch Changes

0.2.6-next.2

Patch Changes

0.2.6-next.1

Patch Changes

0.2.6-next.0

Patch Changes

0.2.5

Patch Changes

  • 9212439d15: Minor update to tests
  • 2cbd533426: IdentityClient is now deprecated. Please migrate to IdentityApi and DefaultIdentityClient instead. The authenticate function on DefaultIdentityClient is also deprecated. Please use getIdentity instead.
  • 667d917488: Updated dependency msw to ^0.47.0.
  • 87ec2ba4d6: Updated dependency msw to ^0.46.0.
  • bf5e9030eb: Updated dependency msw to ^0.45.0.
  • Updated dependencies

0.2.5-next.3

Patch Changes

0.2.5-next.2

Patch Changes

  • 2cbd533426: IdentityClient is now deprecated. Please migrate to IdentityApi and DefaultIdentityClient instead. The authenticate function on DefaultIdentityClient is also deprecated. Please use getIdentity instead.
  • 667d917488: Updated dependency msw to ^0.47.0.
  • 87ec2ba4d6: Updated dependency msw to ^0.46.0.
  • Updated dependencies

0.2.5-next.1

Patch Changes

0.2.5-next.0

Patch Changes

0.2.4

Patch Changes

0.2.4-next.0

Patch Changes

0.2.3

Patch Changes

0.2.3-next.2

Patch Changes

0.2.3-next.1

Patch Changes

0.2.3-next.0

Patch Changes

0.2.2

Patch Changes

  • 5ca0b86b88: Address corner cases where the key store was not being created at startup
  • 8f7b1835df: Updated dependency msw to ^0.41.0.
  • 9079a78078: Added configurable algorithms array for IdentityClient
  • Updated dependencies

0.2.2-next.2

Patch Changes

0.2.2-next.1

Patch Changes

0.2.2-next.0

Patch Changes

0.2.1

Patch Changes

0.2.1-next.1

Patch Changes

0.2.1-next.0

Patch Changes

0.2.0

Minor Changes

  • 15d3a3c39a: BREAKING: Removed the deprecated id and entity fields from BackstageSignInResult.

Patch Changes

0.2.0-next.0

Minor Changes

  • 15d3a3c39a: BREAKING: Removed the deprecated id and entity fields from BackstageSignInResult.

Patch Changes

0.1.6

Patch Changes

0.1.5

Patch Changes

0.1.5-next.0

Patch Changes

0.1.4

Patch Changes

0.1.3

Patch Changes

0.1.2

Patch Changes

0.1.1

Patch Changes

0.1.0

Minor Changes

  • 9058bb1b5e: Added this package, to hold shared types and functionality that other backend packages need to import.

Patch Changes