Merge pull request #146 from nocodb/sso-faq

SSO - FAQ page

Author: dstala

content/docs/FAQs.md

@@ -70,3 +70,7 @@ PackageVersion: **0.258.2**
 - Community Forums: https://community.nocodb.com/
 - LinkedIn: https://www.linkedin.com/company/nocodb
 - Reddit: https://www.reddit.com/r/NocoDB/
+
+## SSO (Single Sign-On) FAQs
+
+For all questions related to SSO, please see the dedicated SSO FAQ section: [SSO FAQs](/docs/product-docs/account-settings/authentication/FAQs)

content/docs/account-settings/authentication/FAQs.md

@@ -0,0 +1,26 @@
+---
+title: 'SSO FAQs'
+description: 'Frequently asked questions about Single Sign-On (SSO) in NocoDB.'
+icon: "helpCircle"
+---
+
+## Why do I see the error "SSO is not configured for this domain" when trying to sign in?
+
+This error means that the email address you are using does not belong to a domain that has been verified and configured for SSO in your workspace settings. Only users with email addresses under your verified domain(s) can sign in via SSO. For example, if you’ve verified `example.com`, only users with emails like `[email protected]` will be allowed to sign in through the SSO page.
+
+## Do I need to verify my domain when setting up SSO (e.g., Google OAuth)?
+
+**For NocoDB Cloud:** Yes. In addition to configuring Google OAuth or other SSO providers, you must also verify your domain in the SSO settings. This is done by adding your domain and verifying it by adding the provided TXT record to your DNS. Only after domain verification will users from that domain be able to sign in via SSO.
+
+**For NocoDB Self-hosted/On-prem:** Domain verification is not required. You can configure SSO providers without verifying your domain via DNS. 
+
+## Why do I get a redirection/callback URL or URI error when setting up SSO?
+
+This error usually means that the Redirect URL (sometimes called Callback URL or Redirect URI) configured in your identity provider does not exactly match the one provided by NocoDB. Common reasons include:
+- Typo or extra spaces in the URL/URI
+- Using HTTP instead of HTTPS (or vice versa)
+- Not including the full path as required
+- Registering the wrong environment (e.g., using a local URL for production)
+- Forgetting to update the Redirect URL after changing your NocoDB domain
+
+**Solution:** Always copy and paste the exact Redirect URL/URI provided by NocoDB into your identity provider's configuration. Any mismatch will result in an error during authentication. 

content/docs/account-settings/authentication/google-oauth.mdx

@@ -28,3 +28,5 @@ NocoDB offers a functionality that allows users to connect with Google OAuth 2.0
 9. Go back to NocoDB and paste the credentials in in the respective fields in the `Google OAuth` section:
     - **Cloud version**: `Workspace Settings` > `Authentication` > `Google OAuth`
     - **On-prem version**: `Account Settings` > `Authentication` > `Google OAuth`
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>

content/docs/account-settings/authentication/oidc-sso/auth0.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Auth0' 
-description: 'Learn how to configure Auth0 as an identity provider for NocoDB.' 
+title: 'Auth0'
+description: 'Learn how to configure Auth0 as an identity provider for NocoDB.'
 tags: ['SSO', 'Auth0', 'OIDC']
 keywords: ['SSO', 'Auth0', 'OIDC', 'Authentication', 'Identity Provider']
 ---
@@ -56,4 +56,6 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 
 <Callout type="info">Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option</Callout>
 
-For information about Auth0 API Scopes, refer [here](https://auth0.com/docs/secure/tokens/refresh-tokens)
+For information about Auth0 API Scopes, refer [here](https://auth0.com/docs/secure/tokens/refresh-tokens)
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>

content/docs/account-settings/authentication/oidc-sso/azure-ad.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Azure AD (Entra)' 
-description: 'Learn how to configure Azure AD as an identity provider for NocoDB.' 
+title: 'Azure AD (Entra)'
+description: 'Learn how to configure Azure AD as an identity provider for NocoDB.'
 tags: ['SSO', 'Azure AD', 'OIDC']
 keywords: ['SSO', 'Azure AD', 'OIDC', 'Authentication', 'Identity Provider']
 ---
@@ -34,23 +34,23 @@ This article briefs about the steps to configure Azure AD as Identity service pr
     - Choose `Web` as the Application type
     - Add the `Redirect URL` under `Redirect URIs`.
     - `Register`
-5. On your application's homepage, 
+5. On your application's homepage,
     - Copy the `Application (client) ID`
     - Click `Add a certificate or secret` under `Client credentials` section
     - On `Certificates & secrets` page, go to `Client secrets` section
     - Click `New client secret`
-    - On `Add a client secret` page, 
+    - On `Add a client secret` page,
         - Add a description for the secret
         - Set expiration as required
         - `Add`
     - Copy the `Value` of the newly created secret
-6. On your application's homepage, 
+6. On your application's homepage,
     - Go to `Endpoints` tab
     - Open `OpenID Connect metadata document` URL & copy `authorization_endpoint`, `token_endpoint`, `userinfo_endpoint` & `jwks_uri` from the JSON response
 7. Configuring scopes
     - Go to `API permissions` tab
     - Click `Add a permission`
-    - On `Request API permissions` page, 
+    - On `Request API permissions` page,
         - Select `Microsoft Graph` from `Microsoft APIs`
         - Select `Delegated permissions`
         - Select `openid` `profile` `email` `offline_access` from `Select permissions` dropdown
@@ -78,4 +78,6 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
 </Callout>
 
-For information about Azure AD API Scopes, refer [here](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#offline_access)
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>
+
+For information about Azure AD API Scopes, refer [here](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-permissions-and-consent#offline_access)

content/docs/account-settings/authentication/oidc-sso/okta.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Okta' 
-description: 'Learn how to configure Okta as an identity provider for NocoDB.' 
+title: 'Okta'
+description: 'Learn how to configure Okta as an identity provider for NocoDB.'
 tags: ['SSO', 'Okta', 'OIDC']
 keywords: ['SSO', 'Okta', 'OIDC', 'Authentication', 'Identity Provider']
 ---
@@ -18,8 +18,8 @@ This article briefs about the steps to configure Okta as Identity service provid
 2. Select `Authentication (SSO)`
 3. Click on `New Provider` button
 4. On the Popup modal, Specify a `Display name` for the provider; note that, this name will be used to display the provider on the login page
-5. Retrieve `Redirect URL`; this information will be required to be configured later with the Identity Provider  
-  
+5. Retrieve `Redirect URL`; this information will be required to be configured later with the Identity Provider
+
 ![OIDC SSO Configuration](/img/v2/account-settings/SSO-1.png)
 ![OIDC SSO Configuration](/img/v2/account-settings/OIDC-2.png)
 ![OIDC SSO Configuration](/img/v2/account-settings/OIDC-3.png)
@@ -28,15 +28,15 @@ This article briefs about the steps to configure Okta as Identity service provid
 1. Sign in to your [Okta account](https://www.okta.com/) and navigate to the "Get started with Okta" page.
     - Click on `Add App` for the Single Sign-On option.
     - On the `Browse App Integration Catalog` page, select `Create New App`
-2. In the pop-up with title `Create a new app integration` 
+2. In the pop-up with title `Create a new app integration`
     - Choose `OIDC - OpenID Connect` as the Sign-in method
     - Choose `Web Application` as the Application type
 3. Go to `General Settings` on the `New Web App Integration` page
     - Provide your application's name.
     - From the Options in the `Grant type allowed` section, select `Authorization Code` and `Refresh Token`
     - Add the `Redirect URL` under `Sign-in redirect URIs`.
     - From the `Assignments section`, select an option from `Controlled access` to set up the desired accessibility configuration for this application.
-    - `Save` 
+    - `Save`
 4. On your new application,
     - Go to the `General` tab
     - Copy the `Client ID` and `Client Secret` from the `Client Credentials` section.
@@ -66,4 +66,6 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
 </Callout>
 
-For information about Okta API Scopes, refer [here](https://developer.okta.com/docs/reference/api/oidc/#scopes)
+For information about Okta API Scopes, refer [here](https://developer.okta.com/docs/reference/api/oidc/#scopes)
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>

content/docs/account-settings/authentication/oidc-sso/ping-identity.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Ping Identity' 
-description: 'Learn how to configure Ping Identity as an identity provider for NocoDB.' 
+title: 'Ping Identity'
+description: 'Learn how to configure Ping Identity as an identity provider for NocoDB.'
 tags: ['SSO', 'Ping Identity', 'OIDC']
 keywords: ['SSO', 'Ping Identity', 'OIDC', 'Authentication', 'Identity Provider']
 ---
@@ -38,14 +38,14 @@ This article briefs about the steps to configure Ping Identity as Identity servi
 6. On the "Add Application" panel:
     - Input the application name and description.
     - Choose "OIDC Web App" as the Application Type and click "Configure"
-7. From your application, 
+7. From your application,
     - Go to `Configurations` tab
     - Click on `Edit` button
     - Check `Refresh Token` option
     - Copy `Authorization URL`, `Token URL`, `Userinfo URL` & `JWK Set URL` from the `Endpoints` section
     - From `Generals` dropdown, copy `Client ID` & `Client Secret`
     - `Save`
-8. From `Resources` tab, 
+8. From `Resources` tab,
     - Click `Edit`
     - Select `openid` `profile` `email` from `Scopes`
 9. Switch toggle button in the top right corner to `On` to activate the application.
@@ -71,4 +71,6 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
 </Callout>
 
-For information about Ping Identity API Scopes, refer [here](https://docs.pingidentity.com/r/en-us/pingone/pingone_t_edit_scopes_for_an_application)
+For information about Ping Identity API Scopes, refer [here](https://docs.pingidentity.com/r/en-us/pingone/pingone_t_edit_scopes_for_an_application)
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>

content/docs/account-settings/authentication/saml-sso/auth0.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Auth0' 
-description: 'Learn how to configure Auth0 as an identity provider for NocoDB.' 
+title: 'Auth0'
+description: 'Learn how to configure Auth0 as an identity provider for NocoDB.'
 tags: ['SSO', 'Auth0', 'SAML']
 keywords: ['SSO', 'Auth0', 'SAML', 'Authentication', 'Identity Provider']
 ---
@@ -25,15 +25,15 @@ This article briefs about the steps to configure Auth0 as Identity service provi
 
 
 ### Auth0, Configure NocoDB as an Application
-1. Access your [Auth0 account](https://auth0.com/)  
+1. Access your [Auth0 account](https://auth0.com/)
     - navigate to `Applications` > `Create Application`.
-2. In the `Create Application` modal, 
-    - choose `Regular Web Application` 
+2. In the `Create Application` modal,
+    - choose `Regular Web Application`
     - click `Create`
 3. Upon successful creation, you will be directed to the `Quick Start` screen.
     - Go to the `Addons` tab.
     - Enable `SAML2 Web App`
-4. On the `SAML2 Web App` modal, 
+4. On the `SAML2 Web App` modal,
     - Paste `Redirect URL` copied in step above into `Application Callback URL` field
     - In Settings, retain `nameIdentifierProbes` as `["http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]`; remove other probes if any
    ```json
@@ -45,7 +45,7 @@ This article briefs about the steps to configure Auth0 as Identity service provi
    ```
    - Click `Enable` to save the settings
 
-5. On the `Settings` tab, 
+5. On the `Settings` tab,
     - move to `Advanced Settings` > `Endpoints` > `SAML` section,
     - copy the SAML `Metadata URL`
 
@@ -68,4 +68,6 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 
 <Callout type="note">
 Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
-</Callout>
+</Callout>
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>

content/docs/account-settings/authentication/saml-sso/azure-ad.mdx

@@ -66,3 +66,5 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 <Callout type="note">
 Post sign-out, refresh page (for the first time) if you do not see `Sign in with SSO` option
 </Callout>
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>

content/docs/account-settings/authentication/saml-sso/keycloak.mdx

@@ -1,6 +1,6 @@
 ---
-title: 'Keycloak' 
-description: 'Learn how to configure Keycloak as an identity provider for NocoDB.' 
+title: 'Keycloak'
+description: 'Learn how to configure Keycloak as an identity provider for NocoDB.'
 tags: ['SSO', 'Keycloak', 'SAML']
 keywords: ['SSO', 'Keycloak', 'SAML', 'Authentication', 'Identity Provider']
 ---
@@ -27,8 +27,8 @@ This article briefs about the steps to configure Keycloak as Identity service pr
 
 
 ### Keycloak, Configure NocoDB as an Application
-1. Access your Keycloak account  
-    - navigate to `Clients` menu 
+1. Access your Keycloak account
+    - navigate to `Clients` menu
     - select `Clients list` tab > Click `Create client` button.
 2. In the `Create Client` modal, `General Settings` tab:
     - Select `SAML` as the `Client type`
@@ -46,8 +46,8 @@ This article briefs about the steps to configure Keycloak as Identity service pr
     - Enable `Sign Assertions`
     - Click `Save`
 5. On the `Client details`, `Keys` tab,
-    - Disable `Signing keys config` > `Client Signature Required`   
-6. Navigate to `Realm Settings` > `Endpoints` 
+    - Disable `Signing keys config` > `Client Signature Required`
+6. Navigate to `Realm Settings` > `Endpoints`
     - Copy `SAML 2.0 Identity Provider Metadata` URL
 
 ### NocoDB, Configure Azure AD as an Identity Provider
@@ -64,3 +64,5 @@ For Sign-in's, user should be able to now see `Sign in with <SSO>` option.
 <Callout type="note">
 Post sign-out, refresh page (for the first time) if you do not see `Sign in with <SSO>` option
 </Callout>
+
+<Callout type="info">For more common questions and troubleshooting, see our [SSO FAQ](/docs/product-docs/account-settings/authentication/FAQs).</Callout>