Auth and onboarding

UG AI Engine for children

Authentication and onboarding

Note: This section is very technical and aimed for application developers. For interaction designers, feel free to skip this section and move to the Interaction page.

User onboarding

To be able to access PUG to develop experiences, the developer first needs to have a user account associated with their email address (can be done by navigating to https://pug-playground.stg.uglabs.app and signing up).

Once such an account is created, PUG can be accessed in one of two ways:

Using Google Single Sign-On (SSO)

Using an API key

Teams

To enable the same user to collaborate on different PUG resources with different groups of users, PUG implements a “team” concept. Every persistent resource in PUG is associated with a team, and all users within a team share the same permissions to all the team resources. Note that team names are globally unique.

Every time a user logs-in to PUG (using one of the methods above), they can specify a team name. When unspecified, PUG will select any of the teams the user belongs to. As most users will likely only belong to one team, this should work for most users as expected. For users belonging to multiple teams, specifying the team name is strongly advised.

Service Accounts

Service accounts are special types of users that are not associated with an email address and thus can only login to the system with API keys. Service accounts currently be broken down to two main types:

Private API Key service accounts - service accounts whose API key should be kept private, and have the full privileges of a user. These should mainly be used for automations

Public API Key service accounts - service accounts whose API keys can be embedded into apps and are thus public.

Player vs. User

Entities using PUG to develop experiences (“developers”) are referred to as users, whereas consumers of experiences are referred to as players. There’s a basic distinction between the two in terms of permissions:

Users have full access to the PUG APIs, within the scope of resources associated with their team(s)

Players have read-only access to resources, and will typically only use the Interaction session endpoint from within the experience

Unlike users that share access to certain resources (within a team), players are completely isolated from one another. No action or conversation history made by one player will be available to any other player.

Player onboarding and authentication

Overview

💡

We've created an easy way for you to create service accounts - sign up here https://pug-playground.stg.uglabs.app

And click on create a new service account

First, the developer creates a public API service-account by creating a user (once) to obtain an API key for the experience:

Then, upon registration of the player, the developer chooses the external ID for the player, and using a secret on their backend sends a “create player” request to PUG. The request returns a federated ID that is sent back the player:

Finally, on every login the player uses a combination of the public API key and the federated ID to perform their login:

In more depth

When creating the experience, the developer user creates a service account user, with the user_type of playerlogin This service account will then have an API key that can later be used to login players

This API key will not have permissions to make any other changes in PUG
Thus it’s safe to send this API key to the player devices

When the player completes the experience-specific registration flow, the backend of the user will send a “create player” request to PUG with an “external identifier” of the user

For example, this could be an email address that may have been validated in one way or another. PUG makes no validation on these identifiers
This creation request can be sent either using the credentials of a “person” user, or using a service account with a private API key

Private API key = Without the can_login_as_player attribute

Once the player is created, it will be associated with a federated ID that can be returned to the app/web-page for further authentication

This multi-stage authentication flow is used to achieve two distinct security features:

Preventing uncontrolled creation of player objects in the system using credentials that are available in the app/web-page (such as the public API key), by requiring a secret known only to the backend

Preventing impersonation in case the external identifier is publicly known (such as email addresses), by requiring a secret ID on authentication instead of the external ID

Player Creation & Authentication

Players are yet another type of resource in PUG, and are assigned to a team at creation, based on their creation request. The main action performed by players is interaction (i.e. starting a conversation), where each interaction may start fresh or continue a previously saved conversation. Players are completely isolated from one another and can only access their own previous conversations, not conversations of other players.

Within a team, every player is identified by a unique external ID which is assigned to them by the user who created them.

To enable players to login to the system, a user (app developer) should do the following:

Create a service account with the special role playerLogin (this needs to be done only once)

Per player that should have access to PUG, a player creation request must be made in advance. This request receives the external identifier, and returns a federated ID - a unique secret allocated by PUG

Finally, the player can login to PUG using the API key of the playerLogin service account and their own federated ID

The reason for the indirection of the login through federated IDs (instead of using the external ID on the login request) is to prevent impersonation and data leaks:

We assume that in some cases, the external ID chosen by the systems creating the players may be an email addresses or some other easy-to-guess identifier.

To avoid enumeration on these identifiers in order to access conversations by other players, we allocate our own hard-to-guess identifier

While the API key of the playerLogin service account can be embedded in advance directly in the code interacting with PUG from the client device, the player creation needs to happen dynamically.

We support two main ways of achieving this:

Managed registration - the client on the player device interacts with a dedicated backend in order to perform the registration/identification (for example, verifying an email address, sending an SMS to a phone number, etc.) and then that backend will create the player and return the federated ID to the player device.

💡

To clarify, the registration backend would be a backend maintained separately from PUG, by the team of users developing the experience

This registration is managed since player creation can only happen using the dedicated backend in a controlled manner.

This is the preferred safe way to implement players login

Open registration - instead of maintaining a backend, the user will create a special service account with the playerCreate role, and also embed that API key in the application

The application can then login once to create the player and obtain the federated ID, and then another time using the federated ID as the player.

Users that only have this role cannot do anything except for creating players, and thus if the team does not wish to control player creation, this provides a solution that doesn’t require a dedicated backend

For an (even more) technical overview, see the API Documentation

Authentication and onboarding User onboarding Teams Service Accounts Player vs. User Player onboarding and authentication Overview In more depth Player Creation & Authentication