Token auth – PUBQ

Token auth

Token authentication uses a trusted device with an API key to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as capabilities, and can have a specific identity using a clientId.

Token authentication is the recommended authentication method to use client-side as it provides more fine-grained access control and limits the risk of credentials being exposed.

The following cause an SDK to use token authentication:

An authUrl, refreshUrl, and revokeUrl is provided that returns a PUBQ-compatible token.

Token auth architecture

The diagram below illustrates the authentication process used by PUBQ SDKs to authenticate with PUBQ using token authentication:

Using token auth on client

You can specify an authUrl, refreshUrl, and revokeUrl when you create the PUBQ client. For example:

const realtime = new Pubq.RealTime({
    authUrl: "http://example.com/auth",
    refreshUrl: "http://example.com/refresh",
    revokeUrl: "http://example.com/revoke",
});

The client will obtain a JWT token from the URL and use it to authenticate requests to PUBQ.

Refresh token

One of the important benefits of using a PUBQ SDK is that the automatic refresh of tokens will be handled for you.

To use automatic refresh of tokens, provide an refreshUrl. When the token is near to expiry the refreshUrl is invoked and a new token is automatically requested. If you want to disable automatic refresh, set autoRefreshToken to false.

Revoke token

Use token revocation to invalidate authentication tokens. This invalidation can be used to force specified clients to re-obtain a token, and subsequently enables the app to modify the rights granted to clients, or to decline to re-issue a token.

To use token revocation on client-side, provide an revokeUrl.

Options

You can use the following options to set custom body and headers to pass along with authUrl, refreshUrl, and revokeUrl requests, when instantiating a client.

authBody: Allows you to pass additional body parameters as required, depending on your use case.
authHeaders: Allows you to pass additional headers as required, depending on your use case.

const realtime = new Pubq.RealTime({
    authUrl: "http://example.com/auth",
    refreshUrl: "http://example.com/refresh",
    revokeUrl: "http://example.com/revoke",
    authBody: {
        key: "value",
        anotherKey: "another value",
    },
    authHeaders: {
        header1: "header 1",
        header2: "header 2",
    }
});

Issue tokens on server

Using a PUBQ SDK, a PUBQ Token is requested by your servers from PUBQ and then passed to the client-side SDK instance. The client-side SDK instance then uses the obtained PUBQ Token to authenticate with PUBQ.

const rest = new Pubq.REST({ key: "q4D9G2.rGQK1W:9pWbndVJg50MaOPAapAx7LQ_zKw6YvXl2B" });
const response = rest.generateToken({ clientId: "John" });

PUBQ Token response body that should be returned by the server to the client SDK instance:

{
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL3Jlc3QucHVicS5pby92MS9rZXlzL3Rva2VucyIsImlhdCI6MTcwMjY0MTQ2MywiZXhwIjoxNzAyNjQ1MDYzLCJuYmYiOjE3MDI2NDE0NjMsImp0aSI6IkNBNG91R1hsQXMyWG0wOXIiLCJzdWIiOiJsWjdyNGoubFo3cjRqIiwicGVybWlzc2lvbnMiOlsiKiJdLCJyZXN0cmljdGlvbnMiOm51bGwsImNsaWVudElkIjoiSm9obiJ9.NJ7u0U0PRLsgV7HuWB4P5NA8WDklWcxgA3t92d9iOog",
        "token_type": "Bearer",
        "expires_in": 1702645063
    }
}

When to use token auth

PUBQ recommends that token authentication is used client-side for the following reasons:

Tokens ensure that a PUBQ API key isn’t exposed in client applications.
Tokens are short-lived so there is only a short period of time during which a compromised token can be used.
Tokens provide more fine-grained access control, which also limits the area of exposure a compromised token can access.

NOTE

When selecting a PUBQ SDK for implementing token authentication with PUBQ, you don’t need to use the realtime interface on the auth server.

As basic authentication is primarily designed for authenticating a secure server, in this situation, and assuming the server is only used for authentication, it is more efficient to use the REST interface, as the overhead associated with maintaining a realtime connection, is not required to issue tokens.

Authentication: Identified clients

Explains how to allocate a client ID to identify the client.