{% auth %}

Use this method to execute authentication-related functionality for profiles.

This method is unique in its structure and use. Every call to auth will execute a specific action (called a command). The results of each command will be stored on the globally-reserved {{ auth }} object. In addition to other outputs, all auth commands set or clear the {{ auth.error_code }} and {{ auth.error_message }} properties.

The {{ auth }} object has one additional propery not listed below that you may find useful, and that is the {{ auth.logged_in }} property. {{ auth.logged_in }} will return true if there is a profile currently logged in on the current request, regardless of whether the profile was already logged in from a previous request or is logged in as a result of the {% auth login %} command.

In order to use the auth method, the first command used must be an init command. The simplest init command is {% auth init id %}. If you use multiple init commands, they must each use the same id. You may not use the auth command for multiple profiles in a single request.

Additionally, there are a number of commands which may only be called once - such as the login, register, set_password, activate, and deactivate commands for example. Attempting to execute one of these commands a second time will result in a duplicate_command error_code.

Note that while you can log a profile in using the {% auth %} method, you cannot log them out. To do that you will need the {% logout %} method.

Syntax

{% auth

command

Identifies the specific auth command to execute.

... varies ...

The remaining arguments for the auth method varies depending on which command is being executed. More details on the arguments for each command are listed blow.

Error Codes

Unless otherwise specified for an individual command, the following standard error codes have the following meaning:

command_disabled: Indicates that the current command has been disabled at the site level. This will be set for any auth command if profiles are disabled. Additionally there are several signup-related profiles which will result in this code if signup is disabled.
unexpected: Indicates that an unexpected system error has occurred for which we have no other explanation.
no_init: Indicates that no initialization functions have been called. This may also occur as a result of calling an initialization function without the optional [id] parameter.
bad_init: Indicates either that {% auth init %} was called without an id, or that multiple initialization functions were called with different id.
not_found: Indicates that no profile was found with the specified id from the initialization function.
aborted: Indicates that the command could not be performed because {% auth abort %} has been called.
abort_prevented: Indicates that the {% auth abort %} command could not be completed because a previous command has already been completed which cannot be undone.
duplicate_command: Indicates that the current command has already been called. Any command that can result in this error code may only be called once per page load.
missing_value: Indicates that the current command requires an additional argument which was not supplied. Although the missing argument should be obvious for most commands which may result in this error code, the error message will include more detail about which argument must be supplied.
invalid_value: Indicates that one or more supplied arguments is invalid. The error message will include more detail about which argument is invalid.
duplicate_value: Indicates that the command could not be completed because it would result in an invalid duplicate value (eg: multiple profiles with the same id or email address).
unchanged: Indicates that the command was not completed because it would not result in any meaningful change to the profile (eg: changing the email address to the same value, activating an already active profile, etc…).
expired: Currently only used by {% auth activate %} command to indicate that the activation_code has expired.
inactive: Indicates that the command could not be completed because the profile is inactive and must be activated first.
locked: Indicates that the command could not be completed because the profile is currently locked.
blocked: Indicates that the command could not be completed because the profile has been blocked.
require_password_reset: Indicates that the {% auth login %} command could not be completed because the password must first be reset.

Commands

init id

Must be called before other auth commands. There are several alternate init commands which may be called in place of {% auth init %}. Alternate init commands set the same auth properties as the {% auth init %} command.

Sets {{ auth.init }} to true, {{ auth.id }} to the specified ID, {{ auth.exists }} to true if a profile with the specified ID exists and false if it does not exist, and {{ auth.profile }} to the profile with the specified ID. If profile does not exist, {{ auth.profile.is_valid }} will be false.

Error Codes: command_disabled, bad_init, aborted

login [id] password

Functions as an alternate init command if the [id] argument is supplied.

If a profile is already logged in, this will result in a duplicate_value error_code.

Executing this command after a successful login, force_password_reset, deactivate, set_activation_code, lock, block, or register command will result in a duplicate_command error_code.

If successful, sets the globally-reserved {{ profile }} variable.

If successful, the {% auth abort %} command may not be called.

Sets {{ auth.login_success }} to true if successful, or false if not.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, blocked, locked, inactive, require_password_reset, missing_value, invalid_value, duplicate_value

abort

Once called all remaining auth commands will cease to function. This will also prevent any settings or attributes that were previously set or unset from being saved.

Can only be called as long as no commands have been executed that prevent abort (eg: login, register, unlock, set_password, etc....).

If successful, sets {{ auth.aborted }} to true, and unsets all other auth properties except for {{ auth.init }}, {{ auth.profile }}, {{ auth.id }}, and {{ auth.exists }}.

Error Codes: command_disabled, abort_prevented

clear_error

Unsets {{ auth.error_code }} and {{ auth.error_message }}.

set_password [id] new_password

Functions as an alternate init command if the [id] argument is supplied.

The set_password command may only be executed once.

Sets the password for the profile to the password specified. The new password may not be blank, but other than than there is no validation on the new password. It is up to the template developer to ensure that the password meets their criteria before calling this command.

For security purposes, passwords are securely salted and hashed before being stored. Once a password has been set there is no way to retrieve the original password - even by top-level Marketpath technical staff. Also for security purposes, you should not attempt to store old or current passwords for profiles.

Sets {{ auth.password_changed }} to true if it succeeds or false if it does not.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, blocked, locked, inactive, missing_value, unexpected

change_id [id] new_id

Functions as an alternate init command if the [id] argument is supplied.

The change_id command may only be executed once. If the site is configured to set the id and email to the same value then this command may also not be executed after calling the change_email command.

Sets the id for the profile to the id specified. If ths site is configured to set the id an email to the same value then will validate the id as a valid email address and will set the email to this value as well.

Note that this does NOT log the profile out, deactivate it, or require any further confirmation or action by the user to continue using their profile. Those actions are up to the template developer to execute (which we strongly recommend whenever the email address is changed).

Sets {{ auth.id_changed }} to true if successful or false if not. If successful sets {{ auth.old_id }} and {{ auth.new_id }} to the old and new id values and sets {{ auth.id }} to the new id. Note that any future auth init commands will have to use the new id instead of the old one.

If successful and the site is configured to set the id and email to the same value then this also sets {{ auth.email_changed }} to true and sets {{ auth.old_email }} and {{ auth.new_email }} to the old and new email values.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, blocked, locked, inactive, missing_value, unchanged, duplicate_value, unexpected

change_email [id] new_email

Functions as an alternate init command if the [id] argument is supplied.

The change_email command may only be executed once. If the site is configured to set the id and email to the same value then this command may also not be executed after calling the change_id command.

Sets the email for the profile to the email specified. Will also set the id to this value if the site is configured to set the id and email to the same value.

Sets {{ auth.email_changed }} to true if successful or false if not. If successful sets {{ auth.old_email }} and {{ auth.new_email }} to the old and new email values.

If successful and the site is configured to set the id and email to the same value this will also set {{ auth.id_changed }} to true, {{ auth.old_id }} and {{ auth.new_id }} to the old and new id values, and {{ auth.id }} to the new id. Note that in this case any future auth functions will be required to use the new id.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, blocked, locked, inactive, missing_value, unchanged, invalid_value, duplicate_value

force_password_reset [id]

Functions as an alternate init command if the [id] argument is supplied.

The force_password_reset command may only be executed once.

Resets the profile's password - requiring a password reset before the profile may log in again.

If there is a profile logged in, they will automatically be logged out (without saving changes, clearing the session, clearing cookies, or clearing permissions).

Sets {{ auth.force_password_reset }} to true if successful or false if not. If successful sets {{ auth.login_success }} to false.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, unexpected

activate [id] (force|activation_code)

Functions as an alternate init command if the [id] argument is supplied.

The activate command may only be executed once.

Attempt to activate the profile. If force is set, an activation code is not necessary. Otherwise the activation_code must match the activation code on the profile and must not have expired.

Sets {{ auth.activated }} to true if successful or false if not. Also unsets {{ auth.deactivated }}, {{ auth.activation_code_set }}, {{ auth.new_activation_code }}, and {{ auth.activation_code_expires }}.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, blocked, locked, unchanged, missing_value, invalid_value, expired, unexpected

deactivate

The deactivate command may only be executed once. The deactivate command may also not be called after the set_activation_code command.

Deactivates the profile - requiring activation before it may be logged in again. The only functional difference between this command and {% auth set_activation_code %} is that this command will unset the activation_code.

If there is a profile logged in, they will automatically be logged out (without saving changes, clearing the session, clearing cookies, or clearing permissions).

Sets {{ auth.deactivated }} to true and {{ auth.login_success }} to false. Unsets {{ auth.activated }}, {{ auth.activation_code_set }}, {{ auth.new_activation_code }}, and {{ auth.activation_code_expires }}.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, aborted, not_found, unexpected

set_activation_code [id] expiration_date

Functions as an alternate init command if the [id] argument is supplied.

The set_activation_code command may only be executed once.

Deactivates the profile and sets a new activation code which will expire on expiration_date - requiring activation before the profile may be logged in again. The only functional difference between this command and {% auth set_activation_code %} is that this command will set the activation_code.

If there is a profile logged in, they will automatically be logged out (without saving changes, clearing the session, clearing cookies, or clearing permissions).

Sets {{ auth.deactivated }} to true, {{ auth.activation_code_set }} to true, {{ auth.new_activation_code }} to the new activation code, {{ auth.activation_code_expires }} to the date the new activation code will expire, and {{ auth.login_success }} to false. Unsets {{ auth.activated }}.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, not_found, blocked, locked, missing_value, invalid_value, unexpected

lock until

The lock command may only be executed once.

Locks the profile until the specified date, typically used as a security precaution to prevent attackers from guessing passwords.

If there is a profile logged in, they will automatically be logged out (without saving changes, clearing the session, clearing cookies, or clearing permissions).

Sets {{ auth.locked }} to true if successful and false if not. If successful sets {{ auth.locked_until }} to the date that the profile will remain locked until, sets {{ auth.login_success }} to false, and unsets {{ auth.unlocked }}.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, aborted, not_found, missing_value, invalid_value, unexpected

unlock

The unlock command may only be executed once.

Unlocks the profile if it is locked.

Sets {{ auth.unlocked }} to true. Unsets {{ auth.locked }} and {{ auth.locked_until }}.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, aborted, not_found, unchanged, unexpected

block

The block command may only be executed once.

Blocks the profile indefinitely. Should only be used sparingly as blocking and unblocking profiles is typically done manually from the Marketpath CMS admin interface.

If there is a profile logged in, they will automatically be logged out (without saving changes, clearing the session, clearing cookies, or clearing permissions).

Sets {{ auth.blocked }} to true if successful or false if not. If successful unsets {{ auth.unblocked }} and sets {{ auth.login_success }} to false.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, aborted, not_found, unchanged, unexpected

unblock

The unblock command may only be executed once.

Unblocks the profile. Should only be used sparingly as blocking and unblocking profiles is typically done manually from the Marketpath CMS admin interface.

Sets {{ auth.unblocked }} to true and unsets {{ auth.blocked }}.

If successful, the {% auth abort %} command may not be called.

Error Codes: command_disabled, duplicate_command, no_init, aborted, not_found, unchanged, unexpected

set_attribute key:value etc...

Sets the specified profile attributes to their new values on the auth profile (not the currently-logged in profile).

If the profile exists and the auth is not aborted before the end of the request the new values will be saved to the profile. If the auth is aborted then the new values will not be saved in between requests. If the profile does not exist but is registered in the same request then the new values will be saved on the new profile.

Error Codes: command_disabled, no_init, aborted

unset_attribute key etc...

Removes the specified profile attributes from the auth profile (not the currently-logged in profile).

If the auth is aborted then the removed attributes will not be saved in between requests.

Error Codes: command_disabled, no_init, aborted

set_setting key:value etc...

Sets the specified profile settings to their new values on the auth profile (not the currently-logged in profile).

If any of the specified settings has validation, the new settings will be validated before being set. An invalid value for any setting will prevent any of the new settings from being set.

Error Codes: command_disabled, no_init, aborted, invalid_valid

unset_setting key etc...

Unsets the specified profile settings from the auth profile (not the currently-logged in profile). For settings with default values this will set them back to their defaults. For settings without default values this will set them to empty/unselected/false.

If the auth is aborted then the unset settings will not be saved in between requests.

Error Codes: command_disabled, no_init, aborted, invalid_valid

register key:value etc...

Functions as an alternate init command if an "id" key is supplied.

The register command may only be executed once.

Creates a new profile with the specified values, which will be stored in core profiles fields, settings, or attributes as follows:

id, email, password, is_active, date_activation_code_expires, date_locked_through, and is_blocked will be used to set the corresponding core profile fields and the related metadata (eg: is_active will also set date_activated to the current date).
logged_in will cause the new profile will be automatically logged in IF the profile is created successfully, is_active is true, password is set, is_blocked is not true, and date_locked_through is not set.
Keys that correspond to a custom profile setting will set the corresponding profile setting.
All other keys will set a profile attribute.

If the profile validation fails for any reason - including one or more custom profile settings are invalid (eg: an empty required setting), the entire registration will fail.

Unless otherwise specified the new profile will have the same id and email values, will require a password reset, will be inactive with a new activation code set to expire in 1 week, and will use all of the default custom profile setting values.

Sets {{ auth.registered }} to true if it succeeds, or false if it does not. If successful sets {{ auth.login_success }} to false.

If successful, the {% auth abort %} command may not be called.

If there is a profile logged in, they will automatically be logged out (without saving changes, clearing the session, clearing cookies, or clearing permissions).

Error Codes: command_disabled, duplicate_command, no_init, bad_init, aborted, duplicate_value, invalid_value