base.rdoc

doc/base.rdoc
Last Update: 2021-02-04 12:27:02 -0800

Documentation for Base Feature

The base feature is automatically loaded when you use Rodauth. It contains shared functionality that is used by multiple features.

Auth Value Methods

Most Commonly Used

account_password_hash_column

Set if the password hash column is in the same table as the login. If this is set, Rodauth will check the password hash in ruby. This is often used if you are replacing a legacy authentication system with Rodauth.

accounts_table

The database table containing the accounts.

base_url

The base URL to use, used when construct absolute links. It is recommended to set this if the application can be reached using arbitrary Host headers, as otherwise it is possible for an attacker to control the value.

db

The Sequel::Database object used for database access.

domain

The domain to use, required by some other features. It is recommended to set this if the application can be reached using arbitrary Host headers, as otherwise it is possible for an attacker to control the value.

hmac_secret

This sets the secret to use for all of Rodauth's HMACs. This is not set by default, in which case Rodauth does not use HMACs for additional security. However, it is highly recommended that you set this, and some features require it.

mark_input_fields_as_required?

Whether input fields should be marked as required, so browsers will not allow submission without filling out the field (default: true).

prefix

The routing prefix used for Rodauth routes. If you are calling in a routing subtree, this should be set to the root path of the subtree. This should include a leading slash if set, but not a trailing slash.

require_bcrypt?

Set to false to not require bcrypt, useful if using custom authentication or when using the argon2 feature without existing bcrypt password hashes.

session_key

The key in the session hash storing the primary key of the logged in account.

session_key_prefix

The string that will be prepended to the default value for all session keys.

skip_status_checks?

Whether status checks should be skipped for accounts. Defaults to true unless enabling the verify_account or close_account features.

title_instance_variable

The instance variable to set in the Roda scope with the page title. The layout should use this instance variable if available to set the title of the page. You can use set_title if setting the page title is not done through an instance variable.

Other

account_id_column

The primary key column of the accounts_table.

account_open_status_value

The integer representing open accounts.

account_select

An array of columns to select from accounts_table. By default, selects all columns in the table.

account_status_column

The status id column in the accounts_table.

account_unverified_status_value

The integer representating unverified accounts.

authenticated_by_session_key

The key in the session hash storing an array of methods used to authenticate.

autocomplete_for_field?(param)

Whether to use an autocomplete attribute for the given parameter, defaults to mark_input_fields_with_autocomplete?.

autologin_type_session_key

The key in the session hash storing the type of autologin method used, if autologin was used to authenticate.

cache_templates

Whether to cache templates. True by default. It may be worth switching this to false in development if you are using your own templates instead of the templates provided by Rodauth.

check_csrf?

Whether Rodauth should use Roda's check_csrf! method for checking CSRF tokens before dispatching to Rodauth routes, true by default.

check_csrf_opts

Options to pass to Roda's check_csrf! if Rodauth calls it before dispatching.

check_csrf_block

Proc for block to pass to Roda's check_csrf! if Rodauth calls it before dispatching.

default_field_attributes

The default attributes to use for input field tags, if field_attributes returns nil for the field.

default_redirect

Where to redirect after most successful actions.

field_attributes(field)

The attributes to use for the input field tags for the given field (parameter name).

field_error_attributes(field)

The attributes to use for the input field tags for the given field (parameter name), if the input has an error.

flash_error_key

The flash key to use for error messages (default: :error or 'error' depending on session support for symbols).

flash_notice_key

The flash key to use for notice messages (default: :notice or 'notice' depending on session support for symbols).

formatted_field_error(field, error)

HTML to use for error messages for the field (parameter name), if the field has an error. By default, uses a span tag for the error message.

hook_action(hook_type, action)

Arbitrary action to take on all hook processing, with hook type being :before or :after, and action being symbol for related action.

input_field_error_class

The CSS class to use for input fields with errors. Can be a space separated string for multiple CSS classes.

input_field_error_message_class

The CSS class to use for error messages. Can be a space separated string for multiple CSS classes.

input_field_label_suffix

The suffix to use for all labels. Useful for noting that the fields are required.

inputmode_for_field?(param)

Whether to use an inputmode attribute for the given parameter, defaults to mark_input_fields_with_inputmode?.

invalid_field_error_status

The response status to use for invalid field value errors, 422 by default.

invalid_key_error_status

The response status to use for invalid key codes, 401 by default.

invalid_password_error_status

The response status to use for invalid passwords, 401 by default.

invalid_password_message

The error message to display when a given password doesn't match the stored password hash.

lockout_error_status

The response status to use a login is attempted to an account that is locked out, 403 by default.

login_column

The login column in the accounts_table.

login_input_type

The input type to use for logins. Defaults to email if login column is email and text otherwise.

login_label

The label to use for logins.

login_param

The parameter name to use for logins.

login_required_error_status

The response status to return when a login is required and you are not logged in, if not redirecting, 401 by default

login_uses_email?

Whether the login field uses email, used to set the type of the login field as well as the autocomplete setting.

mark_input_fields_with_autocomplete?

Whether input fields should be marked with autocomplete attribute appropriate for the field, true by default.

mark_input_fields_with_inputmode?

Whether input fields should be marked with inputmode attribute appropriate for the field, true by default.

modifications_require_password?

Whether making changes to an account requires the user reinputing their password. True by default if the account has a password.

no_matching_login_error_status

The response status to use when the login is not in the database, 401 by default.

no_matching_login_message

The error message to display when the login used is not in the database.

password_hash_column

The password hash column in the password_hash_table.

password_hash_id_column

The account id column in the password_hash_table.

password_hash_table

The table storing the password hashes.

password_label

The label to use for passwords.

password_param

The parameter name to use for passwords.

require_login_error_flash

The flash error to display when accessing a page that requires a login, when you are not logged in.

require_login_redirect

A redirect to the login page.

set_deadline_values?

Whether deadline values should be set. True by default on MySQL, as that doesn't support default values that are not constant. Can be set to true on other databases if you want to vary the value based on a request parameter.

template_opts

Any template options to pass to view/render. This can be used to set a custom layout, for example.

token_separator

The string used to separate account id from the random key in links.

unmatched_field_error_status

The response status to use when two field values should match but do not, 422 by default.

unopen_account_error_status

The response status to use when trying to login to an account that isn't open, 403 by default.

use_database_authentication_functions?

Whether to use functions to do authentication. True by default on PostgreSQL, MySQL, and Microsoft SQL Server, false otherwise.

use_date_arithmetic?

Whether the date_arithmetic extension should be loaded into the database. Defaults to whether deadline values should be set.

use_request_specific_csrf_tokens?

Whether to use request-specific CSRF tokens. True if the default CSRF setting are used.

Auth Methods

account_from_login(login)

Retrieve the account hash related to the given login or nil if no login matches.

account_from_session

Retrieve the account hash related to the currently logged in session.

account_id

The primary key value of the current account.

account_session_value

The primary value of the current account to store in the session when logging in.

after_login

Run arbitrary code after a successful login.

after_login_failure

Run arbitrary code after a login failure due to an invalid password.

already_logged_in

What action to take if you are already logged in and attempt to access a page that only makes sense if you are not logged in.

around_rodauth(&block)

Run arbitrary code around handling any rodauth route. Call super(&block) for Rodauth to handle the action.

authenticated?

Whether the user has been authenticated. If multifactor authentication has been enabled for the account, this is true only if the session is multifactor authenticated.

before_login

Run arbitrary code after password has been checked, but before updating the session.

before_login_attempt

Run arbitrary code after an account has been located, but before the password has been checked.

before_rodauth

Run arbitrary code before handling any rodauth route, but after CSRF checks if Rodauth is doing CSRF checks.

check_csrf

Checks CSRF token using Roda's check_csrf! method.

clear_session

Clears the current session.

csrf_tag(path=request.path)

The HTML fragment containing the CSRF tag to use, if any.

function_name(name)

The name of the database function to call. It's passed either :rodauth_get_salt or :rodauth_valid_password_hash.

logged_in?

Whether the current session is logged in.

login_required

Action to take when a login is required to access the page and the user is not logged in.

open_account?

Whether the current account is an open account (not closed or unverified).

password_match?(password)

Check whether the given password matches the stored password hash.

random_key

A randomly generated string, used for creating tokens.

redirect(path)

Redirect the request to the given path.

session_value

The value for session_key in the current session.

set_error_flash(message)

Set the current error flash to the given message.

set_notice_flash(message)

Set the next notice flash to the given message.

set_notice_now_flash(message)

Set the current notice flash to the given message.

set_redirect_error_flash(message)

Set the next error flash to the given message.

set_title(title)

Set the title of the page to the given title.

translate(key, default_value)

Return a translated version for the key (uses the default value by default).

unverified_account_message

The message to use when attempting to login to an unverified account.

update_session

Clear the session, then set the session key to the primary key of the current account.