Username (ID)

Definition and Default Configuration

The username (ID) is considered a factor as well, though it will mostly serve for identifying a user as a first-step in order to continue the authentication with other non-unique factors (such as OTP or password for example).

To the Quasr platform, the username value has no semantic meaning; whether the end-user uses their email address, their real-name or a fictitious nickname makes no difference to Quasr. Quasr does not require the username value to be any sort of PII (Personal Identifiable Information).

The default allowed username value pattern is very flexible, allowing any character and a length between 1-100 characters. There is also no limitation on the character set - if a user prefers to use Chinese or Cyrllic characters, they can do so.

The default maximum failed attempts before the factor gets temporarily disabled is 5. The factor will auto-unlock after 300 seconds (5 minutes). The counter resets to 0 on each successful login.

Usernames are non-case-sensitive by default.

Usernames values are stored hashed, using the Argon2id algorithm.

User Interface (UI) Example

Below is a sample screenshot to give an idea of a potential login / registration page asking for a username. On a login or registration page, the username input field is usually represented by a single-line text field.

Example of username login on the Hosted Login UI (Quasr)

Signup with a username

This step is done by the end-users, usually at initial signup to a web service or to add an additional authentication method (factor) to their existing one as additional option.

To signup with a username, the actual username value (input parameter) and optionally a label (label parameter) is provided.

Enrolling a username factor

POST https://{tenant_id}.api.quasr.io/factors/signup

Request Body

Name	Type	Description
input	String	ID value
label	String	Label
id*	String	Factor ID

200: OK Failed enrollment

{
  "result": "FAILED",
  "feedback": {
    "cause": "INVALID_INPUT"
  }
}

200: OK Successful enrollment (with access token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment id>",
    "generated_input": "<generated_input>" // in case input was not provided
  }
}

200: OK Successful enrollment (with session token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment id>",
    "generated_input": "<generated_input>" // in case input was not provided
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}

Login with a username

This step is done by the end-users, in order to authenticate themselves (login).

To validate a username factor, the actual username value (input parameter) is provided.

Validating a username factor

POST https://{tenant_id}.api.quasr.io/factors/login

Request Body

Name	Type	Description
input*	String	ID value
id*	String	Factor or Enrollment ID

200: OK Successful validation (with session token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrolment_id": "<enrollment_id>"
  },
  "session_token": "<session_token>",
  "account_id": "<account_id>",
  "session_score": <session_score>,
  "session_exp": <session_expiration> // epoch in seconds (not ms)
}

200: OK Failed validation

{
  "result": "FAILED",
  "feedback": {
    "cause": "ENROLLMENT_NOT_FOUND",
  }
}

Factor Creation via Management API

This step is done by the Quasr customer's Tenant Administrator, to provide this factor as an authentication option to their end-users.

A username factor is already available for all newly created tenants by default, however, if you want to add additional ID factors, you can do so via Tenant Administration UI or Admin API.

The following API sample calls create a username factor labelled "Another Username" with a score of 1.

The username factor allows for the following parameters and config options:

Parameter	Value Options	Default Value	Required
subtype	"secret:id"
label	<any string>	"Username"
status	"ENABLED" | "DISABLED"	"DISABLED"
score	<positive int>	1
config. regex	regex	"^.{1,100}$"
config.unique	true | false	true
config. case_sensitive	true | false	false
config. public_signup	true | false	false
config.threshold	0-4	0
config.require_validation_for_enablement	true | false	false
config.capture_input	true | false	false

The Quasr Access Token used in the Authorization header in the examples below must contain the scope https://api.quasr.io/scopes/admin in order to be authorized. See API Authorization

GraphQL Example

// GraphQL Query (Sample)
mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}

// GraphQL Variables (Sample)
{
  "input": {
    "subtype": "secret:id",
    "regex": "^.{1,100}$",
    "label": "My Username",
    "status": "ENABLED",
    "score": 1
  }
}

// Response (Sample)
{
    "data": {
        "createFactor": {
            "id": "678c0054-d57e-4e09-9e54-ef8deb4ddd72"
        }
    }
}

Node.js Example

var axios = require('axios');
var data = JSON.stringify({
  query: `mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}`,
  variables: {
    "input": {
      "subtype": "secret:id",
      "regex": "^.{1,100}$",
      "label": "Another ID",
      "status": "ENABLED",
      "score": 1
    }
  }
});

var config = {
  method: 'post',
  url: 'https://{tenant_id}.api.quasr.io/graphql',
  headers: { 
    'Authorization': 'Bearer {access_token}', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});