Add and document option for enabling email lookup (#913)

* Docs: Document option for enabling email lookup

* Add the new config in the config files

* Apply suggestions from code review

Co-authored-by: Ieva <ieva.vasiljeva@grafana.com>

* Don't capitalize identity providers

* Apply suggestions from code review

Co-authored-by: Jo <joao.guerreiro@grafana.com>

* Apply suggestions from code review

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

---------

Co-authored-by: Ieva <ieva.vasiljeva@grafana.com>
Co-authored-by: Jo <joao.guerreiro@grafana.com>
Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

conf/defaults.ini

@@ -556,6 +556,9 @@ sigv4_verbose_logging = false
 # Set to true to enable Azure authentication option for HTTP-based datasources
 azure_auth_enabled = false
 
+# Use email lookup in addition to the unique ID provided by the IdP
+oauth_allow_insecure_email_lookup = false
+
 #################################### Anonymous Auth ######################
 [auth.anonymous]
 # enable anonymous access

conf/sample.ini

@@ -545,6 +545,9 @@
 # Set to skip the organization role from JWT login and use system's role assignment instead.
 ; skip_org_role_sync = false
 
+# Use email lookup in addition to the unique ID provided by the IdP
+;oauth_allow_insecure_email_lookup = false
+
 #################################### Anonymous Auth ######################
 [auth.anonymous]
 # enable anonymous access

docs/sources/breaking-changes/breaking-changes-v10-0.md

@@ -158,6 +158,38 @@ We've built a [CLI tool](https://grafana.com/blog/2022/12/12/guide-to-using-the-
 
 - [Blog post describing usage of the new CLI command](https://grafana.com/blog/2022/12/12/guide-to-using-the-new-grafana-cli-user-identity-conflict-tool-in-grafana-9.3/)
 
+### Grafana OAuth integrations do not work anymore with email lookups
+
+#### You are affected if:
+
+- You have configured Grafana to use multiple identity providers, and you have users with the same email address in multiple identity providers.
+- You have configured Grafana to use Generic OAuth with an identity provider that does not support a unique ID field.
+
+#### Background
+
+Grafana used to validate identity provider accounts based on the email claim. On many identity providers, the email field is not unique, and this could open a possible account vector to perform an account takeover and authentication bypass in certain scenarios.
+This change also ensures that Grafana is protected against the [CVE-2023-3128](https://grafana.com/security/security-advisories/CVE-2023-3128) vulnerability.
+
+#### Change in Grafana v10
+
+Grafana will not allow the affected users to sign in.
+
+#### Migration path
+
+In order to address any errors, we have provided an escape hatch that allows you to activate email lookup. You can use the following configuration in your Grafana instance to return the previous behavior.
+
+```
+[auth]
+oauth_allow_insecure_email_lookup = true
+```
+
+We strongly recommend not doing this in case you are using Azure AD as an identity provider with a multi-tenant app.
+
+#### Learn more
+
+- [CVE-2023-3128 Advisory](https://grafana.com/security/security-advisories/CVE-2023-3128)
+- [Enable email lookup]({{< relref "../setup-grafana/configure-security/configure-authentication/" >}})
+
 ### The "Alias" field in the CloudWatch data source is removed
 
 #### You are affected if:

docs/sources/setup-grafana/configure-security/configure-authentication/_index.md

@@ -74,6 +74,9 @@ token_rotation_interval_minutes = 10
 
 # The maximum lifetime (seconds) an API key can be used. If it is set all the API keys should have limited lifetime that is lower than this value.
 api_key_max_seconds_to_live = -1
+
+# Enforce user lookup based on email instead of the unique ID provided by the IdP.
+oauth_allow_insecure_email_lookup = false
 ```
 
 ### Anonymous authentication
@@ -116,6 +119,20 @@ Hide the Grafana login form using the below configuration settings.
 disable_login_form = true
 ```
 
+### Enable email lookup
+
+Enable user lookup based on email in addition to using unique ID provided by IdPs.
+
+By default, Grafana relies on the user unique ID provided by the identity provider.
+Looking up users by email can be safe for some identity providers (for example, when they are single tenants and unique non-editable, validated emails are provided), as well as in some infrastructures.
+
+We strongly recommend against enabling email lookups, however it is possible to do with the following configuration.
+
+```bash
+[auth]
+oauth_allow_insecure_email_lookup = true
+```
+
 ### Automatic OAuth login
 
 Set to true to attempt login with specific OAuth provider automatically, skipping the login screen.