From 40a2b65f27dc8cd8b5c00a8fcfdfaf22e1311be6 Mon Sep 17 00:00:00 2001 From: timothycarambat Date: Tue, 29 Oct 2024 15:11:43 -0700 Subject: [PATCH] simple SSO config docs --- pages/configuration.mdx | 66 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/pages/configuration.mdx b/pages/configuration.mdx index eb37976..c86574f 100644 --- a/pages/configuration.mdx +++ b/pages/configuration.mdx @@ -47,3 +47,69 @@ DISABLE_VIEW_CHAT_HISTORY="enable" ### Disable Fully remove or comment out the `DISABLE_VIEW_CHAT_HISTORY` environment variable to return to the default behavior. + +## Simple SSO Passthrough + + + **Important:** You should use an independent API key for using this feature so + you can revoke it if needed. This feature configuration is best used for + internally facing AnythingLLM instances that are not exposed to the public + internet for the best security practices. + + +Modification of the `SIMPLE_SSO_ENABLED` environment variable allows easily enable third party SSO solutions that do not require a full OAuth integration. This environment variable +will enable you to generate a temporary authentication link **per user** that can be visited in browser to automatically login the user. + +This feature is most useful for when you have AnythingLLM as a simple sub-service within a much larger system and you want to leverage existing user authentication flows within that system and want to provide a seamless login experience for your users to your AnythingLLM instance. + +### Prerequisites + +- **Your instance must be in multi-user mode** to use this feature. +- You should provision an API key for AnythingLLM so you can create new users as well as issue temporary authentication links for users. +- The user must already exist within AnythingLLM before using this feature. You can create a user via the in-app interface or the API. + +### Enable + +Set the `SIMPLE_SSO_ENABLED` environment variable to **_any value_** to enable. + +```bash copy +# This can be any value, number, boolean, or string and it will have the same effect. +SIMPLE_SSO_ENABLED="enable" +``` + +### Integration + +Once enabled, you can issue a temporary authentication link for a user leveraging the `/v1/users/{id}/issue-auth-token` endpoint via the AnythingLLM API. +You simply need to provide the user ID and the API key you created earlier to generate a temporary authentication token that can be used by the target user to login to AnythingLLM. + +```bash copy +curl -X POST "https://your-anythingllm-instance.com/v1/users/{id}/issue-auth-token" \ + -H "Authorization: Bearer {api_key}" +# Example Response +# { +# "token": "1234567890", +# "loginPath": "/sso/simple?token=1234567890" +# } +``` + +Now, the user can visit the provided `loginPath` URL in their browser to be automatically logged in to AnythingLLM! + +```text copy +https://your-anythingllm-instance.com/sso/simple?token=1234567890 +``` + +All temporary authentication tokens expire after 1 hour and are single-use only. Once logged in, the user sessions will be valid for 30 days. +The user will be redirected to the home page of AnythingLLM after logging in. +You can optionally redirect the user to a different URL after logging in by appending `&redirectTo={path/to/redirect}` to the query string of the login path. + +For example: + +```text copy +https://your-anythingllm-instance.com/sso/simple?token=1234567890&redirectTo=/workspaces/sample-workspace +``` + +Will redirect the user to the `/workspaces/sample-workspace` chat page after logging in. This can be useful if you want to redirect the user to a specific workspace they have access to after logging in. + +### Disable + +Fully remove or comment out the `SIMPLE_SSO_ENABLED` environment variable to return to the default behavior.