Merge pull request #26969 from backstage/rugvip/harden

Update docs to be more strict around sign-in resolvers + remove insecure sign-in resolver
2024-10-08 11:53:37 +02:00
parent d66496a8eb a7ef006e15
commit 7fd7280e36
48 changed files with 186 additions and 276 deletions
@@ -49,9 +49,7 @@ auth:
        scope: ${AUTH_ATLASSIAN_SCOPES}
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # See https://backstage.io/docs/auth/atlassian/provider#resolvers for more resolvers
            - resolver: usernameMatchingUserEntityName
 ```

@@ -25,9 +25,8 @@ auth:
      region: 'us-west-2'
      signIn:
        resolvers:
-          # typically you would pick one of these
+          # See https://backstage.io/docs/auth/aws-alb/provider#resolvers for more resolvers
          - resolver: emailMatchingUserEntityProfileEmail
-          - resolver: emailLocalPartMatchingUserEntityName
 ```

 Ensure that you have set the signer correctly. It is also recommended that you restrict your target groups' security policy to only accept connections from that ALB.
@@ -39,11 +39,8 @@ auth:
        clientSecret: ${AUTH_BITBUCKET_CLIENT_SECRET}
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # See https://backstage.io/docs/auth/bitbucket/provider#resolvers for more resolvers
            - resolver: userIdMatchingUserEntityAnnotation
-            - resolver: usernameMatchingUserEntityAnnotation
 ```

 The Bitbucket provider is a structure with two configuration keys:
@@ -41,8 +41,8 @@ auth:
      # This picks what sign in resolver(s) you want to use.
      signIn:
        resolvers:
+          # See https://backstage.io/docs/auth/cloudflare/provider#resolvers for more resolvers
          - resolver: emailMatchingUserEntityProfileEmail
-          - resolver: emailLocalPartMatchingUserEntityName
 ```

 This config section must be in place for the provider to load at all.
@@ -51,8 +51,7 @@ auth:
        # enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
        signIn:
          resolvers:
-            # Matches the GitHub username with the Backstage user entity name.
-            # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
+            # See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers
            - resolver: usernameMatchingUserEntityName
 ```

@@ -46,9 +46,7 @@ auth:
        # callbackUrl: https://${BASE_URL}/api/auth/gitlab/handler/frame
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # See https://backstage.io/docs/auth/gitlab/provider#resolvers for more resolvers
            - resolver: usernameMatchingUserEntityName
 ```

@@ -29,9 +29,7 @@ auth:
      jwtHeader: x-custom-header # Optional: Only if you are using a custom header for the IAP JWT
      signIn:
        resolvers:
-          # typically you would pick one of these
-          - resolver: emailMatchingUserEntityProfileEmail
-          - resolver: emailLocalPartMatchingUserEntityName
+          # See https://backstage.io/docs/auth/google/gcp-iap-auth#resolvers for more resolvers
          - resolver: emailMatchingUserEntityAnnotation
 ```

@@ -44,9 +44,7 @@ auth:
        clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET}
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # See https://backstage.io/docs/auth/google/provider#resolvers for more resolvers
            - resolver: emailMatchingUserEntityAnnotation
 ```

@@ -70,6 +70,14 @@ always be full entity references, as opposed to shorthands like just `jane` or

 ## Sign-in Resolvers

+:::warning
+Be careful when configuring Sign-in resolvers, as they are part of determining who
+has access to your Backstage instance, and with what identity. Always only configure
+**a single sign-in resolver for one of your auth providers**. The only reason to have
+more sign-in resolvers is if you want to allow your users to sign in to Backstage in
+multiple ways, but it increases the risk of account hijacking.
+:::
+
 Signing in a user into Backstage requires a mapping of the user identity from the
 third-party auth provider to a Backstage user identity. This mapping can vary quite
 a lot between different organizations and auth providers, and because of that there's
@@ -112,19 +120,38 @@ auth:
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
 ```

-Note that in this instance it lists several resolvers, which means that the
-framework will try them one by one until one succeeds. If none of them do, the
-sign in attempt is rejected.
-
 The list of available resolvers is different for each provider, since they often
 depend on the information model returned from the upstream provider service.
 Consult the documentation of the respective provider to find the list.

-In the example above `emailMatchingUserEntityProfileEmail` and `emailLocalPartMatchingUserEntityName` are common to all auth providers and `usernameMatchingUserEntityName` is specific to GitHub.
+In the example above, the `usernameMatchingUserEntityName` is specific to the
+GitHub provider, but you could also choose to use the
+`emailMatchingUserEntityProfileEmail` or `emailLocalPartMatchingUserEntityName`
+resolvers, which are common to all auth providers.
+
+:::warning
+When using the `emailLocalPartMatchingUserEntityName` resolver it is strongly
+recommended to set the `allowedDomains` option to ensure that only authorized users
+are able to sign-in.
+:::
+
+If you are using the `emailLocalPartMatchingUserEntityName` resolver, it is
+recommended to also set the `allowedDomains` option, for example:
+
+```yaml title="Within the provider configuration"
+auth:
+  providers:
+    github:
+      development:
+        ...
+        signIn:
+          resolvers:
+            - resolver: emailLocalPartMatchingUserEntityName
+              allowedDomains:
+                - acme.org
+```

 ### Building Custom Resolvers

@@ -160,8 +187,6 @@ auth:
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
 /* highlight-remove-end */
 ```

@@ -318,6 +343,12 @@ async signInResolver({ profile: { email} }, ctx) {

 ### Sign-In without Users in the Catalog

+:::warning
+Signing in users without verifying that they exist in the catalog can be
+dangerous. Take care to ensure that your custom resolvers only allow expected
+users to sign in, for example by checking email domains.
+:::
+
 While populating the catalog with organizational data unlocks more powerful ways
 to browse your software ecosystem, it might not always be a viable or prioritized
 option. However, even if you do not have user entities populated in your catalog, you
@@ -66,9 +66,7 @@ auth:
    azureEasyAuth:
      signIn:
        resolvers:
-          # typically you would pick one of these
-          - resolver: emailMatchingUserEntityProfileEmail
-          - resolver: emailLocalPartMatchingUserEntityName
+          # See https://backstage.io/docs/auth/microsoft/easy-auth#resolvers for more resolvers
          - resolver: idMatchingUserEntityAnnotation
 ```

@@ -69,10 +69,7 @@ auth:
        domainHint: ${AZURE_TENANT_ID}
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
-            - resolver: emailMatchingUserEntityAnnotation
+            # See https://backstage.io/docs/auth/microsoft/provider#resolvers for more resolvers
            - resolver: userIdMatchingUserEntityAnnotation
 ```

@@ -31,9 +31,7 @@ auth:
    oauth2Proxy:
      signIn:
        resolvers:
-          # typically you would pick one of these
-          - resolver: emailMatchingUserEntityProfileEmail
-          - resolver: emailLocalPartMatchingUserEntityName
+          # See https://backstage.io/docs/auth/oauth2-proxy/provider#resolvers for more resolvers
          - resolver: forwardedUserMatchingUserEntityName
 ```

@@ -156,8 +156,6 @@ auth:
        # ...
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailLocalPartMatchingUserEntityName
            - resolver: emailMatchingUserEntityProfileEmail
 ```

@@ -49,9 +49,7 @@ auth:
        additionalScopes: ${AUTH_OKTA_ADDITIONAL_SCOPES} # Optional
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # See https://backstage.io/docs/auth/okta/provider#resolvers for more resolvers
            - resolver: emailMatchingUserEntityAnnotation
 ```

@@ -40,9 +40,7 @@ auth:
        issuer: https://<company>.onelogin.com/oidc/2
        signIn:
          resolvers:
-            # typically you would pick one of these
-            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
+            # See https://backstage.io/docs/auth/onelogin/provider#resolvers for more resolvers
            - resolver: usernameMatchingUserEntityName
 ```

@@ -49,10 +49,8 @@ auth:
        organizationId: ${ORG_ID}
        signIn:
          resolvers:
-            # typically you would pick one of these
+            # See https://backstage.io/docs/auth/vmware-cloud/provider#resolvers for more resolvers
            - resolver: emailMatchingUserEntityProfileEmail
-            - resolver: emailLocalPartMatchingUserEntityName
-            - resolver: vmwareCloudSignInResolvers
 ```

 Where `APP_ID` refers to the ID retrieved when creating the OAuth App, and
@@ -76,7 +74,6 @@ This provider includes several resolvers out of the box that you can use:

 - `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will throw a `NotFoundError`.
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
- `vmwareCloudSignInResolvers`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found it will sign in the user without associating with a catalog user.

 :::note Note