Generator

The basic concept of PhantAuth is that it generates data in a random but deterministic way. To achieve this goal, a so-called pseudorandom number generator (PRNG) is used. Each object type has an identifier (login name for user, client_id for client, etc.) By using a given hash algorithm, the value of the pseudorandom generator seed is produced from this identifier. Then, every property of the given object is generated with the pseudorandom generator started from this seed value. Taking advantage of the special feature of the pseudorandom number generator, also called as deterministic random bit generator (DRBG), that is, it generates the same random value series started from the same seed, the identifier clearly defines the object generated from it. That is, by the use of an identifier and generator, you can regenarate the properties of a given object at any time.

Based on the above concept, PhantAuth is absolutely stateless, and no storage medium is necessary. So, a randomly selected login name will "exist", and the properties of the "associated" user can be generated.

Identifier

In brief, an object is defined by its identifier. The name of the identifier of a user or client object is sub or client_id used in the OpenID Connect specifications. The name of the identifier property of other PhantAuth-specific objects that are not included in the specifications is sub.

The identifier may contain any character.

Customization

Sometimes you may want to customize the properties generated from the identifier. Although the identifier may contain any character, and its structure is optional, you can customize the generated values if a certain structure is used.

Flags

You can use a variety of flags to customize or give the parameters of certain object properties (user, client, etc.). The flags can be grouped by their effect on the generation of the properties. Basically, a flag is a keyword. You can set more than one flags to affect the generation of a variety of properties at the same time. To separate the flags from one another and the rest of the identifier, you need to use a semicolon ;:

joe;female;kitten

In the above example, the user generated by the user generator is female, and her avatar is a randomly selected sketched kitten avatar. The other features are deterministically generated from the name "joe", that is, their values are not affected by the two flags. The profile page of this example can be found here.

Please note that the flags form part of the identifier, as a different flag allows you to generate a different object.

User gender flags

The following flags modify the gender of the generated user.

Flag Description
male The gender property of the generated user is male, independent of the user's name
female The gender property of the generated user is female, independent of the user's name
guess The gender property is defined on the basis of the generated user's given name (default)
nogender The generated user doesn't have a gender property

User avatar flags

The following flags modify the generated avatar image.

Avatar Flag Description
ai AI type generated, photo-like avatars (default)
sketch sketched photo-like avataaars avatars
photo photo avatars
dice pixel art-style DiceBear avatars
kitten ROBOHASH-generated sketched kitten avatars
adorable Adorable Avatars
mp simple, cartoon-style silhouetted outline of a person (does not vary by user)
identicon a geometric pattern based on an email hash
monsterid a generated "monster" with different colors, faces, etc.
wavatar generated faces with varying features and backgrounds
retro awesome generated, 8-bit arcade-style pixelated faces
robohash a generated robot with different colors, faces, etc.
blank a transparent PNG image
  notfound return an HTTP 404 (File Not Found) response
  noavatar the user will not have a picture property

Client logo flags

The following flags modify the generated logo.

Logo Flag Description
icon Game-icons.net icon as a logo (default)
fractal Electric Sheep fractal as a logo

Group size flags

The following flag modify the sizes of the generated team (group of users) and fleet (group of clients).

Flag Size
tiny 5 (default)
small 10
medium 25
large 50
huge 100

Name

In most cases, the generated objects have a full name, which is generated from the identifier. Instead of being generated, the full name can be produced from the identifier, if the identifier contains at least one period (.) or space () character. In such cases, these characters play the role of separator between the parts of the full name (e.g. family name, given name). That is, the full name isn't randomly generated from the identifier but, by taking the separator characters into account, it is produced from the single parts of the full name (with capitalised initial letters). For this purpose, it is advised to use a period character, rather than a space character.

joe.black;sketch

In the above example: The full name of the user generated by the user generator is Joe Black (and his avatar is a skecthed profile avatar). The profile page of this example can be found here.

Picture

In most cases, the generated objects have an image (avatar for a user, logo for a client), which is generated from the identifier. The flags determine which pre-defined inventory the image comes from (see flags). It can be further customized by the use of Gravatar.

Each object has a generated unique email address (email for a user, logo_email for any other objects). To customize the image of a given object, you need to assign the gravatar image to this email address. By default, an object has a gravatar image, and the generated image is the default value of the gravatar URL only. In other words, as soon as you create a gravatar image to a given email address, that image will appear as the image associated with the given object.

Email

A disposable, operational email address suitable for receiving incoming emails is generated to each object. You can use your own email address (e.g. a previously set test email address) instead of a generated email address, if you prefer. In this case, the identifier contains an email address. Consequently, the image associated with the given object is the gravatar image assigned to the email address contained in the identifier.

In the above example: The email address of the user generated by the user generator is [email protected] (and his name is Ivan Test Szkiba). The profile page of this example can be found here.

Custom Generators

PhantAuth can use external data sources and generators as well. The only restriction is that the external generator has to be deterministic. This means that even if called several times, it has to generate the same object to the same identifier.

A special case of external generators is if an external data source is used. In such cases, the properties of a given object can be provided in a comma separated value (CSV) file or a Google Sheets document.

The external data sources and generators can be defined by the use of so-called tenants. To learn more, please go to chapter Tenant.