masks.json and ruby configuration...
There are two ways to configure masks—a masks.json
or an initializer that
calls Masks.configure
. Both are generated automatically when you run
the masks:install
generator.
If masks detects a file named masks.json
in the current working directory or in ENV['MASKS_DIR']
then it will be used as defaults.
{
"name": "my-app",
"url": "http://localhost:3000",
"extend": "masks",
"masks": [
{
"skip": true,
"request": {
"method": "get",
"path": "/assets/*"
}
}
]
}
While masks.json
is suitable for most, configuration via Ruby allows more
control. All properties outlined below are supported, along with any additional
abilities outlined in the API docs.
Masks.configuration
method can be used to inspect configuration.
Masks.configure do |config|
config.name = "my-app"
config.masks = [
# supports the same data structure as masks.json
]
end
Generally speaking, configuration specified using Masks.configure
will overwrite whatever is
in masks.json
.
Nearly all properties are optional, except for masks
.
String
- a name used to identify your application. you can add a user-facing name by setting title
. Defaults to your Rails app’s name.
String
- a human-readable name for your application, used in user-facing locations like the login page and meta tags.
URI
- a canonical URI for your application, used in places where it is referenced in a generic way (e.g. a footer).
URI
- a URI pointing to your application’s logo, used in places similar to title
(e.g. for branding on pages and favicons)
String
- a theme name, one of the stock daisyUI themes or a custom theme.
String
- the name of a gem to use as base configuration. "masks"
is a good starting value, assuming your app is also relying on the routes and controllers provided by Masks::Engine
.
Mask[]
- a list of masks to use for masking sessions.
When a session is created it will find an applicable mask from this list. Masks are searched from top-to-bottom and the first match wins, so list your most-specific masks first.
A Mask
must specify properties that sessions can use for matching:
Key | Type | Description |
---|---|---|
name | String |
a unique name to use in cases where direct matching is preferred. |
request | Request |
for HTTP-based sessions, a hash of conditions like a method, path, etc. |
access | String[] |
for access-based sessions, a list of access names that apply to the mask |
custom | Hash |
additional data to use for matching, usually for custom sessions. |
Every mask must specify a set of credentials and checks unless it is set to skip
. Access is only allowed when these conditions are met.
Name | Description |
---|---|
skip | If true, all credentials and checks for this mask will be skipped. Masks will effectively no-op, useful for situations where you are serving public/static content. |
credentials | Credentials are classes that verify the masked session. They are specified as a string (or Class in Ruby) referring to the credential’s class name. Masks built-in credentials are stored under Masks::Credentials:: but you can skip the prefix. |
checks | All credentials perform a series of checks. Your configuration must list the checks expected to pass. You can also specify how long to accept checks that happened in the past by specifying a duration for the check. |
actor | Credentials must identify an actor for the session, or it is denied. The actor must match the class name supplied in this field. |
anon | Some sessions are mixed-use. Set this to true (or a class name) to build and allow an anonymous actor when the credentials are unable to identify someone. |
scopes | If using scopes, you can specify a list of scopes to require. The session actor is expected to have at least one of the scopes in this list, or access is denied. |
/public
{
"skip": true,
"request": {
"method": "GET",
"path": "/public"
}
}
You can also specify what to do with a session after it’s been masked, specifically if it doesn’t pass. You can see the fail
key to one of the following values to adjust what happens:
Value | Behaviour |
---|---|
HTTP status | If you specify an HTTP status code, like 401 , it will be returned along with an empty body on failure. |
controller#action |
Pass a string in this format and the controller and action will be allowed to respond to the failed request (assuming it is a request-based session). |
URI or Path |
Pass a valid URI or path and a 302 redirect will be returned with the URI in the Location header. |
false |
By default fail is a truthy value. If false access will be allowed even when a failure occurred. In this case, your code must be prepared to handle both pass and failed states. |
/public
{
"type": "session",
"request": {
"path": "/public"
},
"fail": false
}
Sometimes you’ll want to backup the results of a mask somewhere, like to the Rails session. This makes it possible for actors to rely on session cookies and duration-based access. In other cases, like with API access, it’s not necessary. You can disable this functionality by adding "backup": false
to the mask.
// require a token on API requests
{
"credentials": [
"Key"
],
"checks": {
"actor": {}
},
"request": {
"path": "/api*",
"header": "Authorization"
},
"backup": "false
}
You can create types to share common configuration across Mask
s. This is an optional feature added to overcome JSON’s limitations in this area.
{
"types": {
"session": {
"credentials": ["Nickname", "Session", "Password"],
"checks": {
"actor": {
"duration": "P1D"
},
"password": {
"duration": "P1D"
}
}
}
},
"masks": [
{
"request": {
"path": "*",
"type": "session"
}
}
]
}
Hash
- a set of models to use in adapters, credentials, and other places that interact with your data layer. See models & adapters.
String|Class
- an adapter to use for finding and building models (primarily actors). See models & adapters.
Hash
- a set of lifetimes to use in various places, specified as a number of seconds.
These values dictate how long certain information is retained by masks—inactive accounts, cookies, session data, generated tokens, etc.
name | default |
---|---|
recovery_email |
1 hour |
verification_email |
1 hour |
passwordless_email |
10 minutes |
totp_drift |
60 seconds |
inactive_actor |
6 months |
Hash
- a set of links to use in the frontend. Some of these will default to the routes exposed by masks’ Rails engine.
Hash
- a set of default options for any access classes you build or rely on. The key should be the access name and the value a hash of data you’d like to merge on top of the access class’ default options.