Secret

Secrets are only stored securely hashed so secrets can not be recovered. Hence if an account loses its secret, it must re-generate the secret.

Secrets are similar to passwords but auto-generated by the authorization server and of a certain minimum length. The main purpose is its use as a client secret for client authentication, though it could also be used by any account type other than a client.

Default Secret Policy

• minimum 43 characters length

• maximum 43 characters length

• no password expiration / no required password change

Secrets 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.

Secrets are stored hashed (Argon2id).

Signup

To enroll a secret factor, optionally a label (label parameter) is provided. The secret value itself is auto-generated by the Quasr service.

Signup with secret factor

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

Request Body

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

200: OK Successful signup (with access token)

{
  "result": "SUCCESS",
  "feedback": {
    "cause": "",
    "enrollment_id": "<enrollment id>",
    "generated_input": "<generated secret>" // in case no input is provided
  }
}

Login

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

Validating an secret factor

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

Request Body

Name	Type	Description
input*	String	Password
id*	String	Enrollment ID

200: OK Failed validation

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

200: OK Successful validation (with session)

{
  "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)
}

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 or Admin API.

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

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

The following API sample calls create an Secret factor labelled "Client Secret" with a score of 6.

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:password",
    "label": "Client Secret",
    "status": "ENABLED",
    "score": 6
  }
}

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

Node.js Example

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

var config = {
  method: 'post',
  url: 'https://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

Secrets 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 (Open Source)
• Bitwarden (Open Source)
• 1Password
• Lastpass
• Google Password Manager

Additional Resources

• OWASP Password Storage Recommendation
• NIST Password Recommendations
• Summary of 2021 NIST Password Recommendations