{"id":23507366,"url":"https://github.com/simplyhexagonal/session-sso","last_synced_at":"2026-05-07T08:35:53.429Z","repository":{"id":71910287,"uuid":"309434379","full_name":"simplyhexagonal/session-sso","owner":"simplyhexagonal","description":"Simple session SSO library to log in with Google, Github, Facebook, or a custom OAuth2 implementation","archived":false,"fork":false,"pushed_at":"2021-12-02T02:27:36.000Z","size":621,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T20:31:57.813Z","etag":null,"topics":["authentication","custom-oauth2","javascript","oauth","oauth2","session-sso","sso","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/session-sso","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplyhexagonal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-11-02T16:48:09.000Z","updated_at":"2021-12-02T02:27:39.000Z","dependencies_parsed_at":"2023-09-24T03:50:37.397Z","dependency_job_id":null,"html_url":"https://github.com/simplyhexagonal/session-sso","commit_stats":{"total_commits":44,"total_committers":1,"mean_commits":44.0,"dds":0.0,"last_synced_commit":"c88ddfff1dca44419e93bd63937666f44d951888"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplyhexagonal%2Fsession-sso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplyhexagonal%2Fsession-sso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplyhexagonal%2Fsession-sso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplyhexagonal%2Fsession-sso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplyhexagonal","download_url":"https://codeload.github.com/simplyhexagonal/session-sso/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253525346,"owners_count":21922063,"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","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":["authentication","custom-oauth2","javascript","oauth","oauth2","session-sso","sso","typescript"],"created_at":"2024-12-25T10:18:15.991Z","updated_at":"2026-05-07T08:35:53.390Z","avatar_url":"https://github.com/simplyhexagonal.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/jeanlescure","https://opencollective.com/simplyhexagonal"],"categories":[],"sub_categories":[],"readme":"![Session SSO Logo depicting a cloud with a fingerprint connected to colored dots representing the multiple SSO providers that are supported by this package](https://assets.jeanlescure.io/session-sso-logo.svg)\n\n# Session SSO\n![Tests](https://github.com/simplyhexagonal/session-sso/workflows/tests/badge.svg)\n\nAdd this package to your back-end API in order to easily authenticate with Google, Facebook, Github,\nor even your custom OAuth2 handled by this same library.\n\n## Open source notice\n\nThis project is open to updates by its users, [I](https://github.com/jeanlescure) ensure that PRs are relevant to the community.\nIn other words, if you find a bug or want a new feature, please help us by becoming one of the\n[contributors](#contributors-) ✌️ ! See the [contributing section](#contributing)\n\n## Like this module? ❤\n\nPlease consider:\n\n- [Buying me a coffee](https://www.buymeacoffee.com/jeanlescure) ☕\n- Supporting Simply Hexagonal on [Open Collective](https://opencollective.com/simplyhexagonal) 🏆\n- Starring this repo on [Github](https://github.com/simplyhexagonal/package) 🌟\n\n## New to Single Sign On (SSO) integrations?\n\nWe suggest taking a look at the [STRATEGY.md](https://github.com/jeanlescure/session-sso/blob/main/STRATEGY.md) document before moving forward here.\n\n## How to get started using this module?\n\n```ts\nimport SessionSSO from 'session-sso';\n\nconst sso = new SessionSSO({\n  // facebook dev credentials\n  appId: 'oHPrt6...',\n  appSecret: 'O9GGmv3KHJ...',\n  // github dev credentials\n  clientId: 'wf3s6u...',\n  clientSecret: 'AxDmXUPUnH...',\n});\n\n// note: google doesn't need dev credentials for SSO verification,\n// just on front-end to generate the initial OAuth token\n\nconst verifyGoogleResult = await sso.verifySSO({\n  provider: 'google',\n  authKey: 'ey0PweGlS1FG...', // token returned by `googleUser.getAuthResponse().id_token`\n});\n\nconst verifyFacebookResult = await sso.verifySSO({\n  provider: 'facebook',\n  authKey: 'EF25LPJCBAT...', // token returned by `FB.getLoginStatus()` =\u003e `response.authResponse.accessToken`\n});\n\nconst verifyGithubResult = await sso.verifySSO({\n  provider: 'github',\n  authKey: 'c12fa85efae0236c034b', // auth code placed in url when redirected back from https://github.com/login/oauth/authorize\n});\n\nconsole.log(verifyGoogleResult); // { \"email\": \"user-email-address@gmail.com\" }\nconsole.log(verifyFacebookResult); // { \"email\": \"user-email-address@gmail.com\" }\nconsole.log(verifyGithubResult); // { \"email\": \"user-email-address@gmail.com\" }\n```\n\nBy default the library will fetch the user's email since it's the most common default scope used by\nGoogle, Facebook, and GitHub's tokens.\n\nIf your provider allows you to fetch other scopes with your Client/Dev credentials, then you can\noverride which user properties are returned by `verifySSO` by passing the a `string[]` using the\n`retrieveProperties` option like so:\n\n```ts\nawait sso.verifySSO({\n  provider: 'google',\n  authKey: 'eyS1FG0PweGl...',\n  retrieveProperties: [\n    'email',\n    'email_verified',\n    'given_name',\n    'family_name',\n    'locale',\n  ]\n});\n\n// would return:\n// {\n//   payload: {\n//     \"email\": \"kahless@t-kuv.ma\",\n//     \"email_verified\": true,\n//     \"given_name\": \"Kahless\",\n//     \"family_name\": \"-\",\n//     \"locale\": \"tlh\"\n//   }\n// }\n```\n\nYou can also set these scopes when instantiating:\n\n```ts\nconst sso = new SessionSSO({\n  // ...\n  retrieveProperties: [\n    //...\n  ],\n});\n```\n\n**Note:** Doing it this way affects _all_ providers, so make sure all of them have the same naming conventions.\n\n## Create your own Custom SSO Provider\n\nThe custom SSO flow was inspired by Google's.\n\nFirst a user would send their authorization data (i.e. username, passowrd, etc), from here, it's up\nto you to generate an authorization promise:\n\n```ts\nconst authorizationPromise = async () =\u003e {\n  // your top secret authorization sauce here\n  // ...\n\n  // if auth fails\n  throw new Error('You cannot pass!');\n\n  // if auth succeeds\n  return {\n    iss: Math.floor(Date.now() / 1000), // issue date as Epoch number (seconds since 1970)\n    exp: Math.floor(Date.now() / 1000) + (60 * 60), // expiration date (1 hour later in this case)\n    email: 'user-email-address@gmail.com',\n    // ...\n  };\n};\n```\n\nthen proceed to produce another promise, this time for the private keys in JSON format:\n\n```ts\nconst privateKeyPromise: Promise\u003cPEMKeyPromisePayload\u003e = fetch(\n  'https://your.static.website/certs.priv.json',\n).then((res) =\u003e res.json()).then((jpems) =\u003e {\n  // `res` is a JSON with PEM keys:\n  // {\n  //   \"nnI9yCyGPq3r5zmurEVr05uf\": \"-----BEGIN RSA PRIVATE KEY-----\\nMIIEow...\",\n  //   \"y7I9IXxvGBEOhc9CuBcHIklK\": \"-----BEGIN RSA PRIVATE KEY-----\\nMIIEps...\"\n  // }\n  //\n  // For a full example of what this should look like visit: https://www.googleapis.com/oauth2/v1/certs\n\n  // Make it hard for bad actors to reverse-engineer PEM keys by using more than one, randomly\n  const randomKeyId = Object.keys(jpems).sort(() =\u003e Math.random() - 0.5)[0];\n\n  return {\n    kid: randomKeyId,\n    pem: jpems[randomKeyId],\n  };\n});\n```\n\nfinally send your front-end the resulting authentication token:\n\n```ts\nconst {\n  payload: {\n    token, // \u003c== send this\n  },\n} = await sso.generateSSO({\n  authorizationPromise,\n  privateKeyPromise,\n});\n```\n\nnow any front-end using your authentication end-point can verify that the token hasn't been forged\nby sending it back to your API where you do will do a very similar check as with google, facebook, and github:\n\n```ts\n// This is the only extra step. With google, facebook, and github we already know where the verification\n// comes from, so we baked it in; but here you get to set your own rule as to where to \nconst publicKeyPromise: Promise\u003cPEMKeyPromisePayload\u003e = fetch(\n  'https://your.static.website/certs.json',\n).then((res) =\u003e res.json());\n\nconst verifyCustomResult = await sso.verifySSO({\n  publicKeyPromise,\n  authKey: token as string,\n});\n```\n\n## Error handling\n\nBoth `verifySSO` and `generateSSO` promises will return an object with **only one property**,\neither `payload` or `error`.\n\nOn success, both `verifySSO` and `generateSSO` will resolve with an object with the `payload`\nproperty, for example:\n\n```js\n{\n  payload: {\n    //...\n  }\n}\n```\n\nOn error, both `verifySSO` and `generateSSO` will reject with an object with the `error` property,\nfor example:\n\n```js\n{\n  error: \"...\"\n}\n```\n\n**Note:** the value of the `error` property is a string.\n\n## 🚨 Where to place this library in your code/API (or \"I'm new to SSO, and confused\")\n\nWe've provided a handy and easy to understand explanation of a proper SSO strategy and where this\nlibrary is meant to be used, just take a look at the [STRATEGY.md](https://github.com/jeanlescure/session-sso/blob/main/STRATEGY.md) document.\n\n## Contributing\n\nYes, thank you! This plugin is community-driven, most of its features are from different authors.\nPlease update the docs and tests and add your name to the `package.json` file.\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://jeanlescure.cr\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/3330339?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eJean Lescure\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#maintenance-jeanlescure\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e \u003ca href=\"https://github.com/jeanlescure/session-sso/commits?author=jeanlescure\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#userTesting-jeanlescure\" title=\"User Testing\"\u003e📓\u003c/a\u003e \u003ca href=\"https://github.com/jeanlescure/session-sso/commits?author=jeanlescure\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"#example-jeanlescure\" title=\"Examples\"\u003e💡\u003c/a\u003e \u003ca href=\"https://github.com/jeanlescure/session-sso/commits?author=jeanlescure\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://dianalu.design\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1036995?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDiana Lescure\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/jeanlescure/session-sso/commits?author=DiLescure\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/jeanlescure/session-sso/pulls?q=is%3Apr+reviewed-by%3ADiLescure\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"#design-DiLescure\" title=\"Design\"\u003e🎨\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## License\n\nCopyright (c) 2020-Present [Session SSO Contributors](https://github.com/simplyhexagonal/session-sso/#contributors-).\u003cbr/\u003e\nLicensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplyhexagonal%2Fsession-sso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplyhexagonal%2Fsession-sso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplyhexagonal%2Fsession-sso/lists"}