docs(oidc): Updating + improving docs around OIDC configuration (#7141)

datahub-project · Jan 26, 2023 · c74060f · c74060f
1 parent 727a779
commit c74060f
Showing 1 changed file with 45 additions and 3 deletions.
diff --git a/docs/authentication/guides/sso/configure-oidc-react.md b/docs/authentication/guides/sso/configure-oidc-react.md
@@ -126,8 +126,8 @@ AUTH_OIDC_SCOPE=your-custom-scope
 AUTH_OIDC_CLIENT_AUTHENTICATION_METHOD=authentication-method
 ```
 
-- `AUTH_OIDC_USER_NAME_CLAIM`: The attribute that will contain the username used on the DataHub platform. By default, this is "preferred_username" provided
-  as part of the standard `profile` scope.
+- `AUTH_OIDC_USER_NAME_CLAIM`: The attribute that will contain the username used on the DataHub platform. By default, this is "email" provided
+  as part of the standard `email` scope.
 - `AUTH_OIDC_USER_NAME_CLAIM_REGEX`: A regex string used for extracting the username from the userNameClaim attribute. For example, if
   the userNameClaim field will contain an email address, and we want to omit the domain name suffix of the email, we can specify a custom
   regex to do so. (e.g. `([^@]+)`)
@@ -188,4 +188,46 @@ A brief summary of the steps that occur when the user navigates to the React app
    can be used to retrieve information on behalf of the authenticated user
 6. DataHub fetches the authenticated user's profile and extracts a username to identify the user on DataHub (eg. urn:li:corpuser:username)
 7. DataHub sets session cookies for the newly authenticated user
-8. DataHub redirects the user to the homepage ("/")
+8. DataHub redirects the user to the homepage ("/")
+
+## FAQ
+
+**No users can log in. Instead, I get redirected to the login page with an error. What do I do?**
+
+This can occur for a variety of reasons, but most often it is due to misconfiguration of Single-Sign On, either on the DataHub
+side or on the Identity Provider side. 
+
+First, verify that all values are consistent across them (e.g. the host URL where DataHub is deployed), and that no values
+are misspelled (client id, client secret). 
+
+Next, verify that the scopes requested are supported by your Identity Provider
+and that the claim (i.e. attribute) DataHub uses for uniquely identifying the user is supported by your Identity Provider (refer to Identity Provider OpenID Connect documentation). By default, this claim is `email`. 
+
+Then, make sure the Discovery URI you've configured (`AUTH_OIDC_DISCOVERY_URI`) is accessible where the datahub-frontend container is running. You
+can do this by issuing a basic CURL to the address (**Pro-Tip**: you may also visit the address in your browser to check more specific details about your Identity Provider). 
+
+Finally, check the container logs for the `datahub-frontend` container. This should hopefully provide some additional context
+around why exactly the login handoff is not working. 
+
+If all else fails, feel free to reach out to the DataHub Community on Slack for
+real-time support 
+
+
+
+**I'm seeing an error in the `datahub-frontend` logs when a user tries to login**
+```shell
+Caused by: java.lang.RuntimeException: Failed to resolve user name claim from profile provided by Identity Provider. Missing attribute. Attribute: 'email', Regex: '(.*)', Profile: { ...
+```
+**what do I do?**
+
+This indicates that your Identity Provider does not provide the claim with name 'email', which DataHub
+uses by default to uniquely identify users within your organization.
+
+To fix this, you may need to 
+
+1. Change the claim that is used as the unique user identifier to something else by changing the `AUTH_OIDC_USER_NAME_CLAIM` (e.g. to "name" or "preferred_username") _OR_
+2. Change the environment variable `AUTH_OIDC_SCOPE` to include the scope required to retrieve the claim with name "email"
+
+For the `datahub-frontend` container / pod. 
+
+**Pro-Tip**: Check the documentation for your Identity Provider to learn more about the scope claims supported.