{"id":21417323,"url":"https://github.com/staffbase/plugins-sdk-nodejs","last_synced_at":"2026-01-07T10:20:08.110Z","repository":{"id":40649355,"uuid":"93078692","full_name":"Staffbase/plugins-sdk-nodejs","owner":"Staffbase","description":"Staffbase plugins SDK for Nodejs","archived":false,"fork":false,"pushed_at":"2025-05-12T08:01:13.000Z","size":1187,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-06-12T10:53:44.978Z","etag":null,"topics":["need-for-speed","plugin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/Staffbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":"authors.txt","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-06-01T16:40:59.000Z","updated_at":"2025-05-12T07:57:57.000Z","dependencies_parsed_at":"2023-02-11T02:30:24.801Z","dependency_job_id":"f6d7d22a-91d6-4e09-a4f4-ae5a05b9fdf4","html_url":"https://github.com/Staffbase/plugins-sdk-nodejs","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Staffbase/plugins-sdk-nodejs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Staffbase%2Fplugins-sdk-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Staffbase%2Fplugins-sdk-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Staffbase%2Fplugins-sdk-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Staffbase%2Fplugins-sdk-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Staffbase","download_url":"https://codeload.github.com/Staffbase/plugins-sdk-nodejs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Staffbase%2Fplugins-sdk-nodejs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262392577,"owners_count":23303935,"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":["need-for-speed","plugin"],"created_at":"2024-11-22T19:14:36.142Z","updated_at":"2026-01-07T10:20:08.037Z","avatar_url":"https://github.com/Staffbase.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/Staffbase/plugins-sdk-nodejs/workflows/Node.js%20CI/badge.svg)](https://github.com/Staffbase/plugins-sdk-nodejs/actions)\n\n# Staffbase Plugins SDK for Node.js.\n\nIf you are developing your own plugin for your Staffbase app we describe the authentication flow of a plugin at https://developers.staffbase.com/guide/customplugin-overview/. While this documentation just covers the conceptual ideas of the interface of plugins though – the so called Plugin SSO – we want to provide a library to help you develop your first plugin for Staffbase even faster. This SDK provides the basic functionality to parse and verify a provided token for Node.js.\n\n\n## Installation\n\nThe plugin SDK can be fetched from the npm registry (https://www.npmjs.com/package/@staffbase/staffbase-plugin-sdk). You can use npm command line tool to install it locally.\n\n    npm install (@staffbase/staffbase-plugin-sdk)\n\nYou can also save the module as a local dependency in your project package.json file with the following command:\n\n    npm install --save (@staffbase/staffbase-plugin-sdk)\n\n\n## API Reference\n\nFor the API reference of this SDK please consult the [docs](docs/API.MD).\n\n## Usage\n\nAfter installation you just need to include the module in your own Javascript Program.\nThe module can be included using the following syntax:\n\n```javascript\nconst StaffBaseSSO = require('@staffbase/staffbase-plugin-sdk').sso;\n```\n## About secret token\nStaffbase backend support only RS256 algorithm of JWT which means that the secret\nyou should provide must be the content of public key in the `PKCS8` format.\nThis means your public key should start and end with tags:\n\n```\n-----BEGIN PUBLIC KEY-----\nBASE64 ENCODED DATA\n-----END PUBLIC KEY-----\n```\n\nYou can use the helper function to read and verify if your public key is in the supported format.\n```javascript\nconst helpers = require(`@staffbase/staffbase-plugin-sdk`).helpers;\nconst publicKeyPath = '[[Your File Path]]';\nlet keySecret;\ntry {\n\tkeySecret = helpers.readKeyFile(publicKeyPath);\n} catch (err) {\n\tconsole.log('Error Reading Key file', err);\n}\n```\n\nYou can then use keySecret to get an instance of StaffBaseSSO class.\n\n## Getting the SSOTokenData instance\nYou should have got your plugin id and Public Key file from Staffbase. After receiving the jwt token\nfrom the Staffbase backend, you can use the module to get the contents of the token.\n\n```javascript\nconst pluginId = '[As received from Staffbase]';\nconst publicKey = '[As received from Staffbase]';\nconst jwtToken = '[As received in current request via jwt query parameter]';\nlet tokenData = null;\ntry {\n\tlet SSOContents = new StaffBaseSSO(pluginId, publicKey, jwtToken);\n\ttokenData = SSOContents.getTokenData();\n\tconsole.log('Received token data:', tokenData);\n} catch(tokenErr) {\n \tconsole.error('Error decoding token:', tokenErr);\n}\n```\n\nIf no exception is thrown, you would get a SSOTokenData instance in the tokenData\nvariable which you can use to get contents of the SSO Token.\n\nThe following data can be retrieved from the token:\n\n|Helper Name|Token Key| Fetch Function| Description|\n| --- | --- | --- | --- |\n|CLAIM_BRANCH_ID|branch_id|getBranchId()|Get the branch ID for which the token was issued.|\n|CLAIM_BRANCH_SLUG|branch_slug|getBranchSlug()|Get the branch slug for which the token was issued.|\n|CLAIM_AUDIENCE|aud|getAudience()|Get targeted audience of the token.|\n|CLAIM_EXPIRE_AT|exp|getExpireAtTime()|Get the time when the token expires.|\n|CLAIM_NOT_BEFORE|nbf|getNotBeforeTime()|Get the time when the token starts to be valid.|\n|CLAIM_ISSUED_AT|iat|getIssuedAtTime()|Get the time when the token was issued.|\n|CLAIM_ISSUER|iss|getIssuer()|Get issuer of the token.|\n|CLAIM_INSTANCE_ID|instance_id|getInstanceId()|Get the (plugin) instance id for which the token was issued.|\n|CLAIM_INSTANCE_NAME|instance_name|getInstanceName()|Get the (plugin) instance name for which the token was issued.|\n|CLAIM_USER_ID|sub|getUserId()|Get the id of the authenticated user.|\n|CLAIM_USER_EXTERNAL_ID|external_id|getUserExternalId()|Get the id of the user in an external system.|\n|CLAIM_USER_USERNAME|username|getUserUsername()|Get the username of the user accessing.|\n|CLAIM_USER_PRIMARY_EMAIL_ADDRESS|primary_email_address|getUserPrimaryEmailAddress()|Get the primary email address of the user accessing.|\n|CLAIM_USER_FULL_NAME|name|getFullName()|Get either the combined name of the user or the name of the token.|\n|CLAIM_USER_FIRST_NAME|given_name|getFirstName()|Get the first name of the user accessing.|\n|CLAIM_USER_LAST_NAME|family_name|getLastName()|Get the last name of the user accessing.|\n|CLAIM_USER_ROLE|role|getRole()|Get the role of the accessing user.|\n|CLAIM_ENTITY_TYPE|type|getType()|Get the type of the token.|\n|CLAIM_THEME_TEXT_COLOR|theming_text|getThemeTextColor()|Get text color used in the overall theme for this audience.|\n|CLAIM_THEME_BACKGROUND_COLOR|theming_bg|getThemeBackgroundColor()|Get background color used in the overall theme for this audience.|\n|CLAIM_USER_LOCALE|locale|getLocale()|Get the locale of the requesting user in the format of language tags.|\n\nIt is not guaranteed that the token would contain information of all the keys.\nIf there is no value for the corresponding field, the SDK would return a `null` value.\n\n## Using with Express\nYou can use the provided helper middleware to simply mount it to your express\nserver and get an instance of SSOTokenData class in your Express request object.\n\nYou need to provide your *Secret Key* and *Plugin ID* to the middleware so it can decode the data.\nThe key can be provided in the constructor or by setting an Environment variables `STAFFBASE_SSO_SECRET` and `STAFFBASE_SSO_AUDIENCE` respectively.\n\nTo provide the key using constructor:\n```javascript\nconst ssoSecret = [[YOUR_PUBLIC_KEY_HERE]];\nconst SSOMiddleware = require('@staffbase/staffbase-plugin-sdk').middleware;\nlet ssoMiddleWare = ssoMiddleWare(ssoSecret);\n```\n\nAfter getting an instance of the middleware function, you can simply mount it to your\nSSO URL of the plugin. If the secret is fine and the middleware is able to decode the token,\nan instance of `SSOTokenData` can be used in `req.sbSSO`.\n\n```javascript\nconst ssoSecret = [[YOUR_PUBLIC_KEY_HERE]];\nconst SSOMiddleware = require('@staffbase/staffbase-plugin-sdk').middleware;\nlet ssoMiddleWare = SSOMiddleware(ssoSecret);\n\nconst redirectURL = '/staffbase/sso/backoffice';\nlet express = require('express');\nlet app = express();\n\n// Request Handler for client side of plugin\napp.use('/frontEnd', ssoMiddleWare);\napp.get('/frontEnd', function(req, res) {\n  if (req.sbSSO) {\n    // Render the decoded object using Express templating engine\n    return res.render('plugin', req.sbSSO);\n  }\n  return res.end(\"Unable to decode token data\");\n});\n\n// Apply middleware on the SSO URL\napp.use(redirectURL, ssoMiddleWare);\n// Your request handler for admin side of plugin below\napp.get(redirectURL, function(req, res) {\n  // Middleware was able to decode the token\n  // console.log('Got SSO Request from backend', req.query);\n  if (req.sbSSO) {\n    let ssoTokenData = req.sbSSO;\n    // Send back the token data back.\n    res.json(ssoTokenData);\n    return res.end();\n  }\n  res.json({\n    error: {\n      msg: \"Unable to get token information.\"\n    }\n  });\n  return res.end();\n});\n```\n\n### Generating Express Template\nYou can also use the `create-staffbase-plugin` CLI tool to start a template for a basic\nexpress server configured with the SDK. For more detail please check out the\n[Project Repo](https://github.com/Staffbase/create-staffbase-plugin-nodejs).\n\n\n## Contribution\n\n- Fork it\n- Create a branch `git checkout -b feature-description`\n- Put your name into authors.txt\n- Commit your changes `git commit -am \"Added ....\"`\n- Push to the branch `git push origin feature-description`\n- Open a Pull Request\n\n## Running Tests\n\nTo run the tests a simple `# npm test` command in the root directory will suffice. The tests are run using the Jest  framework. Please consult [jest](https://facebook.github.io/jest/) to learn more about writing unit tests for the plugin.\n\n## License\n\nCopyright 2017-2023 Staffbase GmbH.\n\nLicensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0\n\n\n\u003ctable\u003e\n      \u003ctr\u003e\n        \u003ctd\u003e\n          \u003cimg src=\"docs/assets/images/staffbase.png\" alt=\"Staffbase GmbH\" width=\"96\" /\u003e\n        \u003c/td\u003e\n        \u003ctd\u003e\n          \u003cb\u003eStaffbase GmbH\u003c/b\u003e\n          \u003cbr /\u003eStaffbase is an internal communications platform built to revolutionize the way you work and unite your company. Staffbase is hiring: \u003ca href=\"https://jobs.staffbase.com\" target=\"_blank\" rel=\"noreferrer\"\u003ejobs.staffbase.com\u003c/a\u003e\n          \u003cbr /\u003e\u003ca href=\"https://github.com/Staffbase\" target=\"_blank\" rel=\"noreferrer\"\u003eGitHub\u003c/a\u003e | \u003ca href=\"https://staffbase.com/\" target=\"_blank\" rel=\"noreferrer\"\u003eWebsite\u003c/a\u003e | \u003ca href=\"https://jobs.staffbase.com\" target=\"_blank\" rel=\"noreferrer\"\u003eJobs\u003c/a\u003e\n        \u003c/td\u003e\n      \u003c/tr\u003e\n    \u003c/table\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstaffbase%2Fplugins-sdk-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstaffbase%2Fplugins-sdk-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstaffbase%2Fplugins-sdk-nodejs/lists"}