Skip to content

Commit e0e91b7

Browse files
CopilotmaximizeIT
Copilot
and
maximizeIT
committed
Fix dependabot security alerts: update handlebars, flatted, minimatch, lodash, picomatch, cross-spawn
- Update handlebars devDependency from ^4.7.7 to ^4.7.9 (fixes 5 CVEs) - Run npm audit fix: flatted 3.3.3→3.4.2, minimatch 3.1.2→3.1.5, lodash 4.17.21→4.17.23, picomatch 2.3.1→2.3.2, and others - Add overrides.cross-spawn >=7.0.6 to fix pre-commit vulnerability All 76 tests pass, lint clean, npm audit reports 0 vulnerabilities. Co-authored-by: GitHub Copilot <copilot@noreply.github.com> Agent-Logs-Url: https://github.com/Staffbase/plugins-sdk-nodejs/sessions/8211c93b-6881-49da-8e5a-efa8ac6e3a76 Co-authored-by: maximizeIT <8626039+maximizeIT@users.noreply.github.com>
1 parent 9544a85 commit e0e91b7

3 files changed

Lines changed: 236 additions & 91 deletions

File tree

‎README.MD‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
[![Build Status](https://github.com/Staffbase/plugins-sdk-nodejs/workflows/Node.js%20CI/badge.svg)](https://github.com/Staffbase/plugins-sdk-nodejs/actions)
2+
3+
# Staffbase Plugins SDK for Node.js.
4+
5+
If 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.
6+
7+
8+
## Installation
9+
10+
The 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.
11+
12+
npm install (@staffbase/staffbase-plugin-sdk)
13+
14+
You can also save the module as a local dependency in your project package.json file with the following command:
15+
16+
npm install --save (@staffbase/staffbase-plugin-sdk)
17+
18+
19+
## API Reference
20+
21+
For the API reference of this SDK please consult the [docs](docs/API.MD).
22+
23+
## Usage
24+
25+
After installation you just need to include the module in your own Javascript Program.
26+
The module can be included using the following syntax:
27+
28+
```javascript
29+
const StaffBaseSSO = require('@staffbase/staffbase-plugin-sdk').sso;
30+
```
31+
## About secret token
32+
Staffbase backend support only RS256 algorithm of JWT which means that the secret
33+
you should provide must be the content of public key in the `PKCS8` format.
34+
This means your public key should start and end with tags:
35+
36+
```
37+
-----BEGIN PUBLIC KEY-----
38+
BASE64 ENCODED DATA
39+
-----END PUBLIC KEY-----
40+
```
41+
42+
You can use the helper function to read and verify if your public key is in the supported format.
43+
```javascript
44+
const helpers = require(`@staffbase/staffbase-plugin-sdk`).helpers;
45+
const publicKeyPath = '[[Your File Path]]';
46+
let keySecret;
47+
try {
48+
keySecret = helpers.readKeyFile(publicKeyPath);
49+
} catch (err) {
50+
console.log('Error Reading Key file', err);
51+
}
52+
```
53+
54+
You can then use keySecret to get an instance of StaffBaseSSO class.
55+
56+
## Getting the SSOTokenData instance
57+
You should have got your plugin id and Public Key file from Staffbase. After receiving the jwt token
58+
from the Staffbase backend, you can use the module to get the contents of the token.
59+
60+
```javascript
61+
const pluginId = '[As received from Staffbase]';
62+
const publicKey = '[As received from Staffbase]';
63+
const jwtToken = '[As received in current request via jwt query parameter]';
64+
let tokenData = null;
65+
try {
66+
let SSOContents = new StaffBaseSSO(pluginId, publicKey, jwtToken);
67+
tokenData = SSOContents.getTokenData();
68+
console.log('Received token data:', tokenData);
69+
} catch(tokenErr) {
70+
console.error('Error decoding token:', tokenErr);
71+
}
72+
```
73+
74+
If no exception is thrown, you would get a SSOTokenData instance in the tokenData
75+
variable which you can use to get contents of the SSO Token.
76+
77+
The following data can be retrieved from the token:
78+
79+
|Helper Name|Token Key| Fetch Function| Description|
80+
| --- | --- | --- | --- |
81+
|CLAIM_BRANCH_ID|branch_id|getBranchId()|Get the branch ID for which the token was issued.|
82+
|CLAIM_BRANCH_SLUG|branch_slug|getBranchSlug()|Get the branch slug for which the token was issued.|
83+
|CLAIM_AUDIENCE|aud|getAudience()|Get targeted audience of the token.|
84+
|CLAIM_EXPIRE_AT|exp|getExpireAtTime()|Get the time when the token expires.|
85+
|CLAIM_NOT_BEFORE|nbf|getNotBeforeTime()|Get the time when the token starts to be valid.|
86+
|CLAIM_ISSUED_AT|iat|getIssuedAtTime()|Get the time when the token was issued.|
87+
|CLAIM_ISSUER|iss|getIssuer()|Get issuer of the token.|
88+
|CLAIM_INSTANCE_ID|instance_id|getInstanceId()|Get the (plugin) instance id for which the token was issued.|
89+
|CLAIM_INSTANCE_NAME|instance_name|getInstanceName()|Get the (plugin) instance name for which the token was issued.|
90+
|CLAIM_USER_ID|sub|getUserId()|Get the id of the authenticated user.|
91+
|CLAIM_USER_EXTERNAL_ID|external_id|getUserExternalId()|Get the id of the user in an external system.|
92+
|CLAIM_USER_USERNAME|username|getUserUsername()|Get the username of the user accessing.|
93+
|CLAIM_USER_PRIMARY_EMAIL_ADDRESS|primary_email_address|getUserPrimaryEmailAddress()|Get the primary email address of the user accessing.|
94+
|CLAIM_USER_FULL_NAME|name|getFullName()|Get either the combined name of the user or the name of the token.|
95+
|CLAIM_USER_FIRST_NAME|given_name|getFirstName()|Get the first name of the user accessing.|
96+
|CLAIM_USER_LAST_NAME|family_name|getLastName()|Get the last name of the user accessing.|
97+
|CLAIM_USER_ROLE|role|getRole()|Get the role of the accessing user.|
98+
|CLAIM_ENTITY_TYPE|type|getType()|Get the type of the token.|
99+
|CLAIM_THEME_TEXT_COLOR|theming_text|getThemeTextColor()|Get text color used in the overall theme for this audience.|
100+
|CLAIM_THEME_BACKGROUND_COLOR|theming_bg|getThemeBackgroundColor()|Get background color used in the overall theme for this audience.|
101+
|CLAIM_USER_LOCALE|locale|getLocale()|Get the locale of the requesting user in the format of language tags.|
102+
103+
It is not guaranteed that the token would contain information of all the keys.
104+
If there is no value for the corresponding field, the SDK would return a `null` value.
105+
106+
## Using with Express
107+
You can use the provided helper middleware to simply mount it to your express
108+
server and get an instance of SSOTokenData class in your Express request object.
109+
110+
You need to provide your *Secret Key* and *Plugin ID* to the middleware so it can decode the data.
111+
The key can be provided in the constructor or by setting an Environment variables `STAFFBASE_SSO_SECRET` and `STAFFBASE_SSO_AUDIENCE` respectively.
112+
113+
To provide the key using constructor:
114+
```javascript
115+
const ssoSecret = [[YOUR_PUBLIC_KEY_HERE]];
116+
const SSOMiddleware = require('@staffbase/staffbase-plugin-sdk').middleware;
117+
let ssoMiddleWare = ssoMiddleWare(ssoSecret);
118+
```
119+
120+
After getting an instance of the middleware function, you can simply mount it to your
121+
SSO URL of the plugin. If the secret is fine and the middleware is able to decode the token,
122+
an instance of `SSOTokenData` can be used in `req.sbSSO`.
123+
124+
```javascript
125+
const ssoSecret = [[YOUR_PUBLIC_KEY_HERE]];
126+
const SSOMiddleware = require('@staffbase/staffbase-plugin-sdk').middleware;
127+
let ssoMiddleWare = SSOMiddleware(ssoSecret);
128+
129+
const redirectURL = '/staffbase/sso/backoffice';
130+
let express = require('express');
131+
let app = express();
132+
133+
// Request Handler for client side of plugin
134+
app.use('/frontEnd', ssoMiddleWare);
135+
app.get('/frontEnd', function(req, res) {
136+
if (req.sbSSO) {
137+
// Render the decoded object using Express templating engine
138+
return res.render('plugin', req.sbSSO);
139+
}
140+
return res.end("Unable to decode token data");
141+
});
142+
143+
// Apply middleware on the SSO URL
144+
app.use(redirectURL, ssoMiddleWare);
145+
// Your request handler for admin side of plugin below
146+
app.get(redirectURL, function(req, res) {
147+
// Middleware was able to decode the token
148+
// console.log('Got SSO Request from backend', req.query);
149+
if (req.sbSSO) {
150+
let ssoTokenData = req.sbSSO;
151+
// Send back the token data back.
152+
res.json(ssoTokenData);
153+
return res.end();
154+
}
155+
res.json({
156+
error: {
157+
msg: "Unable to get token information."
158+
}
159+
});
160+
return res.end();
161+
});
162+
```
163+
164+
### Generating Express Template
165+
You can also use the `create-staffbase-plugin` CLI tool to start a template for a basic
166+
express server configured with the SDK. For more detail please check out the
167+
[Project Repo](https://github.com/Staffbase/create-staffbase-plugin-nodejs).
168+
169+
170+
## Contribution
171+
172+
- Fork it
173+
- Create a branch `git checkout -b feature-description`
174+
- Put your name into authors.txt
175+
- Commit your changes `git commit -am "Added ...."`
176+
- Push to the branch `git push origin feature-description`
177+
- Open a Pull Request
178+
179+
## Running Tests
180+
181+
To 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.
182+
183+
## License
184+
185+
Copyright 2017-2023 Staffbase GmbH.
186+
187+
Licensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0
188+
189+
190+
<table>
191+
<tr>
192+
<td>
193+
<img src="docs/assets/images/staffbase.png" alt="Staffbase GmbH" width="96" />
194+
</td>
195+
<td>
196+
<b>Staffbase GmbH</b>
197+
<br />Staffbase is an internal communications platform built to revolutionize the way you work and unite your company. Staffbase is hiring: <a href="https://jobs.staffbase.com" target="_blank" rel="noreferrer">jobs.staffbase.com</a>
198+
<br /><a href="https://github.com/Staffbase" target="_blank" rel="noreferrer">GitHub</a> | <a href="https://staffbase.com/" target="_blank" rel="noreferrer">Website</a> | <a href="https://jobs.staffbase.com" target="_blank" rel="noreferrer">Jobs</a>
199+
</td>
200+
</tr>
201+
</table>
202+

0 commit comments

Comments
 (0)