Skip to content
masks

Clients

Clients are consumers of the masks server. Typically they are web or mobile apps that manage data only meant for authenticated actors. For every real-world client there will be a corresponding record in the masks server.

Adding clients

You can add clients manually as a manager, via the API, CLI, with seeds, a clients.yml file, or a number of other ways.

clients.yml

Any clients specified in clients.yml will be available to masks:

mobile:
  name: My mobile app
  type: public


admin:
  name: Admins only
  type: internal
  scopes:
    required: admin

Refer to the settings for a complete set of options.

Command line

You can also make new clients using the command line. The following adds a client with a key of my-app named "My app":

Terminal window
masks client my-app name="My app" type=confidential

You can also edit clients, given a key:

Terminal window
masks client my-app allow_sso=false

Ruby API

You can seed clients in Ruby with the Masks global:

client = Masks.clients.new(key: "my-app", type: "confidential")
client.save

Or in your db/seeds.rb:

db/seeds.rb
Masks.seed { client "my-app", type: "confidential" }

HTTP APIs

If configured, masks can expose a dynamic client registration endpoint. Given a valid token, a masks consumer can register clients over the network. There are GraphQL mutations for adding and editing clients.

Types

You’ll notice most examples specify a type. Types are optional, since they are just named defaults. There are several built-in types:

You can add custom types if necessary using the client_types key in your masks.yml:

config/masks.yml
client_types:
  my-type:
    internal: true
    allow_factor2: false
    # etc...

Settings

In general, you can pass any of the following settings to the various APIs for adding & editing clients.

name string A human-readable name for the client.
default null
key string A public key for identification.
default generated from name
type string .
default null
secret string A private secret for authentication.
default random 64-character base58 string
internal boolean Internal clients operate on the same domain.
default false
pkce boolean .
default false
issuer string The "iss" claim value for ID tokens.
default the masks server url
allowed_scopes string A list of scopes allowed by the client.
default null
required_scopes string A list of required, always-applied scopes.
default null
grant_types string A list of allowed grant types (from the OIDC spec).
default null
response_types string A list of allowed response types (from the OIDC spec).
default dynamic
redirect_uris json A newline-separated list of allowed redirect URIs.
default null
default_redirect_uri string A redirect URI to use if/when none is supplied.
default dynamic
public_url string A public URL for linking back to the client.
default null
styles_url string .
default null
terms_url string .
default dynamic
rsa_private_key string The client's private key.
default RSA-2048 key
require_approval boolean Show a consent screen before granting access.
default true for public clients
sector_identifier string A stable identifier for use with pairwise subject types.
default the masks server url
subject_type string Customize the actor (subject) exposed to the client.
default pairwise-uuid
id_token_duration string Lifetime for ID tokens.
default 6 hours
access_token_duration string Lifetime for access tokens.
default 6 hours
authorization_code_duration string Lifetime for authorization codes.
default 10 minutes
refresh_token_duration string Lifetime for refresh tokens.
default 1 day
client_token_duration string Lifetime for client tokens.
default 12 hours
internal_token_duration string Lifetime for internal tokens.
default 1 day
login_attempt_duration string Lifetime for login attempts.
default 1 hour
login_link_duration string .
default 15 minutes
verified_email_duration string Verified email lifetime—requiring re-verification on expiration.
default 1 year
phone_verification_duration string Lifetime for phone/SMS verification.
default 15 minutes
sso_request_duration string Lifetime for a single sign-on request.
default 30 minutes
sso_login_duration string Session lifetime for login via SSO.
default 6 hours
email_login_duration string Session lifetime for login via email.
default 12 hours
password_login_duration string Session lifetime for traditional password login.
default 1 day
signup_login_duration string .
default 1 hour
backup_code_2fa_duration string Session lifetime for 2FA with backup codes.
default 3 hours
phone_2fa_duration string Session lifetime for 2FA with phone/SMS.
default 2 hours
otp_2fa_duration string Session lifetime for 2FA with TOTP/ROTP.
default 2 hours
webauthn_2fa_duration string Session lifetime for 2FA with webauthn.
default 2 hours
actor_duration string How long to remember actors after login.
default 1 week
onboarded_profile_duration string .
default 1 year
allow_login boolean .
default true
allow_signup boolean .
default true
allow_nicknames boolean Toggle login with nickname.
default true
allow_emails boolean Toggle login with an email address.
default true
allow_passwords boolean Toggle password-based login.
default true
allow_login_links boolean Toggle login links.
default true
allow_factor2 boolean Toggle any form of two-factor auth.
default true
allow_otp boolean Toggle two-factor auth with one-time passwords (TOTP/ROTP).
default true
allow_phones boolean Toggle two-factor auth with SMS codes.
default true
allow_webauthn boolean Toggle two-factor auth with Webauthn (excluding passkeys).
default true
allow_backup_codes boolean Toggle two-factor auth with backup codes.
default true
allow_sso boolean Toggle support for single sign-on.
default true
allow_profiles boolean Allow built-in profile management.
default true
allow_discovery boolean .
default false
created_at datetime Time of creation.
read-only
updated_at datetime Last time of changed.
read-only
autofill_redirect_uri boolean If true, auto-fill empty redirect_uris with the first successful used.
default false
fuzzy_redirect_uri boolean Allow wildcards with '*' in redirect URIs.
default false
pairwise_salt string A "salt" for use with pairwise subject types.
default random 10-character hex string