@backstage/plugin-auth-backend 0.4.10 → 0.6.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 /// <reference types="node" />
 import express from 'express';
 import { Logger } from 'winston';
+import { Config } from '@backstage/config';
 import { PluginEndpointDiscovery, PluginDatabaseManager } from '@backstage/backend-common';
 import { CatalogApi } from '@backstage/catalog-client';
 import { UserEntity, Entity } from '@backstage/catalog-model';
-import { Config } from '@backstage/config';
 import { Profile } from 'passport';
 import { JSONWebKey } from 'jose';
 import { TokenSet, UserinfoResponse } from 'openid-client';
@@ -70,7 +70,16 @@ declare type OAuthResult = {
     accessToken: string;
     refreshToken?: string;
 };
-declare type OAuthResponse = AuthResponse<OAuthProviderInfo>;
+/**
+ * The expected response from an OAuth flow.
+ *
+ * @public
+ */
+declare type OAuthResponse = {
+    profile: ProfileInfo;
+    providerInfo: OAuthProviderInfo;
+    backstageIdentity?: BackstageSignInResult;
+};
 declare type OAuthProviderInfo = {
     /**
      * An access token issued for the signed in user.
@@ -88,10 +97,6 @@ declare type OAuthProviderInfo = {
      * Scopes granted for the access token.
      */
     scope: string;
-    /**
-     * A refresh token issued for the signed in user
-     */
-    refreshToken?: string;
 };
 declare type OAuthState = {
     nonce: string;
@@ -123,7 +128,7 @@ interface OAuthHandlers {
      * @param {express.Request} req
      */
     handler(req: express.Request): Promise<{
-        response: AuthResponse<OAuthProviderInfo>;
+        response: OAuthResponse;
         refreshToken?: string;
     }>;
     /**
@@ -131,7 +136,10 @@ interface OAuthHandlers {
      * @param {string} refreshToken
      * @param {string} scope
      */
-    refresh?(req: OAuthRefreshRequest): Promise<AuthResponse<OAuthProviderInfo>>;
+    refresh?(req: OAuthRefreshRequest): Promise<{
+        response: OAuthResponse;
+        refreshToken?: string;
+    }>;
     /**
      * (Optional) Sign out of the auth provider.
      */
@@ -158,7 +166,7 @@ declare class IdentityClient {
      * Returns a BackstageIdentity (user) matching the token.
      * The method throws an error if verification fails.
      */
-    authenticate(token: string | undefined): Promise<BackstageIdentity>;
+    authenticate(token: string | undefined): Promise<BackstageIdentityResponse>;
     /**
      * Parses the given authorization header and returns
      * the bearer token, or null if no bearer token is given
@@ -211,7 +219,7 @@ declare class CatalogIdentityClient {
      *
      * Returns a superset of the entity names that can be passed directly to `issueToken` as `ent`.
      */
-    resolveCatalogMembership({ entityRefs, logger, }: MemberClaimQuery): Promise<string[]>;
+    resolveCatalogMembership(query: MemberClaimQuery): Promise<string[]>;
 }
 
 declare function getEntityClaims(entity: UserEntity): TokenParams['claims'];
@@ -317,37 +325,83 @@ declare type AuthProviderFactory = (options: AuthProviderFactoryOptions) => Auth
 declare type AuthResponse<ProviderInfo> = {
     providerInfo: ProviderInfo;
     profile: ProfileInfo;
-    backstageIdentity?: BackstageIdentity;
+    backstageIdentity?: BackstageIdentityResponse;
 };
-declare type BackstageIdentity = {
+/**
+ * User identity information within Backstage.
+ *
+ * @public
+ */
+declare type BackstageUserIdentity = {
     /**
-     * An opaque ID that uniquely identifies the user within Backstage.
-     *
-     * This is typically the same as the user entity `metadata.name`.
+     * The type of identity that this structure represents. In the frontend app
+     * this will currently always be 'user'.
      */
-    id: string;
+    type: 'user';
     /**
-     * This is deprecated, use `token` instead.
-     * @deprecated
+     * The entityRef of the user in the catalog.
+     * For example User:default/sandra
      */
-    idToken?: string;
+    userEntityRef: string;
     /**
-     * The token used to authenticate the user within Backstage.
+     * The user and group entities that the user claims ownership through
      */
-    token?: string;
+    ownershipEntityRefs: string[];
+};
+/**
+ * A representation of a successful Backstage sign-in.
+ *
+ * Compared to the {@link BackstageIdentityResponse} this type omits
+ * the decoded identity information embedded in the token.
+ *
+ * @public
+ */
+interface BackstageSignInResult {
+    /**
+     * An opaque ID that uniquely identifies the user within Backstage.
+     *
+     * This is typically the same as the user entity `metadata.name`.
+     *
+     * @deprecated Use the `identity` field instead
+     */
+    id: string;
     /**
      * The entity that the user is represented by within Backstage.
      *
      * This entity may or may not exist within the Catalog, and it can be used
      * to read and store additional metadata about the user.
+     *
+     * @deprecated Use the `identity` field instead.
      */
     entity?: Entity;
-};
+    /**
+     * The token used to authenticate the user within Backstage.
+     */
+    token: string;
+}
+/**
+ * The old exported symbol for {@link BackstageSignInResult}.
+ * @public
+ * @deprecated Use the `BackstageSignInResult` type instead.
+ */
+declare type BackstageIdentity = BackstageSignInResult;
+/**
+ * Response object containing the {@link BackstageUserIdentity} and the token from the authentication provider.
+ * @public
+ */
+interface BackstageIdentityResponse extends BackstageSignInResult {
+    /**
+     * A plaintext description of the identity that is encapsulated within the token.
+     */
+    identity: BackstageUserIdentity;
+}
 /**
  * Used to display login information to user, i.e. sidebar popup.
  *
  * It is also temporarily used as the profile of the signed-in user's Backstage
  * identity, but we want to replace that with data from identity and/org catalog service
+ *
+ * @public
  */
 declare type ProfileInfo = {
     /**
@@ -364,6 +418,10 @@ declare type ProfileInfo = {
      */
     picture?: string;
 };
+/**
+ * type of sign in information context, includes the profile information and authentication result which contains auth. related information
+ * @public
+ */
 declare type SignInInfo<AuthResult> = {
     /**
      * The simple profile passed down for use in the frontend.
@@ -374,11 +432,20 @@ declare type SignInInfo<AuthResult> = {
      */
     result: AuthResult;
 };
+/**
+ * Sign in resolver type describes the function which handles the result of a successful authentication
+ * and it must return a valid {@link BackstageSignInResult}
+ * @public
+ */
 declare type SignInResolver<AuthResult> = (info: SignInInfo<AuthResult>, context: {
     tokenIssuer: TokenIssuer;
     catalogIdentityClient: CatalogIdentityClient;
     logger: Logger;
-}) => Promise<BackstageIdentity>;
+}) => Promise<BackstageSignInResult>;
+/**
+ * The return type of authentication handler which must contain a valid profile information
+ * @public
+ */
 declare type AuthHandlerResult = {
     profile: ProfileInfo;
 };
@@ -389,6 +456,8 @@ declare type AuthHandlerResult = {
  *
  * Throwing an error in the function will cause the authentication to fail, making it
  * possible to use this function as a way to limit access to a certain group of users.
+ *
+ * @public
  */
 declare type AuthHandler<AuthResult> = (input: AuthResult) => Promise<AuthHandlerResult>;
 declare type StateEncoder = (req: OAuthStartRequest) => Promise<{
@@ -443,6 +512,134 @@ declare const readState: (stateString: string) => OAuthState;
 declare const encodeState: (state: OAuthState) => string;
 declare const verifyNonce: (req: express.Request, providerId: string) => void;
 
+declare type AtlassianAuthProviderOptions = OAuthProviderOptions & {
+    scopes: string;
+    signInResolver?: SignInResolver<OAuthResult>;
+    authHandler: AuthHandler<OAuthResult>;
+    tokenIssuer: TokenIssuer;
+    catalogIdentityClient: CatalogIdentityClient;
+    logger: Logger;
+};
+declare class AtlassianAuthProvider implements OAuthHandlers {
+    private readonly _strategy;
+    private readonly signInResolver?;
+    private readonly authHandler;
+    private readonly tokenIssuer;
+    private readonly catalogIdentityClient;
+    private readonly logger;
+    constructor(options: AtlassianAuthProviderOptions);
+    start(req: OAuthStartRequest): Promise<RedirectInfo>;
+    handler(req: express.Request): Promise<{
+        response: OAuthResponse;
+        refreshToken: string | undefined;
+    }>;
+    private handleResult;
+    refresh(req: OAuthRefreshRequest): Promise<{
+        response: OAuthResponse;
+        refreshToken: string | undefined;
+    }>;
+}
+declare type AtlassianProviderOptions = {
+    /**
+     * The profile transformation function used to verify and convert the auth response
+     * into the profile that will be presented to the user.
+     */
+    authHandler?: AuthHandler<OAuthResult>;
+    /**
+     * Configure sign-in for this provider, without it the provider can not be used to sign users in.
+     */
+    signIn?: {
+        resolver: SignInResolver<OAuthResult>;
+    };
+};
+declare const createAtlassianProvider: (options?: AtlassianProviderOptions | undefined) => AuthProviderFactory;
+
+/** @public */
+declare type Auth0ProviderOptions = {
+    /**
+     * The profile transformation function used to verify and convert the auth response
+     * into the profile that will be presented to the user.
+     */
+    authHandler?: AuthHandler<OAuthResult>;
+    /**
+     * Configure sign-in for this provider, without it the provider can not be used to sign users in.
+     */
+    signIn?: {
+        /**
+         * Maps an auth result to a Backstage identity for the user.
+         */
+        resolver: SignInResolver<OAuthResult>;
+    };
+};
+/** @public */
+declare const createAuth0Provider: (options?: Auth0ProviderOptions | undefined) => AuthProviderFactory;
+
+declare type AwsAlbResult = {
+    fullProfile: Profile;
+    expiresInSeconds?: number;
+    accessToken: string;
+};
+declare type AwsAlbProviderOptions = {
+    /**
+     * The profile transformation function used to verify and convert the auth response
+     * into the profile that will be presented to the user.
+     */
+    authHandler?: AuthHandler<AwsAlbResult>;
+    /**
+     * Configure sign-in for this provider, without it the provider can not be used to sign users in.
+     */
+    signIn: {
+        /**
+         * Maps an auth result to a Backstage identity for the user.
+         */
+        resolver: SignInResolver<AwsAlbResult>;
+    };
+};
+declare const createAwsAlbProvider: (options?: AwsAlbProviderOptions | undefined) => AuthProviderFactory;
+
+declare type BitbucketOAuthResult = {
+    fullProfile: BitbucketPassportProfile;
+    params: {
+        id_token?: string;
+        scope: string;
+        expires_in: number;
+    };
+    accessToken: string;
+    refreshToken?: string;
+};
+declare type BitbucketPassportProfile = Profile & {
+    id?: string;
+    displayName?: string;
+    username?: string;
+    avatarUrl?: string;
+    _json?: {
+        links?: {
+            avatar?: {
+                href?: string;
+            };
+        };
+    };
+};
+declare const bitbucketUsernameSignInResolver: SignInResolver<BitbucketOAuthResult>;
+declare const bitbucketUserIdSignInResolver: SignInResolver<BitbucketOAuthResult>;
+declare type BitbucketProviderOptions = {
+    /**
+     * The profile transformation function used to verify and convert the auth response
+     * into the profile that will be presented to the user.
+     */
+    authHandler?: AuthHandler<OAuthResult>;
+    /**
+     * Configure sign-in for this provider, without it the provider can not be used to sign users in.
+     */
+    signIn?: {
+        /**
+         * Maps an auth result to a Backstage identity for the user.
+         */
+        resolver: SignInResolver<OAuthResult>;
+    };
+};
+declare const createBitbucketProvider: (options?: BitbucketProviderOptions | undefined) => AuthProviderFactory;
+
 declare type GithubOAuthResult = {
     fullProfile: Profile;
     params: {
@@ -555,14 +752,30 @@ declare type OAuth2ProviderOptions = {
 };
 declare const createOAuth2Provider: (options?: OAuth2ProviderOptions | undefined) => AuthProviderFactory;
 
-declare type AuthResult = {
+/**
+ * authentication result for the OIDC which includes the token set and user information (a profile response sent by OIDC server)
+ * @public
+ */
+declare type OidcAuthResult = {
     tokenset: TokenSet;
     userinfo: UserinfoResponse;
 };
+/**
+ * OIDC provider callback options. An auth handler and a sign in resolver
+ * can be passed while creating a OIDC provider.
+ *
+ * authHandler : called after sign in was successful, a new object must be returned which includes a profile
+ * signInResolver: called after sign in was successful, expects to return a new {@link BackstageSignInResult}
+ *
+ * Both options are optional. There is fallback for authHandler where the default handler expect an e-mail explicitly
+ * otherwise it throws an error
+ *
+ * @public
+ */
 declare type OidcProviderOptions = {
-    authHandler?: AuthHandler<AuthResult>;
+    authHandler?: AuthHandler<OidcAuthResult>;
     signIn?: {
-        resolver?: SignInResolver<AuthResult>;
+        resolver?: SignInResolver<OidcAuthResult>;
     };
 };
 declare const createOidcProvider: (options?: OidcProviderOptions | undefined) => AuthProviderFactory;
@@ -586,32 +799,8 @@ declare type OktaProviderOptions = {
 };
 declare const createOktaProvider: (_options?: OktaProviderOptions | undefined) => AuthProviderFactory;
 
-declare type BitbucketOAuthResult = {
-    fullProfile: BitbucketPassportProfile;
-    params: {
-        id_token?: string;
-        scope: string;
-        expires_in: number;
-    };
-    accessToken: string;
-    refreshToken?: string;
-};
-declare type BitbucketPassportProfile = Profile & {
-    id?: string;
-    displayName?: string;
-    username?: string;
-    avatarUrl?: string;
-    _json?: {
-        links?: {
-            avatar?: {
-                href?: string;
-            };
-        };
-    };
-};
-declare const bitbucketUsernameSignInResolver: SignInResolver<BitbucketOAuthResult>;
-declare const bitbucketUserIdSignInResolver: SignInResolver<BitbucketOAuthResult>;
-declare type BitbucketProviderOptions = {
+/** @public */
+declare type OneLoginProviderOptions = {
     /**
      * The profile transformation function used to verify and convert the auth response
      * into the profile that will be presented to the user.
@@ -627,69 +816,8 @@ declare type BitbucketProviderOptions = {
         resolver: SignInResolver<OAuthResult>;
     };
 };
-declare const createBitbucketProvider: (options?: BitbucketProviderOptions | undefined) => AuthProviderFactory;
-
-declare type AtlassianAuthProviderOptions = OAuthProviderOptions & {
-    scopes: string;
-    signInResolver?: SignInResolver<OAuthResult>;
-    authHandler: AuthHandler<OAuthResult>;
-    tokenIssuer: TokenIssuer;
-    catalogIdentityClient: CatalogIdentityClient;
-    logger: Logger;
-};
-declare class AtlassianAuthProvider implements OAuthHandlers {
-    private readonly _strategy;
-    private readonly signInResolver?;
-    private readonly authHandler;
-    private readonly tokenIssuer;
-    private readonly catalogIdentityClient;
-    private readonly logger;
-    constructor(options: AtlassianAuthProviderOptions);
-    start(req: OAuthStartRequest): Promise<RedirectInfo>;
-    handler(req: express.Request): Promise<{
-        response: OAuthResponse;
-        refreshToken: string;
-    }>;
-    private handleResult;
-    refresh(req: OAuthRefreshRequest): Promise<OAuthResponse>;
-}
-declare type AtlassianProviderOptions = {
-    /**
-     * The profile transformation function used to verify and convert the auth response
-     * into the profile that will be presented to the user.
-     */
-    authHandler?: AuthHandler<OAuthResult>;
-    /**
-     * Configure sign-in for this provider, without it the provider can not be used to sign users in.
-     */
-    signIn?: {
-        resolver: SignInResolver<OAuthResult>;
-    };
-};
-declare const createAtlassianProvider: (options?: AtlassianProviderOptions | undefined) => AuthProviderFactory;
-
-declare type AwsAlbResult = {
-    fullProfile: Profile;
-    expiresInSeconds?: number;
-    accessToken: string;
-};
-declare type AwsAlbProviderOptions = {
-    /**
-     * The profile transformation function used to verify and convert the auth response
-     * into the profile that will be presented to the user.
-     */
-    authHandler?: AuthHandler<AwsAlbResult>;
-    /**
-     * Configure sign-in for this provider, without it the provider can not be used to sign users in.
-     */
-    signIn: {
-        /**
-         * Maps an auth result to a Backstage identity for the user.
-         */
-        resolver: SignInResolver<AwsAlbResult>;
-    };
-};
-declare const createAwsAlbProvider: (options?: AwsAlbProviderOptions | undefined) => AuthProviderFactory;
+/** @public */
+declare const createOneLoginProvider: (options?: OneLoginProviderOptions | undefined) => AuthProviderFactory;
 
 /** @public */
 declare type SamlAuthResult = {
@@ -719,6 +847,13 @@ declare const factories: {
     [providerId: string]: AuthProviderFactory;
 };
 
+/**
+ * Parses token and decorates the BackstageIdentityResponse with identity information sourced from the token
+ *
+ * @public
+ */
+declare function prepareBackstageIdentityResponse(result: BackstageSignInResult): BackstageIdentityResponse;
+
 declare type ProviderFactories = {
     [s: string]: AuthProviderFactory;
 };
@@ -729,7 +864,7 @@ interface RouterOptions {
     discovery: PluginEndpointDiscovery;
     providerFactories?: ProviderFactories;
 }
-declare function createRouter({ logger, config, discovery, database, providerFactories, }: RouterOptions): Promise<express.Router>;
+declare function createRouter(options: RouterOptions): Promise<express.Router>;
 declare function createOriginFilter(config: Config): (origin: string) => boolean;
 
 /**
@@ -747,4 +882,4 @@ declare type WebMessageResponse = {
 declare const postMessageResponse: (res: express.Response, appOrigin: string, response: WebMessageResponse) => void;
 declare const ensuresXRequestedWith: (req: express.Request) => boolean;
 
-export { AtlassianAuthProvider, AtlassianProviderOptions, AuthProviderFactory, AuthProviderFactoryOptions, AuthProviderRouteHandlers, AuthResponse, AwsAlbProviderOptions, BackstageIdentity, BitbucketOAuthResult, BitbucketPassportProfile, BitbucketProviderOptions, CatalogIdentityClient, GithubOAuthResult, GithubProviderOptions, GitlabProviderOptions, GoogleProviderOptions, IdentityClient, MicrosoftProviderOptions, OAuth2ProviderOptions, OAuthAdapter, OAuthEnvironmentHandler, OAuthHandlers, OAuthProviderInfo, OAuthProviderOptions, OAuthRefreshRequest, OAuthResponse, OAuthResult, OAuthStartRequest, OAuthState, OktaProviderOptions, ProfileInfo, RouterOptions, SamlAuthResult, SamlProviderOptions, TokenIssuer, WebMessageResponse, bitbucketUserIdSignInResolver, bitbucketUsernameSignInResolver, createAtlassianProvider, createAwsAlbProvider, createBitbucketProvider, createGithubProvider, createGitlabProvider, createGoogleProvider, createMicrosoftProvider, createOAuth2Provider, createOidcProvider, createOktaProvider, createOriginFilter, createRouter, createSamlProvider, factories as defaultAuthProviderFactories, encodeState, ensuresXRequestedWith, getEntityClaims, googleEmailSignInResolver, microsoftEmailSignInResolver, oktaEmailSignInResolver, postMessageResponse, readState, verifyNonce };
+export { AtlassianAuthProvider, AtlassianProviderOptions, Auth0ProviderOptions, AuthHandler, AuthHandlerResult, AuthProviderFactory, AuthProviderFactoryOptions, AuthProviderRouteHandlers, AuthResponse, AwsAlbProviderOptions, BackstageIdentity, BackstageIdentityResponse, BackstageSignInResult, BackstageUserIdentity, BitbucketOAuthResult, BitbucketPassportProfile, BitbucketProviderOptions, CatalogIdentityClient, GithubOAuthResult, GithubProviderOptions, GitlabProviderOptions, GoogleProviderOptions, IdentityClient, MicrosoftProviderOptions, OAuth2ProviderOptions, OAuthAdapter, OAuthEnvironmentHandler, OAuthHandlers, OAuthProviderInfo, OAuthProviderOptions, OAuthRefreshRequest, OAuthResponse, OAuthResult, OAuthStartRequest, OAuthState, OidcAuthResult, OidcProviderOptions, OktaProviderOptions, OneLoginProviderOptions, ProfileInfo, RouterOptions, SamlAuthResult, SamlProviderOptions, SignInInfo, SignInResolver, TokenIssuer, WebMessageResponse, bitbucketUserIdSignInResolver, bitbucketUsernameSignInResolver, createAtlassianProvider, createAuth0Provider, createAwsAlbProvider, createBitbucketProvider, createGithubProvider, createGitlabProvider, createGoogleProvider, createMicrosoftProvider, createOAuth2Provider, createOidcProvider, createOktaProvider, createOneLoginProvider, createOriginFilter, createRouter, createSamlProvider, factories as defaultAuthProviderFactories, encodeState, ensuresXRequestedWith, getEntityClaims, googleEmailSignInResolver, microsoftEmailSignInResolver, oktaEmailSignInResolver, postMessageResponse, prepareBackstageIdentityResponse, readState, verifyNonce };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/plugin-auth-backend",
   "description": "A Backstage backend plugin that handles authentication",
-  "version": "0.4.10",
+  "version": "0.6.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -30,12 +30,12 @@
     "clean": "backstage-cli clean"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.9.12",
-    "@backstage/catalog-client": "^0.5.2",
-    "@backstage/catalog-model": "^0.9.7",
+    "@backstage/backend-common": "^0.10.1",
+    "@backstage/catalog-client": "^0.5.3",
+    "@backstage/catalog-model": "^0.9.8",
     "@backstage/config": "^0.1.11",
     "@backstage/errors": "^0.1.5",
-    "@backstage/test-utils": "^0.1.23",
+    "@backstage/test-utils": "^0.2.1",
     "@google-cloud/firestore": "^4.15.1",
     "@types/express": "^4.17.6",
     "@types/passport": "^1.0.3",
@@ -46,7 +46,6 @@
     "express-promise-router": "^4.1.0",
     "express-session": "^1.17.1",
     "fs-extra": "9.1.0",
-    "got": "^11.5.2",
     "helmet": "^4.0.0",
     "jose": "^1.27.1",
     "jwt-decode": "^3.1.0",
@@ -73,7 +72,7 @@
     "yn": "^4.0.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.10.0",
+    "@backstage/cli": "^0.10.4",
     "@types/body-parser": "^1.19.0",
     "@types/cookie-parser": "^1.4.2",
     "@types/express-session": "^1.17.2",
@@ -92,5 +91,5 @@
     "config.d.ts"
   ],
   "configSchema": "config.d.ts",
-  "gitHead": "a05e7081b805006e3f0b2960a08a7753357f532f"
+  "gitHead": "4b2a8ed96ff427735c872a72c1864321ef698436"
 }