Authorization

cyxth uses json webtokens to authorize user access to your instance. this guide shows you how to authorize user access to your cyxth instance.

public key generation

we use EdDSA public keys to verify a user has been authorized to access your instance. when you first create your cyxth instance you are required to provide an EdDSA public key. here is how you can easily generate a keypair with the openssl commandline utility.

# generate private key
openssl genpkey -algorithm ed25519 -out private.pem

# public key
openssl pkey -in private.pem -pubout -out public.pem

cat public.pem

# you get something similar to
#-----BEGIN PUBLIC KEY-----
#MCowBQYDK2VwAyEA3gR3WPqDIUNaSMdxD0f2DJtvBtpGkWLlEPGJcNfni00=
#-----END PUBLIC KEY-----

# copy the entire key includeing the head and tail

json webtokens

in your backend using any Jwt library that supports EdDSA keys you can sign the user info. the user info is defined as.

interface UserInfo {
 /**
  * user id, this is the only required field
  */
 id: string;
 /**
  * whether this user's data should  be saved,
  * all the other fields will be ignored if true
  */
 isTemporary?: boolean;
 /**
  * join given channels on authorized. these channels has the devloper as the sole admin
  */
 channels?: InitialChannel[];
 /**
  * user access level across the instance by default editor
  */
 access?: 'admin' | 'viewer' | 'editor' | 'no-access';
}

interface InitialChannel {
 /** channel id */
 id: string;
 /** user access level in channel */
 mode?: 'admin' | 'viewer' | 'editor' | 'no-access';
}

only the id is required if the user id is already registered. use our REST API to register all your users before user login.

sign the user info using any Jwt library and pass the token to the @cyxth/core connect() function. here is an example with node jwt library jose.

import { SignJWT, importPKCS8 } from 'jose';

const user = { id: "alice" };
const importedKey = await importPKCS8("YOUR_PRIVATE_KEY", 'EdDSA');
const token = await new SignJWT({ ...user })
   .setProtectedHeader({ alg: 'EdDSA' })
   .setExpirationTime(options?.duration || '2h')
   .sign(importedKey);

console.log(token)

cyxth provides @cyxth/auth library for node and js backends that does these for you. more will be availble for other backends.

a simple auth service

This simple guide will show you how to authenticate users with a simple nodejs/express service using @cyxth/auth npm package.

this and other examples are in the cyxth examples repository here. you can clone the repo and run the examples locally or follow a long this tutorial.

If you are not using nodejs feel free to skip this section and checkout the authentication examples repo on github to implement it using your language of choice.

mkdir auth-service && cd auth-service
npm init -y
touch server.js
npm i express cors body-parser @cyxth/auth

Add this code to your server.js

import Auth from '@cyxth/auth';

import express from 'express';
import * as BodyParser from 'body-parser';
import * as cors from 'cors';

const APP_ID = 'YOUR_APP_ID';
const APP_SECRET = 'YOUR_PRIVATE_KEY';

const app = express();
app.use(BodyParser.default.json());
app.use(cors.default());

const auth = new Auth(APP_ID, APP_SECRET);

// auth
app.post('/authorize', async (req, res) => {
  let data = req.body;
  let tokenData = await auth.createToken({ id: data.id }, { pkce: true });
  res.json(tokenData);
});

app.listen(8902, () => console.log('started auth server on port 8902'));

start the server

$ node server.js
started server on port 8902

Let’s test the service with cURL.

$ curl -X POST http://localhost:8902/authorize
    -H 'Content-Type: application/json'
    -d '{"id":"alice"}'

{
 "token": "eyJ***some long jwt token***0",
 "code_challenge": "i81I46-EhLtn_o_wW5baaDk8YdM7pXyRjJFXDSvO27Q",
 "code_verifier": "WfQ_oNtNFRrtTKPu2VkLt7ocj6NU2CVvcUAIaRe_Rwg"
}
#  your values will be obviously different

deploy this simple service or integrate it with your backend to authorize users i.e on login or navigation to a chat, colab or calls page.