Custom User Authentication

This guide will explain how to prepare custom user authentication with self-made identity management system and integrate with industry standard SSOs

Intro

Very often content creators may want to make their audience to be the only users to access their content or maybe provide custom roles for users to provide more personalized content or both or deliver content or an expereience to their users. While user registration, verification and authentication part can be done by any back-end specialist, HoloFair will only need User Primary Key and an End Point to make user avatars more identifiable by using User Tags. In the meantime, the End Point should be able to respond to a GET request with specific json, which then HoloFair will use to setup User Tag. Below in this guide, you will read about User Tags, User Primary Key and End Point response requirements. Additionally, in the end of the page you will find possible integration options.

User Tags

In HoloFair, you may have noticed that users have a semi-transparent panel with their display name and colored role like on the image below

This not only makes user more identifiable by other users, but also allows to access content available only to a specific user group, which is not publicly shown and used internally by HoloFair to see what content matches to a user.

User Primary Key

It is an arbitrary value that is up to a developer to generate and keep secure. In general, we recommend to use MySQL as a storage of the identities and UUID() function to generate heavy randomized alphanumeric and not user friendly ID/Key whenever a user signs up to get access to a custom HoloFair world. Feel free to use your own way of storing the identities and generating User Primary Keys. Below you can find sample of the url that we may use to authenticate verified users and provide access to a demo content

https://holofair.app?code=5466989&uuid=f96dac98-91e4-450a-9d55-acc280beec09

End Point

Once link below is accessed, HoloFair will start loading and on completion will fetch End Point url from HoloFair database to make a GET request with provided User Primary Key as one of the parameters in order to get user data. Whenever such End Point is provided it must have exactly the same 200 response as below

{
    "displayName": String,
    "roleName": String,
    "roleColor": String,
    "group": int,
    "fullNameRestrictedVisibilityGroups": int[] // optional, User group ids who can't see full name of a user
    "PhoneNumber": String, // optional
    "Email": String, // optional
    "profileImage": String // optional
}

A possible response maybe similar to described below

{
    "displayName": "Kevin L Joly",
    "roleName": "VIP",
    "roleColor": "#7c1ea3",
    "group": 1,
    "fullNameRestrictedVisibilityGroups": [1] // optional, User group ids who can't see full name of a user
    "PhoneNumber": "909-718-1950", // optional
    "Email": "[e-mail]", // optional
    "profileImage": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/681px-Placeholder_view_vector.svg.png" // optional
}

In case you didn't use a template world and made your own HoloFair world with the SDK, make sure to use group values to provide targeted content to a specific group of users

Make sure to provide End Point in the HoloFair portal in advance, otherwise HoloFair will grant users with Guest name and Guest user group once they join a world

Full name retricted view

You may have noticed that response may contain fullNameRestrictedVisibilityGroups field. This allows you to control what users can see full name of a user.

Basic Integration

1. Build and deploy database.

2. Develop and deploy your own End Point.

3. On the HoloFair portal copy-paste the End Point url to End Point field and save.

4. Design, develop and deploy sign in/sign up web form using html, css and javascript. The data from the form must be recorded in the database. Make sure to retrieve generated User Primary Key.

5. Redirect user to your HoloFair world using following URL format: https://holofair.app?code={{event code provided in the HoloFair portal}}&uuid={{generated User Primary Key}}

The event code in the URL can be also made custom for per user. The main idea would be changing this part of URL based on user sign in/sign up response you create in step 4, which may be not neccessarly only User Primary Key. It is especially usefull when you try to achieve different content targetting based on a user group.

iframe Integration

The integration is the same until step 5. In the step 5, instead of redirecting a user, use following iframe code to show HoloFair inside your own website:

<iframe
    src="https://cdn.holofair.net/build/2021.3.1f1/5.1.10/index.html?code={{event code provided in the HoloFair portal}}&uuid={{generated User Primary Key}}"
    title="HoloFair"
    allow="camera;microphone;display-capture"
    width="1020"
    height="573.75"
    allowfullscreen="true">
</iframe>

We would also recommend to keep src attribute of the iframe keep empty and set complete url only after user authentication in order not to load HoloFair app too early.

GET parameter event code of src attribute also can be custom per user, which can be achieved by the same way like in the hint above.

Integration with SSO

Since the user authentication is completely web-based any other SSO integrations (Google, Apple ID, FaceBook, Microsoft Azure, Active Directory, UAE Pass etc.) are essentially straightforward, i.e. whatever the way of user identification is, they should be recorded in a intermediate database and available for reading to HoloFair. It makes User Primary Key and valid End Point the only two values required to properly identify a user in HoloFair.

Summary

Below flowchart summarizes integration plan

Third Party is the same as content creator or HoloFair world developer

1. Third Party creates back-end with necessary API to allow visitors to sign up, get verified and sign in. Additionally, creates and End Point, which HoloFair should use to make a GET request with provided User Primary Key to retrieve required json of user data.

2. Third Party creates the website and web app for users to access the authenticate themselves and access Third Party HoloFair world.

3. Third Party logs in Holofair portal and provides End Point

4. HoloFair records the End Point

5. Visitor visits Third Party website and access the Third Party web app

6. Visitor signs up to access the Third Party HoloFair world by providing neccessary data. The set of data that is required is up to Third Party. Feel free to use here Google Auth, Apple Auth, Facebook, UAE Pass or your own of getting necessary user data.

7. On successful authentication website stores User Primary Key and either redirects user to https://holofair.app/?code={{code}}&uuid={{User Primary Key}} or loads iframe where src attribute is also https://holofair.app/?code={{code}}&uuid={{User Primary Key}}. Note that code value must be the same as the one HoloFair generated after world creation on HoloFair portal. This value can be different per user in case if Third Party created multiple worlds for different group of users. Make sure to adjust your API accordingly so that it actually returns different code for different users.

8. HoloFair fetches End Point from the HoloFair back-end.

9. HoloFair makes a GET request to the End Point: https://api.thirdparty.com/holofair/auth?uuid={{uuid}}

10. End Point responds with required user data (see End Point response requirements) and configure user according to the data in HoloFair system.

Now user is identified and now have access to the intended content.