Getting Started with Authentication Functions

Authentication in Glee can be implemented using authentication functions. These functions are files that export one or both of the following Node.js functions: clientAuth and serverAuth:

1/* websocket.js */
2
3export async function serverAuth({ authProps, done }) {
4  // Server authentication logic
5}
6
7export async function clientAuth({ parsedAsyncAPI, serverName }) {
8  // Client authentication logic
9}

Glee searches for authentication files in the auth directory by default. However, this can be configured using the glee config file. The authentication file's name should match the targeted server for which the authentication logic is intended.

Supported Authentication Values in the asyncapi.yaml File

AsyncAPI supports a variety of authentication formats as specified in its documentation. Glee, however, supports the following authentication schemas:

• userPassword
• http ("bearer")
• httpApiKey
• Oauth2

Below is an example of a asyncapi.yaml file for a server with security requirements and a userPassword security scheme:

1## Server AsyncAPI Schema
2asyncapi: 3.0.0
3info:
4  title: AsyncAPI IMDB Server
5  version: 1.0.0
6  description: This app is a dummy server that streams trending/upcoming anime.
7servers:
8  trendingAnimeServer:
9    host: 'localhost:8081'
10    protocol: http
11    security:
12      - $ref: '#/components/securitySchemes/userPass'
13
14  ...
15
16components:
17  securitySchemes:
18    userPass:
19      type: userPassword

Here's an example for a client that implements some requirements of the server mentioned above:

1## Client AsyncAPI Schema
2servers:
3  trendingAnime:
4    host: localhost:8081
5    protocol: http
6    security:
7      - $ref: '#/components/securitySchemes/userPass'
8  testwebhook:
9    host: localhost:9000
10    protocol: ws
11x-remoteServers:
12  - trendingAnime
13
14  ...
15
16components:
17  securitySchemes:
18    userPass:
19      type: userPassword

Glee can function as both a server and a client. Hence, the need for both serverAuth and clientAuth functions arises. Glee acts as a client when the server name is included in the x-remoteServers property in the asyncapi.yaml file.

When Glee operates as a client, it can connect to a Glee server. Conversely, as a server, it accepts connections from other Glee clients. Thus, a Glee application can accept connections from clients while also sending requests to other Glee servers.

If a security requirement is specified in the asyncapi.yaml file, and Glee acts as a server, the serverAuth function should be implemented. If Glee acts as a client, then clientAuth should be implemented. If Glee is used as both client and server, both functions are necessary.

Server Authentication in Glee

The serverAuth function takes an argument that can be destructured as follows:

done() Function

The done() parameter in the serverAuth function signals to the broker/server what action to take next, based on the boolean value passed.

1/* websocket.js */
2
3export async function serverAuth({ authProps, done }) {
4  if (isValidUser(authProps)) {
5    done(true);
6  } else {
7    done(false);
8  }
9}

Parameters for done():

• Authentication Result (Boolean): true for success, false for failure.

Passing true to the done parameter indicates that authentication has succeeded, and the server/broker can proceed to allow the client to connect. Conversely, if false is passed, the server will reject the client, indicating failed authentication.

The done() call should always be the last in the serverAuth function, as Glee will not execute any logic beyond this call.

authProps

The authProps parameter includes methods for the server to retrieve authentication parameters from the client. The current available methods are as follows:

1export async function serverAuth({ authProps, done }) {
2  // Some network request
3  authProps.getOauthToken()
4  authProps.getHttpAPIKeys('api_key')
5  authProps.getToken()
6  authProps.getUserPass()
7
8  done(false)
9}

Client Authentication in Glee

The clientAuth function also takes an argument that can be destructured as follows:

Possible Authentication Parameters

The code snippet below illustrates the possible authentication parameters:

1export async function clientAuth({ serverName }) {
2  return {
3    token: process.env.TOKEN,
4    oauth: process.env.OAUTH2,
5    apiKey: process.env.APIKEY,
6    userPass: {
7      user: process.env.USER,
8      password: process.env.PASSWORD,
9    },
10  }
11}

The names of the authentication parameters should match the names specified in the asyncapi.yaml file.