{"id":31061544,"url":"https://github.com/parisneo/lollms_sso_client","last_synced_at":"2026-07-21T16:52:35.492Z","repository":{"id":305280995,"uuid":"1022463584","full_name":"ParisNeo/lollms_sso_client","owner":"ParisNeo","description":"A js library for lollms sso service access from third party apps","archived":false,"fork":false,"pushed_at":"2025-08-01T05:10:08.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-01T07:44:23.889Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ParisNeo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T06:03:00.000Z","updated_at":"2025-08-01T05:10:11.000Z","dependencies_parsed_at":"2025-07-19T11:13:45.897Z","dependency_job_id":"67a45300-9898-447a-b3d3-7a943713860a","html_url":"https://github.com/ParisNeo/lollms_sso_client","commit_stats":null,"previous_names":["parisneo/lollms_sso_client"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ParisNeo/lollms_sso_client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ParisNeo%2Flollms_sso_client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ParisNeo%2Flollms_sso_client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ParisNeo%2Flollms_sso_client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ParisNeo%2Flollms_sso_client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ParisNeo","download_url":"https://codeload.github.com/ParisNeo/lollms_sso_client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ParisNeo%2Flollms_sso_client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275246407,"owners_count":25430814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-15T11:11:40.316Z","updated_at":"2026-07-21T16:52:35.390Z","avatar_url":"https://github.com/ParisNeo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LoLLMs SSO Client Library\n\nA lightweight, dependency-free JavaScript client library to easily integrate third-party web applications with the LoLLMs Single Sign-On (SSO) service.\n\n## How It Works (The SSO Flow)\n\nThis library simplifies a secure authentication flow similar to OAuth2. The client application (your app) never handles user passwords or the SSO secret.\n\n1.  **Redirect to LoLLMs**: Your application redirects the user to the LoLLMs login page.\n2.  **User Login \u0026 Authorization**: The user logs into their LoLLMs account and authorizes your application to access their information.\n3.  **Redirect Back with Token**: LoLLMs redirects the user back to your application's specified \"Redirect URI\" with a short-lived, single-use token in the URL.\n4.  **Token Validation**: Your application's frontend captures the token from the URL using this library.\n5.  **Fetch User Info**: Your application uses the library's `introspect()` method. This method securely sends the token to the LoLLMs backend, which validates it and returns the authorized user data.\n6.  **Session Management**: Your application can now use the returned user data to create its own session, log the user in, and update the UI.\n\n## 1. Setup in LoLLMs\n\nBefore using this library, you must configure your application within your LoLLMs instance:\n\n1.  Navigate to **Settings -\u003e Services** (for personal apps) or **Admin Panel -\u003e Services** (for system-wide apps).\n2.  Add or Edit an Application.\n3.  Set the **Authentication Type** to `LoLLMs SSO`.\n4.  A unique **Client ID** will be generated from the application name (e.g., `my_test_app`). You will need this for the client library.\n5.  Fill in the **Redirect URI**. This is the exact URL in your application where LoLLMs will send the user back after they log in (e.g., `https://myapp.com/auth/callback`). This page must use this SSO client library to handle the redirect.\n6.  Select the user information your application requires (e.g., Email, First Name).\n7.  Click **Save Changes**. The SSO secret is managed by the LoLLMs backend and is **not required** by this client library.\n\n## 2. Integration into Your Application\n\n### Step 1: Include the Library\n\nDownload `lollms_sso_client.js` from the `lollms_sso_client/` directory and include it in your web page.\n\n```html\n\u003cscript src=\"path/to/lollms_sso_client.js\"\u003e\u003c/script\u003e\n```\n\n### Step 2: Initialize the Client\n\nCreate a new instance of `LollmsSSOClient` with your LoLLMs server URL and your application's **Client ID**.\n\n```javascript\nconst ssoClient = new LollmsSSOClient({\n    lollmsUrl: 'http://localhost:9642', // The URL of your LoLLMs instance\n    clientId: 'my_test_app',            // The Client ID of your app from LoLLMs\n});\n```\n\n### Step 3: Handle the Login Flow\n\n1.  **Triggering Login**: Create a \"Login with LoLLMs\" button. When clicked, call the `login()` method.\n\n    ```javascript\n    // In your main login page script\n    document.getElementById('login-button').addEventListener('click', () =\u003e {\n        ssoClient.login();\n    });\n    ```\n\n2.  **Handling the Redirect**: On the page specified as your **Redirect URI**, you must call `handleRedirect()`. This method checks the URL for a token, saves it to `localStorage`, and cleans the URL.\n\n    ```javascript\n    // Place this code on your redirect page (e.g., /auth/callback)\n    document.addEventListener('DOMContentLoaded', () =\u003e {\n        const token = ssoClient.handleRedirect();\n        if (token) {\n            console.log(\"Login successful! Token stored.\");\n            // Now you can verify the token and then redirect to the main part of your app.\n            window.location.href = '/dashboard'; \n        }\n    });\n    ```\n\n### Step 4: Verify Token and Access User Data\n\nAfter the redirect, you have a token. Use `introspect()` to securely verify it with the LoLLMs server and get the user's information.\n\n```javascript\n// In your main application logic (e.g., on your dashboard page)\nasync function fetchAndDisplayUserInfo() {\n    if (!ssoClient.isAuthenticated()) {\n        console.log(\"User is not logged in. Redirecting to login.\");\n        // Redirect to your app's login page\n        window.location.href = '/login.html';\n        return;\n    }\n\n    try {\n        const introspectionData = await ssoClient.introspect();\n        console.log(\"User is valid:\", introspectionData);\n        // `introspectionData.user_info` contains the shared data (e.g., username, email)\n        document.getElementById('welcome-message').textContent = `Welcome, ${introspectionData.user_info.username}!`;\n    } catch (error) {\n        console.error(\"Authentication check failed:\", error.message);\n        // The token is invalid or expired. The library automatically calls logout().\n        // Redirect back to your login page.\n        window.location.href = '/login.html';\n    }\n}\n\nfetchAndDisplayUserInfo();\n```\n\n### Step 5: Handling Logout\n\nTo log a user out of your application, call `logout()`. This removes their token from `localStorage`.\n\n```javascript\ndocument.getElementById('logout-button').addEventListener('click', () =\u003e {\n    ssoClient.logout();\n    // Redirect to your login page\n    window.location.href = '/login.html';\n});\n```\n\n## API Reference\n\n-   `new LollmsSSOClient({ lollmsUrl, clientId, tokenStorageKey? })`\n    -   Creates a new client instance. `clientId` must match the one in your LoLLMs app configuration.\n-   `.login()`\n    -   Redirects the browser to the LoLLMs login page for your `clientId`.\n-   `.handleRedirect()`\n    -   Processes the URL after returning from LoLLMs. Call this on your redirect page. Returns the token if found.\n-   `.setToken(token)`\n    -   Manually saves a token to storage.\n-   `.getToken()`\n    -   Returns the stored token, or `null`.\n-   `.isAuthenticated()`\n    -   Returns `true` if a token is stored, `false` otherwise.\n-   `.logout()`\n    -   Removes the token from storage.\n-   `.introspect()`\n    -   Async method. Securely validates the token with the LoLLMs server. Returns a promise that resolves with user data or rejects with an error.\n\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparisneo%2Flollms_sso_client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparisneo%2Flollms_sso_client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparisneo%2Flollms_sso_client/lists"}