# Password

{% hint style="info" %}
Password are only stored securely hashed **so passwords can not be recovered.** Hence if a user forgets their password they must have sufficient other factors in order to login and add a new password. In effect a password reset mechanism is exactly this and be created with Quasr by selecting factors accordingly in your login UI.
{% endhint %}

At Quasr we do believe in a passwordless future as we feel passwords are impractical for users and have various security challenges. Nonetheless we do offer a password factor as we understand our customers may still need it for the time being. Though we want to challenge our customers to think and plan for a passwordless future. Hence users can enroll in various factors allowing passwords to be phased out over time without implications.

## Definition and Default Configuration

The **password** is a knowledge-based authentication factor and requires input by the user. \
NIST categorizes it a “Memorized Secret”, which is defined as:

> A Memorized Secret authenticator — commonly referred to as a password or, if numeric, a PIN — is a secret value intended to be chosen and memorized by the user. Memorized secrets need to be of sufficient complexity and secrecy that it would be impractical for an attacker to guess or otherwise discover the correct secret value. A memorized secret is something you know.

The password is a **non-unique factor**, meaning that it’s possible that multiple users pick the same password by coincidence. A password requires an additional identifier upfront to be used for authentication (such as a username).

### Default Password Policy

Quasr follows a best-practice implementation according to [*OWASP*](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) and [*NIST*](https://pages.nist.gov/800-63-3/sp800-63b.html#memsecret) recommendations (as minimum) with a **default password policy** of:

* minimum **15** characters length
* maximum **100** characters length
* **no password expiration** / no required password change

**Passwords** are **case-sensitive**.

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.

**Passwords** are stored hashed (Argon2id).

## User Interface (UI) Example

Below is a sample screenshot to give an idea of a potential login / registration page asking for a **OTP factor**. It's just an example, as Quasr does not currently offer a hosted login page.

On a registration page, the **password** input field is usually represented by a single-line text field, often combined with an additional **password confirmation** fields (matching of password and confirmation to be checked client-side) to avoid typos.

<figure><img src="https://3830835165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mjx2ZPygyh2w8fuHh9P%2Fuploads%2FNv6nQIz2c8gcK6Plig26%2FScreenshot%202023-07-24%20at%2010.40.56.png?alt=media&#x26;token=8a181a52-a277-42f4-998d-97b7a79b6e1f" alt="" width="563"><figcaption><p>Password confirmation during new factor enrollment in Quasr Account UI.</p></figcaption></figure>

On a login page, the **password** input field is usually represented by a single-line **password** field, which by default **hides** the input, but allows to toggle its **visibility** and also allows for copy/pasting values into it (i.e. from a **password manager**).

<figure><img src="https://3830835165-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mjx2ZPygyh2w8fuHh9P%2Fuploads%2FZqHHO6w3MfUdho4Wqc1X%2FScreenshot%202023-07-24%20at%2010.39.34.png?alt=media&#x26;token=c6ad7246-fae0-4024-9fe6-a93d892ef06c" alt="" width="367"><figcaption><p>Login with password on the Hosted Login Page (Quasr).</p></figcaption></figure>

## Signup

To enroll a **password** factor, the actual **password** (`input` parameter) and optionally a **label** (`label` parameter) is provided.

## Signup with password factor

<mark style="color:green;">`POST`</mark> `https://{tenant_id}.api.quasr.io/factors/signup`

#### Request Body

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| input                                | String | Password    |
| label                                | String | Label       |
| id<mark style="color:red;">\*</mark> | String | Factor ID   |

{% tabs %}
{% tab title="200: OK Successful signup (with access token)" %}

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

{% endtab %}

{% tab title="200: OK Successful signup (with session token)" %}

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

{% endtab %}
{% endtabs %}

## Login

To validate a **password** factor, the actual **password** (`input` parameter) is provided.

## Login with password factor

<mark style="color:green;">`POST`</mark> `https://{tenant_id}.api.quasr.io/factors/login`

#### Request Body

| Name                                    | Type   | Description   |
| --------------------------------------- | ------ | ------------- |
| input<mark style="color:red;">\*</mark> | String | Password      |
| id<mark style="color:red;">\*</mark>    | String | Enrollment ID |

{% tabs %}
{% tab title="200: OK Failed login" %}

```javascript
{
  "result": "FAILED",
  "feedback": {
    "cause": "INCORRECT_INPUT",
  }
}
```

{% endtab %}

{% tab title="200: OK Successful login (with session token)" %}

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

{% endtab %}
{% endtabs %}

## Factor Creation & Configuration

A **Password factor** is already available for all newly created tenants by default, however, if you want to add additional password factors, you can do so via [Tenant Administration UI](https://docs.quasr.io/quasr/tenant-administration/factors/broken-reference) or [Admin API](https://docs.quasr.io/quasr/tenant-administration/apis/management-api-graphql).

The **Password Factor** allows for the following **parameters** and **config options**:

<table><thead><tr><th width="246.66913060846045">Parameter</th><th width="228.49595687331538">Value Options</th><th width="150">Default</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><mark style="color:blue;"><strong>subtype</strong></mark></td><td>"secret:password"</td><td></td><td>true</td></tr><tr><td><mark style="color:blue;"><strong>label</strong></mark></td><td><em>&#x3C;string></em></td><td>"Password"</td><td>false</td></tr><tr><td><mark style="color:blue;"><strong>status</strong></mark></td><td> "ENABLED" | "DISABLED"</td><td>"DISABLED"</td><td>false</td></tr><tr><td><mark style="color:blue;"><strong>score</strong></mark></td><td><em>&#x3C;positive int></em></td><td>1</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>unique</strong></mark></td><td>true | false</td><td>false</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>case_sensitive</strong></mark></td><td>true | false</td><td>true</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>require_validation_for_enablement</strong></mark></td><td>true | false</td><td>false</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>regex</strong></mark></td><td>regex</td><td>"^.{15,100}$"</td><td>false</td></tr><tr><td><mark style="color:blue;">config.<strong>threshold</strong></mark></td><td>0-4</td><td>2</td><td>false</td></tr></tbody></table>

The following API sample calls create an **Password factor** labelled *"Another Password"* with a score of *2*.

{% hint style="info" %}
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](https://docs.quasr.io/quasr/apis/management-api-graphql#api-authorization)
{% endhint %}

### GraphQL Example

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

// GraphQL Variables (Sample)
{
  "input": {
    "subtype": "secret:password",
    "label": "Another Password",
    "status": "ENABLED",
    "score": 2
  }
}

// Response (Sample)
{
    "data": {
        "createFactor": {
            "id": "8bde5565-7027-4232-8db8-3f3ca1acaeac"
        }
    }
}
```

### Node.js Example

```javascript
var axios = require('axios');
var data = JSON.stringify({
  query: `mutation createFactor ($input: CreateFactorInput!) {
    createFactor (input: $input) {
        id
    }
}`,
  variables: {
    "input": {
      "subtype": "secret:password",
      "label": "Another Password",
      "status": "ENABLED",
      "score": 2
    }
  }
});

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);
});
```

## Recommended Password Managers

Passwords should be long and complex, which makes them hard or impossible to remember. The use of a password manager is recommended to keep them safe. Here is a list of password managers that we can recommend (Quasr has no affiliation with these vendors).

* [KeepassXC](https://keepassxc.org/) (Open Source)
* [Bitwarden](https://bitwarden.com/) (Open Source)
* [1Password](https://1password.com/)
* [Lastpass](https://www.lastpass.com/)
* [Google Password Manager](https://passwords.google.com/)

## Additional Resources

* [OWASP Password Storage Recommendation](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) &#x20;
* [NIST Password Recommendations](https://pages.nist.gov/800-63-3/sp800-63b.html#memsecret)&#x20;
* [Summary of 2021 NIST Password Recommendations](https://www.netsec.news/summary-of-the-nist-password-recommendations-for-2021/)&#x20;