Using the PureWeb SDK to provide authenticated stream access

On the PureWeb platform, there are a number of different ways to provide access to your model:

1. Enabling anonymous access to your project
2. Revokable sharing links
3. Secure access through a 3rd party authentication provider
4. There also exists a 4th authentication option, which is to perform user authentication in-game, where any user can launch a stream for your public model, but they are prompted to provide a username and password within the game itself, thereby providing access to the content of your model.  While this approach would allow potentially untrusted parties to launch a stream of your model, it could still ensure that only authenticated users can access the core content of your experience

This guide will be addressing the 3rd option.  Please note, this workflow assumes that you’re using a custom PureWeb client.

When we talk about providing secure access to a stream using a 3rd party authentication provider, we are talking about how you can use the PureWeb SDK to request individual session tokens to users you’ve authenticated against the auth system of your choosing, ensuring only users that are known to you and authenticated can launch a stream.

Figure 1. Diagram showing the key entities involved in securely accessing a PureWeb stream.

In the 3rd party auth scenario, you will have some sort of authentication user workflow, the specifics of this workflow will differ depending on your organization, use case and other factors.  You might want users to login with a username and password, or your organizational SSO, or some other mechanism entirely.  In Figure 1. Above, this starts at the login page (1).  This could be a pre-existing login page, or even something you build into your custom client (2).  Regardless, this is where your users will provide the necessary credentials to you to begin the authentication process.

Next, you will have some custom code or service (3) that takes the credentials that were provided and validates them against your identity provider (4).  You may not have an identity provider, this could easily be a user database if you’re using simple username / password for authentication.

Now it’s time for the key element.  Once you have authenticated your users against whatever authentication scheme you have created, you’ll want to request that the PureWeb platform creates an individual session token for this user.  This can be done in your authentication service (3) if it’s JavaScript compatible, or you could create a simple token requestor service to request PureWeb tokens.  Regardless of the approach taken, the following PureWeb SDK code will procure a session token.

//necessary imports
const PlatformAdmin = require("@pureweb/platform-admin-sdk").default;
const { PlatformApi } = require("@pureweb/platform-admin-sdk");

//client ID, secret can be found in your project settings in the pureweb console
const clientId = process.env.PUREWEB_PROJECT_CLIENT_ID;
const clientSecret = process.env.PUREWEB_PROJECT_CLIENT_SECRET;
const url = “https://api.pureweb.io”;

//create a new API object
const api = new PlatformApi({ baseUrl: url });

//define the permissions needed for the token
const project = await api.getAccessToken(clientId, clientSecret, [
  'launch_request:*',
  'model:read',
]);

//create a new Admin API
const admin = new PlatformAdmin(clientId, 
  clientSecret, 
  {
    platformUrl: url,
    debug: true
});

//Generate a new agent access token
await admin.authenticate();
const environmentId = (await admin.createAgentEnvironment()).id;
const agent = await admin.createAgentToken(environmentId);

Now with a token in hand, you can simply append the `?token=<your new token>` to the end of your PureWeb stream launch URL when accessing a private model, and you will have given access to your user to launch your model.

Please note, session tokens only have a lifespan of 1 hour, so it’s best practice to generate a fresh token every time a user returns to your site.

To see an example of this workflow in action, we have a public git repository that shows how to request these tokens, using Auth0 as the backend identity framework.  Check it out here: https://github.com/pureweb/platform-auth-example.