2
1
mirror of https://github.com/Thream/socketio-jwt.git synced 2024-07-21 09:38:31 +02:00
socketio-jwt/README.md

164 lines
5.2 KiB
Markdown
Raw Normal View History

2021-01-07 05:45:46 +01:00
<h1 align="center">Thream/socketio-jwt</h1>
2019-07-23 15:22:23 +02:00
<p align="center">
<strong>Authenticate socket.io incoming connections with JWTs.</strong>
</p>
2015-05-29 14:42:14 +02:00
<p align="center">
2021-07-23 23:15:52 +02:00
<a href="./CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/licence-MIT-blue.svg" alt="Licence MIT"/></a>
2021-07-23 23:15:52 +02:00
<a href="./CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg" alt="Contributor Covenant" /></a>
<br/>
<a href="https://github.com/Thream/socketio-jwt/actions/workflows/build.yml"><img src="https://github.com/Thream/socketio-jwt/actions/workflows/build.yml/badge.svg?branch=develop" /></a>
<a href="https://github.com/Thream/socketio-jwt/actions/workflows/lint.yml"><img src="https://github.com/Thream/socketio-jwt/actions/workflows/lint.yml/badge.svg?branch=develop" /></a>
<a href="https://github.com/Thream/socketio-jwt/actions/workflows/test.yml"><img src="https://github.com/Thream/socketio-jwt/actions/workflows/test.yml/badge.svg?branch=develop" /></a>
<br />
<a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg" alt="Conventional Commits" /></a>
2021-07-23 23:15:52 +02:00
<a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="semantic-release" /></a>
<a href="https://www.npmjs.com/package/@thream/socketio-jwt"><img src="https://img.shields.io/npm/v/@thream/socketio-jwt.svg" alt="npm version"></a>
</p>
2019-07-16 11:33:44 +02:00
## 📜 About
2019-07-16 11:33:44 +02:00
Authenticate socket.io incoming connections with JWTs.
2012-09-05 20:14:36 +02:00
2021-01-07 14:30:37 +01:00
Compatible with `socket.io >= 3.0.0`.
2020-12-29 04:30:34 +01:00
This repository was originally forked from [auth0-socketio-jwt](https://github.com/auth0-community/auth0-socketio-jwt) & it is not intended to take any credit but to improve the code from now on.
2019-01-15 17:43:44 +01:00
## Prerequisites
- [Node.js](https://nodejs.org/) >= 16.0.0
2020-12-29 04:30:34 +01:00
## 💾 Install
2019-01-15 17:43:44 +01:00
**Note:** It is a package that is recommended to use/install on both the client and server sides.
```sh
2020-12-29 04:30:34 +01:00
npm install --save @thream/socketio-jwt
2012-09-05 20:14:36 +02:00
```
## ⚙️ Usage
2012-09-05 20:14:36 +02:00
2020-12-29 04:30:34 +01:00
### Server side
2020-12-29 04:30:34 +01:00
```ts
import { Server } from 'socket.io'
import { authorize } from '@thream/socketio-jwt'
2020-12-29 04:30:34 +01:00
const io = new Server(9000)
2020-12-27 17:25:44 +01:00
io.use(
2020-12-29 04:30:34 +01:00
authorize({
secret: 'your secret or public key'
2020-12-27 17:25:44 +01:00
})
)
io.on('connection', async (socket) => {
// jwt payload of the connected client
console.log(socket.decodedToken)
2020-12-29 04:30:34 +01:00
const clients = await io.sockets.allSockets()
if (clients != null) {
for (const clientId of clients) {
const client = io.sockets.sockets.get(clientId)
client?.emit('messages', { message: 'Success!' })
// we can access the jwt payload of each connected client
console.log(client?.decodedToken)
}
}
2020-12-27 17:25:44 +01:00
})
```
2021-01-07 14:30:37 +01:00
### Server side with `jwks-rsa` (example)
```ts
import jwksClient from 'jwks-rsa'
import { Server } from 'socket.io'
import { authorize } from '@thream/socketio-jwt'
const client = jwksClient({
jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'
})
const io = new Server(9000)
io.use(
authorize({
secret: async (decodedToken) => {
const key = await client.getSigningKeyAsync(decodedToken.header.kid)
return key.getPublicKey()
2021-01-07 14:30:37 +01:00
}
})
)
io.on('connection', async (socket) => {
// jwt payload of the connected client
console.log(socket.decodedToken)
// You can do the same things of the previous example there...
})
```
### Server side with `onAuthentication` (example)
```ts
import { Server } from 'socket.io'
import { authorize } from '@thream/socketio-jwt'
const io = new Server(9000)
io.use(
authorize({
secret: 'your secret or public key',
onAuthentication: async (decodedToken) => {
2021-03-08 14:33:53 +01:00
// return the object that you want to add to the user property
// or throw an error if the token is unauthorized
}
})
)
io.on('connection', async (socket) => {
// jwt payload of the connected client
console.log(socket.decodedToken)
// You can do the same things of the previous example there...
// user object returned in onAuthentication
console.log(socket.user)
})
```
2021-02-18 20:14:56 +01:00
### `authorize` options
- `secret` is a string containing the secret for HMAC algorithms, or a function that should fetch the secret or public key as shown in the example with `jwks-rsa`.
- `algorithms` (default: `HS256`)
2021-03-08 14:33:53 +01:00
- `onAuthentication` is a function that will be called with the `decodedToken` as a parameter after the token is authenticated. Return a value to add to the `user` property in the socket object.
2021-02-18 20:14:56 +01:00
2020-12-29 04:30:34 +01:00
### Client side
2020-12-29 04:30:34 +01:00
```ts
import { io } from 'socket.io-client'
import { isUnauthorizedError } from '@thream/socketio-jwt'
// Require Bearer Token
2020-12-29 04:30:34 +01:00
const socket = io('http://localhost:9000', {
auth: { token: `Bearer ${yourJWT}` }
2020-12-27 17:25:44 +01:00
})
2020-12-29 04:30:34 +01:00
// Handling token expiration
socket.on('connect_error', (error) => {
if (isUnauthorizedError(error)) {
2020-12-27 17:25:44 +01:00
console.log('User token has expired')
}
2020-12-27 17:25:44 +01:00
})
2020-12-29 04:30:34 +01:00
// Listening to events
socket.on('messages', (data) => {
console.log(data)
2020-12-27 17:25:44 +01:00
})
```
## 💡 Contributing
2020-12-27 17:25:44 +01:00
Anyone can help to improve the project, submit a Feature Request, a bug report or even correct a simple spelling mistake.
2020-12-27 17:25:44 +01:00
2021-03-08 14:33:53 +01:00
The steps to contribute can be found in the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
2019-01-15 17:43:44 +01:00
## 📄 License
2019-01-15 17:43:44 +01:00
[MIT](./LICENSE)