Add FAQ to self-hosted SSO docs for it not working due to misconfiguration

2026-09-22 13:39:35 +00:00 · 2023-10-13 15:56:10 +01:00
parent cdb1d38f99
commit 543c55b5a6
6 changed files with 77 additions and 6 deletions
--- a/docs/documentation/platform/sso/azure.mdx
+++ b/docs/documentation/platform/sso/azure.mdx
@@ -89,3 +89,13 @@ Back in Azure, navigate to the **Users and groups** tab and select **+ Add user/
 Enabling SAML SSO enforces all members in your organization to only be able to log into Infisical via Azure.

 ![Azure SAML assignment](../../../images/sso/azure/enable-saml.png)
+
+<Note>
+   If you're configuring SAML SSO on a self-hosted instance of Infisical, make sure to
+   set the `JWT_PROVIDER_AUTH_SECRET` and `SITE_URL` environment variable for it to work:
+   
+   - `JWT_PROVIDER_AUTH_SECRET`: This is secret key used for signing and verifying JWT. This could be a randomly-generated 256-bit hex string.
+   - `SITE_URL`: The URL of your self-hosted instance of Infisical - should be an absolute URL including the protocol (e.g. https://app.infisical.com)
+</Note>
+
+
--- a/docs/documentation/platform/sso/github.mdx
+++ b/docs/documentation/platform/sso/github.mdx
@@ -29,9 +29,24 @@ Obtain the **Client ID** and generate a new **Client Secret** for your GitHub OA

 ![GCP obtain OAuth2 credentials](../../../images/sso/github/credentials.png)

-Back in your Infisical instance, add two new environment variables for the credentials of your GitHub OAuth application:
+Back in your Infisical instance, make sure to set the following environment variables:

 - `CLIENT_ID_GITHUB_LOGIN`: The **Client ID** of your GitHub OAuth application.
 - `CLIENT_SECRET_GITHUB_LOGIN`: The **Client Secret** of your GitHub OAuth application.
+- `JWT_PROVIDER_AUTH_SECRET`: A secret key used for signing and verifying JWT. This could be a randomly-generated 256-bit hex string.
+- `SITE_URL`: The URL of your self-hosted instance of Infisical - should be an absolute URL including the protocol (e.g. https://app.infisical.com)
   
-Once added, restart your Infisical instance and log in with GitHub.
+Once added, restart your Infisical instance and log in with GitHub.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why is GitHub SSO not working?">
+    It is likely that you have misconfigured your self-hosted instance of Infisical. You should:
+
+    - Check that you have set the `CLIENT_ID_GITHUB_LOGIN`, `CLIENT_SECRET_GITHUB_LOGIN`, 
+    `JWT_PROVIDER_AUTH_SECRET`, and `SITE_URL` environment variables.
+    - Check that the **Authorization callback URL** specified in GitHub matches the `SITE_URL` environment variable.
+    For example, if the former is `https://app.infisical.com/api/v1/sso/github` then the latter should be `https://app.infisical.com`.
+  </Accordion>
+</AccordionGroup>
--- a/docs/documentation/platform/sso/gitlab.mdx
+++ b/docs/documentation/platform/sso/gitlab.mdx
@@ -28,10 +28,25 @@ Obtain the **Application ID** and **Secret** for your GitLab application.

 ![sso gitlab config](/images/sso/gitlab/credentials.png) 

-Back in your Infisical instance, add 2-3 new environment variables for the credentials of your GitLab application:
+Back in your Infisical instance, make sure to set the following environment variables:

 - `CLIENT_ID_GITLAB_LOGIN`: The **Client ID** of your GitLab application.
 - `CLIENT_SECRET_GITLAB_LOGIN`: The **Secret** of your GitLab application.
 - (optional) `URL_GITLAB_LOGIN`: The URL of your self-hosted instance of GitLab where the OAuth application is registered. If no URL is passed in, this will default to `https://gitlab.com`.
+- `JWT_PROVIDER_AUTH_SECRET`: A secret key used for signing and verifying JWT. This could be a randomly-generated 256-bit hex string.
+- `SITE_URL`: The URL of your self-hosted instance of Infisical - should be an absolute URL including the protocol (e.g. https://app.infisical.com)
   
-Once added, restart your Infisical instance and log in with GitLab.
+Once added, restart your Infisical instance and log in with GitLab.
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why is GitLab SSO not working?">
+    It is likely that you have misconfigured your self-hosted instance of Infisical. You should:
+
+    - Check that you have set the `CLIENT_ID_GITLAB_LOGIN`, `CLIENT_SECRET_GITLAB_LOGIN`, 
+    `JWT_PROVIDER_AUTH_SECRET`, and `SITE_URL` environment variables.
+    - Check that the **Redirect URI** specified in GitLab matches the `SITE_URL` environment variable.
+    For example, if the former is `https://app.infisical.com/api/v1/sso/gitlab` then the latter should be `https://app.infisical.com`.
+  </Accordion>
+</AccordionGroup>
--- a/docs/documentation/platform/sso/google.mdx
+++ b/docs/documentation/platform/sso/google.mdx
@@ -22,9 +22,24 @@ Obtain the **Client ID** and **Client Secret** for your GCP OAuth2 application.

 ![GCP obtain OAuth2 credentials](../../../images/sso/google/credentials.png)
   
-Back in your Infisical instance, add two new environment variables for the credentials of your GCP OAuth2 application:
+Back in your Infisical instance, make sure to set the following environment variables:

 - `CLIENT_ID_GOOGLE_LOGIN`: The **Client ID** of your GCP OAuth2 application.
 - `CLIENT_SECRET_GOOGLE_LOGIN`: The **Client Secret** of your GCP OAuth2 application.
+- `JWT_PROVIDER_AUTH_SECRET`: A secret key used for signing and verifying JWT. This could be a randomly-generated 256-bit hex string.
+- `SITE_URL`: The URL of your self-hosted instance of Infisical - should be an absolute URL including the protocol (e.g. https://app.infisical.com)
   
-  Once added, restart your Infisical instance and log in with Google
+Once added, restart your Infisical instance and log in with Google
+
+## FAQ
+
+<AccordionGroup>
+  <Accordion title="Why is Google SSO not working?">
+    It is likely that you have misconfigured your self-hosted instance of Infisical. You should:
+
+    - Check that you have set the `CLIENT_ID_GOOGLE_LOGIN`, `CLIENT_SECRET_GOOGLE_LOGIN`, 
+    `JWT_PROVIDER_AUTH_SECRET`, and `SITE_URL` environment variables.
+    - Check that the **Authorized redirect URI** specified in GCP matches the `SITE_URL` environment variable.
+    For example, if the former is `https://app.infisical.com/api/v1/sso/google` then the latter should be `https://app.infisical.com`.
+  </Accordion>
+</AccordionGroup>
--- a/docs/documentation/platform/sso/jumpcloud.mdx
+++ b/docs/documentation/platform/sso/jumpcloud.mdx
@@ -72,3 +72,11 @@ Back in JumpCloud, navigate to the **User Groups** tab and assign users to the n
 Enabling SAML SSO enforces all members in your organization to only be able to log into Infisical via JumpCloud.

 ![JumpCloud SAML assignment](../../../images/sso/jumpcloud/enable-saml.png)
+
+<Note>
+   If you're configuring SAML SSO on a self-hosted instance of Infisical, make sure to
+   set the `JWT_PROVIDER_AUTH_SECRET` and `SITE_URL` environment variable for it to work:
+   
+   - `JWT_PROVIDER_AUTH_SECRET`: This is secret key used for signing and verifying JWT. This could be a randomly-generated 256-bit hex string.
+   - `SITE_URL`: The URL of your self-hosted instance of Infisical - should be an absolute URL including the protocol (e.g. https://app.infisical.com)
+</Note>
--- a/docs/documentation/platform/sso/okta.mdx
+++ b/docs/documentation/platform/sso/okta.mdx
@@ -77,3 +77,11 @@ At this point, you have configured everything you need within the context of the
 Enabling SAML SSO enforces all members in your organization to only be able to log into Infisical via Okta.

 ![SAML Okta assignment](../../../images/sso/okta/enable-saml.png)
+
+<Note>
+   If you're configuring SAML SSO on a self-hosted instance of Infisical, make sure to
+   set the `JWT_PROVIDER_AUTH_SECRET` and `SITE_URL` environment variable for it to work:
+   
+   - `JWT_PROVIDER_AUTH_SECRET`: This is secret key used for signing and verifying JWT. This could be a randomly-generated 256-bit hex string.
+   - `SITE_URL`: The URL of your self-hosted instance of Infisical - should be an absolute URL including the protocol (e.g. https://app.infisical.com)
+</Note>