@backstage/plugin-auth-backend 0.17.3-next.0 → 0.17.3-next.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @backstage/plugin-auth-backend
 
+## 0.17.3-next.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.18.0-next.1
+  - @backstage/catalog-client@1.3.0-next.2
+  - @backstage/plugin-auth-node@0.2.9-next.1
+  - @backstage/catalog-model@1.1.5-next.1
+  - @backstage/config@1.0.6-next.0
+  - @backstage/errors@1.1.4
+  - @backstage/types@1.0.2
+
+## 0.17.3-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.18.0-next.0
+  - @backstage/config@1.0.6-next.0
+  - @backstage/catalog-client@1.3.0-next.1
+  - @backstage/catalog-model@1.1.5-next.1
+  - @backstage/errors@1.1.4
+  - @backstage/types@1.0.2
+  - @backstage/plugin-auth-node@0.2.9-next.0
+
 ## 0.17.3-next.0
 
 ### Patch Changes

package/dist/index.cjs.js

@@ -464,6 +464,10 @@ class OAuthAdapter {
       throw new errors.AuthenticationError("Refresh failed", error);
     }
   }
+  /**
+   * If the response from the OAuth provider includes a Backstage identity, we
+   * make sure it's populated with all the information we can derive from the user ID.
+   */
   async populateIdentity(identity) {
     if (!identity) {
       return void 0;
@@ -743,6 +747,14 @@ class Auth0Strategy extends Auth0InternalStrategy__default["default"] {
 
 class Auth0AuthProvider {
   constructor(options) {
+    /**
+     * Due to passport-auth0 forcing options.state = true,
+     * passport-oauth2 requires express-session to be installed
+     * so that the 'state' parameter of the oauth2 flow can be stored.
+     * This implementation of StateStore matches the NullStore found within
+     * passport-oauth2, which is the StateStore implementation used when options.state = false,
+     * allowing us to avoid using express-session in order to integrate with auth0.
+     */
     this.store = {
       store(_req, cb) {
         cb(null, null);
@@ -763,6 +775,8 @@ class Auth0AuthProvider {
         clientSecret: options.clientSecret,
         callbackURL: options.callbackUrl,
         domain: options.domain,
+        // We need passReqToCallback set to false to get params, but there's
+        // no matching type signature for that, so instead behold this beauty
         passReqToCallback: false,
         store: this.store
       },
@@ -1126,6 +1140,9 @@ const bitbucket = createAuthProviderIntegration({
     });
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their username to the `bitbucket.org/username` annotation.
+     */
     usernameMatchingUserEntityAnnotation() {
       return async (info, ctx) => {
         const { result } = info;
@@ -1139,6 +1156,9 @@ const bitbucket = createAuthProviderIntegration({
         });
       };
     },
+    /**
+     * Looks up the user by matching their user ID to the `bitbucket.org/user-id` annotation.
+     */
     userIdMatchingUserEntityAnnotation() {
       return async (info, ctx) => {
         const { result } = info;
@@ -1312,6 +1332,9 @@ const cfAccess = createAuthProviderIntegration({
     };
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their email to the entity email.
+     */
     emailMatchingUserEntityProfileEmail: () => commonByEmailResolver
   }
 });
@@ -1562,6 +1585,9 @@ const github = createAuthProviderIntegration({
     });
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their GitHub username to the entity name.
+     */
     usernameMatchingUserEntityName: () => {
       return async (info, ctx) => {
         const { fullProfile } = info.result;
@@ -1805,8 +1831,17 @@ const google = createAuthProviderIntegration({
     });
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their email local part to the entity name.
+     */
     emailLocalPartMatchingUserEntityName: () => commonByEmailLocalPartResolver,
+    /**
+     * Looks up the user by matching their email to the entity email.
+     */
     emailMatchingUserEntityProfileEmail: () => commonByEmailResolver,
+    /**
+     * Looks up the user by matching their email to the `google.com/email` annotation.
+     */
     emailMatchingUserEntityAnnotation() {
       return async (info, ctx) => {
         const { profile } = info;
@@ -1951,8 +1986,17 @@ const microsoft = createAuthProviderIntegration({
     });
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their email local part to the entity name.
+     */
     emailLocalPartMatchingUserEntityName: () => commonByEmailLocalPartResolver,
+    /**
+     * Looks up the user by matching their email to the entity email.
+     */
     emailMatchingUserEntityProfileEmail: () => commonByEmailResolver,
+    /**
+     * Looks up the user by matching their email to the `microsoft.com/email` annotation.
+     */
     emailMatchingUserEntityAnnotation() {
       return async (info, ctx) => {
         const { profile } = info;
@@ -2231,6 +2275,7 @@ class OidcAuthProvider {
     const issuer = await openidClient.Issuer.discover(options.metadataUrl);
     const client = new issuer.Client({
       access_type: "offline",
+      // this option must be passed to provider to receive a refresh token
       client_id: options.clientId,
       client_secret: options.clientSecret,
       redirect_uris: [options.callbackUrl],
@@ -2261,6 +2306,8 @@ class OidcAuthProvider {
     strategy.error = console.error;
     return { strategy, client };
   }
+  // Use this function to grab the user profile info from the token
+  // Then populate the profile with it
   async handleResult(result) {
     const { profile } = await this.authHandler(result, this.resolverContext);
     const response = {
@@ -2327,6 +2374,14 @@ const oidc = createAuthProviderIntegration({
 
 class OktaAuthProvider {
   constructor(options) {
+    /**
+     * Due to passport-okta-oauth forcing options.state = true,
+     * passport-oauth2 requires express-session to be installed
+     * so that the 'state' parameter of the oauth2 flow can be stored.
+     * This implementation of StateStore matches the NullStore found within
+     * passport-oauth2, which is the StateStore implementation used when options.state = false,
+     * allowing us to avoid using express-session in order to integrate with Okta.
+     */
     this.store = {
       store(_req, cb) {
         cb(null, null);
@@ -2458,8 +2513,17 @@ const okta = createAuthProviderIntegration({
     });
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their email local part to the entity name.
+     */
     emailLocalPartMatchingUserEntityName: () => commonByEmailLocalPartResolver,
+    /**
+     * Looks up the user by matching their email to the entity email.
+     */
     emailMatchingUserEntityProfileEmail: () => commonByEmailResolver,
+    /**
+     * Looks up the user by matching their email to the `okta.com/email` annotation.
+     */
     emailMatchingUserEntityAnnotation() {
       return async (info, ctx) => {
         const { profile } = info;
@@ -2674,6 +2738,9 @@ const saml = createAuthProviderIntegration({
     };
   },
   resolvers: {
+    /**
+     * Looks up the user by matching their nameID to the entity name.
+     */
     nameIdMatchingUserEntityName() {
       return async (info, ctx) => {
         const id = info.result.fullProfile.nameID;
@@ -2784,6 +2851,9 @@ class TokenFactory {
     }
     return new jose.SignJWT({ ...additionalClaims, iss, sub, ent, aud, iat, exp }).setProtectedHeader({ alg: key.alg, kid: key.kid }).setIssuer(iss).setAudience(aud).setSubject(sub).setIssuedAt(iat).setExpirationTime(exp).sign(await jose.importJWK(key));
   }
+  // This will be called by other services that want to verify ID tokens.
+  // It is important that it returns a list of all public keys that could
+  // have been used to sign tokens that have not yet expired.
   async listPublicKeys() {
     const { items: keys } = await this.keyStore.listKeys();
     const validKeys = [];
@@ -2971,6 +3041,15 @@ class FirestoreKeyStore {
       );
     }
   }
+  /**
+   * Helper function to allow us to modify the timeout used when
+   * performing Firestore database operations.
+   *
+   * The reason for this is that it seems that there's no other
+   * practical solution to change the default timeout of 10mins
+   * that Firestore has.
+   *
+   */
   async withTimeout(operation) {
     const timer = new Promise(
       (_, reject) => setTimeout(() => {
@@ -2979,12 +3058,21 @@ class FirestoreKeyStore {
     );
     return Promise.race([operation, timer]);
   }
+  /**
+   * Used to verify that the database is reachable.
+   */
   async verify() {
     await this.withTimeout(this.database.collection(this.path).limit(1).get());
   }
 }
 
 class KeyStores {
+  /**
+   * Looks at the `auth.keyStore` section in the application configuration
+   * and returns a KeyStore store. Defaults to `database`
+   *
+   * @returns a KeyStore store
+   */
   static async fromConfig(config, options) {
     var _a;
     const { logger, database } = options != null ? options : {};
@@ -3028,6 +3116,11 @@ class CatalogIdentityClient {
     this.catalogApi = options.catalogApi;
     this.tokenManager = options.tokenManager;
   }
+  /**
+   * Looks up a single user using a query.
+   *
+   * Throws a NotFoundError or ConflictError if 0 or multiple users are found.
+   */
   async findUser(query) {
     const filter = {
       kind: "user"
@@ -3046,6 +3139,13 @@ class CatalogIdentityClient {
     }
     return items[0];
   }
+  /**
+   * Resolve additional entity claims from the catalog, using the passed-in entity names. Designed
+   * to be used within a `signInResolver` where additional entity claims might be provided, but
+   * group membership and transient group membership lean on imported catalog relations.
+   *
+   * Returns a superset of the entity names that can be passed directly to `issueToken` as `ent`.
+   */
   async resolveCatalogMembership(query) {
     const { entityRefs, logger } = query;
     const resolvedEntityRefs = entityRefs.map((ref) => {