@backstage/plugin-auth-backend 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { UserEntity, Entity } from '@backstage/catalog-model';
 import { Profile } from 'passport';
 import { JSONWebKey } from 'jose';
 import { TokenSet, UserinfoResponse } from 'openid-client';
+import { JsonValue } from '@backstage/types';
 
 /** Represents any form of serializable JWK */
 interface AnyJWK extends Record<string, string> {
@@ -115,17 +116,16 @@ declare type OAuthRefreshRequest = express.Request<{}> & {
  * Any OAuth provider needs to implement this interface which has provider specific
  * handlers for different methods to perform authentication, get access tokens,
  * refresh tokens and perform sign out.
+ *
+ * @public
  */
 interface OAuthHandlers {
     /**
-     * This method initiates a sign in request with an auth provider.
-     * @param {express.Request} req
-     * @param options
+     * Initiate a sign in request with an auth provider.
      */
     start(req: OAuthStartRequest): Promise<RedirectInfo>;
     /**
-     * Handles the redirect from the auth provider when the user has signed in.
-     * @param {express.Request} req
+     * Handle the redirect from the auth provider when the user has signed in.
      */
     handler(req: express.Request): Promise<{
         response: OAuthResponse;
@@ -133,8 +133,6 @@ interface OAuthHandlers {
     }>;
     /**
      * (Optional) Given a refresh token and scope fetches a new access token from the auth provider.
-     * @param {string} refreshToken
-     * @param {string} scope
      */
     refresh?(req: OAuthRefreshRequest): Promise<{
         response: OAuthResponse;
@@ -224,6 +222,16 @@ declare class CatalogIdentityClient {
 
 declare function getEntityClaims(entity: UserEntity): TokenParams['claims'];
 
+/**
+ * The context that is used for auth processing.
+ *
+ * @public
+ */
+declare type AuthResolverContext = {
+    tokenIssuer: TokenIssuer;
+    catalogIdentityClient: CatalogIdentityClient;
+    logger: Logger;
+};
 declare type AuthProviderConfig = {
     /**
      * The protocol://domain[:port] where the app is hosted. This is used to construct the
@@ -255,10 +263,10 @@ declare type RedirectInfo = {
  *
  * The routes in the auth backend API are tied to these methods like below
  *
- * /auth/[provider]/start -> start
- * /auth/[provider]/handler/frame -> frameHandler
- * /auth/[provider]/refresh -> refresh
- * /auth/[provider]/logout -> logout
+ * `/auth/[provider]/start -> start`
+ * `/auth/[provider]/handler/frame -> frameHandler`
+ * `/auth/[provider]/refresh -> refresh`
+ * `/auth/[provider]/logout -> logout`
  */
 interface AuthProviderRouteHandlers {
     /**
@@ -269,9 +277,6 @@ interface AuthProviderRouteHandlers {
      * Response
      * - redirect to the auth provider for the user to sign in or consent.
      * - sets a nonce cookie and also pass the nonce as 'state' query parameter in the redirect request
-     *
-     * @param {express.Request} req
-     * @param {express.Response} res
      */
     start(req: express.Request, res: express.Response): Promise<void>;
     /**
@@ -283,9 +288,6 @@ interface AuthProviderRouteHandlers {
      * Response
      * - postMessage to the window with a payload that contains accessToken, expiryInSeconds?, idToken? and scope.
      * - sets a refresh token cookie if the auth provider supports refresh tokens
-     *
-     * @param {express.Request} req
-     * @param {express.Response} res
      */
     frameHandler(req: express.Request, res: express.Response): Promise<void>;
     /**
@@ -296,9 +298,6 @@ interface AuthProviderRouteHandlers {
      * - to contain a refresh token cookie and scope (Optional) query parameter.
      * Response
      * - payload with accessToken, expiryInSeconds?, idToken?, scope and user profile information.
-     *
-     * @param {express.Request} req
-     * @param {express.Response} res
      */
     refresh?(req: express.Request, res: express.Response): Promise<void>;
     /**
@@ -306,9 +305,6 @@ interface AuthProviderRouteHandlers {
      *
      * Response
      * - removes the refresh token cookie
-     *
-     * @param {express.Request} req
-     * @param {express.Response} res
      */
     logout?(req: express.Request, res: express.Response): Promise<void>;
 }
@@ -381,12 +377,15 @@ interface BackstageSignInResult {
 }
 /**
  * The old exported symbol for {@link BackstageSignInResult}.
+ *
  * @public
- * @deprecated Use the `BackstageSignInResult` type instead.
+ * @deprecated Use the {@link BackstageSignInResult} instead.
  */
 declare type BackstageIdentity = BackstageSignInResult;
 /**
- * Response object containing the {@link BackstageUserIdentity} and the token from the authentication provider.
+ * Response object containing the {@link BackstageUserIdentity} and the token
+ * from the authentication provider.
+ *
  * @public
  */
 interface BackstageIdentityResponse extends BackstageSignInResult {
@@ -399,7 +398,8 @@ interface BackstageIdentityResponse extends BackstageSignInResult {
  * 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
+ * identity, but we want to replace that with data from identity and/org catalog
+ * service
  *
  * @public
  */
@@ -419,47 +419,52 @@ declare type ProfileInfo = {
     picture?: string;
 };
 /**
- * type of sign in information context, includes the profile information and authentication result which contains auth. related information
+ * Type of sign in information context. Includes the profile information and
+ * authentication result which contains auth related information.
+ *
  * @public
  */
-declare type SignInInfo<AuthResult> = {
+declare type SignInInfo<TAuthResult> = {
     /**
      * The simple profile passed down for use in the frontend.
      */
     profile: ProfileInfo;
     /**
-     * The authentication result that was received from the authentication provider.
+     * The authentication result that was received from the authentication
+     * provider.
      */
-    result: AuthResult;
+    result: TAuthResult;
 };
 /**
- * Sign in resolver type describes the function which handles the result of a successful authentication
- * and it must return a valid {@link BackstageSignInResult}
+ * Describes the function which handles the result of a successful
+ * authentication. Must return a valid {@link BackstageSignInResult}.
+ *
  * @public
  */
-declare type SignInResolver<AuthResult> = (info: SignInInfo<AuthResult>, context: {
-    tokenIssuer: TokenIssuer;
-    catalogIdentityClient: CatalogIdentityClient;
-    logger: Logger;
-}) => Promise<BackstageSignInResult>;
+declare type SignInResolver<TAuthResult> = (info: SignInInfo<TAuthResult>, context: AuthResolverContext) => Promise<BackstageSignInResult>;
 /**
- * The return type of authentication handler which must contain a valid profile information
+ * The return type of an authentication handler. Must contain valid profile
+ * information.
+ *
  * @public
  */
 declare type AuthHandlerResult = {
     profile: ProfileInfo;
 };
 /**
- * The AuthHandler function is called every time the user authenticates using the provider.
+ * The AuthHandler function is called every time the user authenticates using
+ * the provider.
  *
- * The handler should return a profile that represents the session for the user in the frontend.
+ * The handler should return a profile that represents the session for the user
+ * in the frontend.
  *
- * 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.
+ * 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 AuthHandler<TAuthResult> = (input: TAuthResult, context: AuthResolverContext) => Promise<AuthHandlerResult>;
 declare type StateEncoder = (req: OAuthStartRequest) => Promise<{
     encodedState: string;
 }>;
@@ -674,7 +679,7 @@ declare type GithubProviderOptions = {
      * Providing your own stateEncoder will allow you to add addition parameters to the state field.
      *
      * It is typed as follows:
-     *   export type StateEncoder = (input: OAuthState) => Promise<{encodedState: string}>;
+     *   `export type StateEncoder = (input: OAuthState) => Promise<{encodedState: string}>;`
      *
      * Note: the stateEncoder must encode a 'nonce' value and an 'env' value. Without this, the OAuth flow will fail
      * (These two values will be set by the req.state by default)
@@ -752,6 +757,49 @@ declare type OAuth2ProviderOptions = {
 };
 declare const createOAuth2Provider: (options?: OAuth2ProviderOptions | undefined) => AuthProviderFactory;
 
+/**
+ * JWT header extraction result, containing the raw value and the parsed JWT
+ * payload.
+ *
+ * @public
+ */
+declare type OAuth2ProxyResult<JWTPayload> = {
+    /**
+     * Parsed and decoded JWT payload.
+     */
+    fullProfile: JWTPayload;
+    /**
+     * Raw JWT token
+     */
+    accessToken: string;
+};
+/**
+ * Options for the oauth2-proxy provider factory
+ *
+ * @public
+ */
+declare type Oauth2ProxyProviderOptions<JWTPayload> = {
+    /**
+     * Configure an auth handler to generate a profile for the user.
+     */
+    authHandler: AuthHandler<OAuth2ProxyResult<JWTPayload>>;
+    /**
+     * 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<OAuth2ProxyResult<JWTPayload>>;
+    };
+};
+/**
+ * Factory function for oauth2-proxy auth provider
+ *
+ * @public
+ */
+declare const createOauth2ProxyProvider: <JWTPayload>(options: Oauth2ProxyProviderOptions<JWTPayload>) => AuthProviderFactory;
+
 /**
  * authentication result for the OIDC which includes the token set and user information (a profile response sent by OIDC server)
  * @public
@@ -843,12 +891,76 @@ declare type SamlProviderOptions = {
 /** @public */
 declare const createSamlProvider: (options?: SamlProviderOptions | undefined) => AuthProviderFactory;
 
+/**
+ * The data extracted from an IAP token.
+ *
+ * @public
+ */
+declare type GcpIapTokenInfo = {
+    /**
+     * The unique, stable identifier for the user.
+     */
+    sub: string;
+    /**
+     * User email address.
+     */
+    email: string;
+    /**
+     * Other fields.
+     */
+    [key: string]: JsonValue;
+};
+/**
+ * The result of the initial auth challenge. This is the input to the auth
+ * callbacks.
+ *
+ * @public
+ */
+declare type GcpIapResult = {
+    /**
+     * The data extracted from the IAP token header.
+     */
+    iapToken: GcpIapTokenInfo;
+};
+/**
+ * Options for {@link createGcpIapProvider}.
+ *
+ * @public
+ */
+declare type GcpIapProviderOptions = {
+    /**
+     * The profile transformation function used to verify and convert the auth
+     * response into the profile that will be presented to the user. The default
+     * implementation just provides the authenticated email that the IAP
+     * presented.
+     */
+    authHandler?: AuthHandler<GcpIapResult>;
+    /**
+     * Configures sign-in for this provider.
+     */
+    signIn: {
+        /**
+         * Maps an auth result to a Backstage identity for the user.
+         */
+        resolver: SignInResolver<GcpIapResult>;
+    };
+};
+
+/**
+ * Creates an auth provider for Google Identity-Aware Proxy.
+ *
+ * @public
+ */
+declare function createGcpIapProvider(options: GcpIapProviderOptions): AuthProviderFactory;
+
 declare const factories: {
     [providerId: string]: AuthProviderFactory;
 };
 
 /**
- * Parses token and decorates the BackstageIdentityResponse with identity information sourced from the token
+ * Parses a Backstage-issued token and decorates the
+ * {@link BackstageIdentityResponse} with identity information sourced from the
+ * token.
  *
  * @public
  */
@@ -882,4 +994,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, 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 };
+export { AtlassianAuthProvider, AtlassianProviderOptions, Auth0ProviderOptions, AuthHandler, AuthHandlerResult, AuthProviderFactory, AuthProviderFactoryOptions, AuthProviderRouteHandlers, AuthResolverContext, AuthResponse, AwsAlbProviderOptions, BackstageIdentity, BackstageIdentityResponse, BackstageSignInResult, BackstageUserIdentity, BitbucketOAuthResult, BitbucketPassportProfile, BitbucketProviderOptions, CatalogIdentityClient, GcpIapProviderOptions, GcpIapResult, GcpIapTokenInfo, GithubOAuthResult, GithubProviderOptions, GitlabProviderOptions, GoogleProviderOptions, IdentityClient, MicrosoftProviderOptions, OAuth2ProviderOptions, OAuth2ProxyResult, OAuthAdapter, OAuthEnvironmentHandler, OAuthHandlers, OAuthProviderInfo, OAuthProviderOptions, OAuthRefreshRequest, OAuthResponse, OAuthResult, OAuthStartRequest, OAuthState, Oauth2ProxyProviderOptions, OidcAuthResult, OidcProviderOptions, OktaProviderOptions, OneLoginProviderOptions, ProfileInfo, RouterOptions, SamlAuthResult, SamlProviderOptions, SignInInfo, SignInResolver, TokenIssuer, WebMessageResponse, bitbucketUserIdSignInResolver, bitbucketUsernameSignInResolver, createAtlassianProvider, createAuth0Provider, createAwsAlbProvider, createBitbucketProvider, createGcpIapProvider, createGithubProvider, createGitlabProvider, createGoogleProvider, createMicrosoftProvider, createOAuth2Provider, createOauth2ProxyProvider, 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.6.0",
+  "version": "0.7.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "license": "Apache-2.0",
@@ -30,13 +30,13 @@
     "clean": "backstage-cli clean"
   },
   "dependencies": {
-    "@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.2.1",
-    "@google-cloud/firestore": "^4.15.1",
+    "@backstage/backend-common": "^0.10.4",
+    "@backstage/catalog-client": "^0.5.5",
+    "@backstage/catalog-model": "^0.9.10",
+    "@backstage/config": "^0.1.13",
+    "@backstage/errors": "^0.2.0",
+    "@backstage/types": "^0.1.1",
+    "@google-cloud/firestore": "^5.0.2",
     "@types/express": "^4.17.6",
     "@types/passport": "^1.0.3",
     "compression": "^1.7.4",
@@ -46,6 +46,7 @@
     "express-promise-router": "^4.1.0",
     "express-session": "^1.17.1",
     "fs-extra": "9.1.0",
+    "google-auth-library": "^7.6.1",
     "helmet": "^4.0.0",
     "jose": "^1.27.1",
     "jwt-decode": "^3.1.0",
@@ -72,7 +73,8 @@
     "yn": "^4.0.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.10.4",
+    "@backstage/cli": "^0.12.0",
+    "@backstage/test-utils": "^0.2.3",
     "@types/body-parser": "^1.19.0",
     "@types/cookie-parser": "^1.4.2",
     "@types/express-session": "^1.17.2",
@@ -83,7 +85,8 @@
     "@types/passport-saml": "^1.1.3",
     "@types/passport-strategy": "^0.2.35",
     "@types/xml2js": "^0.4.7",
-    "msw": "^0.35.0"
+    "msw": "^0.35.0",
+    "supertest": "^6.1.3"
   },
   "files": [
     "dist",
@@ -91,5 +94,5 @@
     "config.d.ts"
   ],
   "configSchema": "config.d.ts",
-  "gitHead": "4b2a8ed96ff427735c872a72c1864321ef698436"
+  "gitHead": "600d6e3c854bbfb12a0078ca6f726d1c0d1fea0b"
 }