diff --git a/docs/configuration.rst b/docs/configuration.rst index e91974f..5e49c77 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -1,62 +1,175 @@ Configuration ============= -Flask-Security configuration options. +The following configuration values are used by Flask-Security: -* :attr:`SECURITY_URL_PREFIX`: Specifies the URL prefix for the Security - blueprint. -* :attr:`SECURITY_FLASH_MESSAGES`: Specifies wether or not to flash messages - during security mechanisms. -* :attr:`SECURITY_PASSWORD_HASH`: Specifies the encryption method to use. e.g.: - plaintext, bcrypt, etc. -* :attr:`SECURITY_AUTH_URL`: Specifies the URL to to handle authentication. -* :attr:`SECURITY_LOGOUT_URL`: Specifies the URL to process a logout request. -* :attr:`SECURITY_REGISTER_URL`: Specifies the URL for user registrations. -* :attr:`SECURITY_RESET_URL`: Specifies the URL for password resets. -* :attr:`SECURITY_CONFIRM_URL`: Specifies the URL for account confirmations. -* :attr:`SECURITY_LOGIN_VIEW`: Specifies the URL to redirect to when - authentication is required. -* :attr:`SECURITY_CONFIRM_ERROR_VIEW`: Specifies the URL to redirect to when - an confirmation error occurs. -* :attr:`SECURITY_POST_LOGIN_VIEW`: Specifies the URL to redirect to after a - user logins in. -* :attr:`SECURITY_POST_LOGOUT_VIEW`: Specifies the URL to redirect to after a - user logs out. -* :attr:`SECURITY_POST_FORGOT_VIEW`: Specifies the URL to redirect to after a - user requests password reset instructions. -* :attr:`SECURITY_RESET_PASSWORD_ERROR_VIEW`: Specifies the URL to redirect to - after an error occurs during the password reset process. -* :attr:`SECURITY_POST_REGISTER_VIEW`: Specifies the URL to redirect to after a - user successfully registers. -* :attr:`SECURITY_POST_CONFIRM_VIEW`: Specifies the URL to redirect to after a - user successfully confirms their account. -* :attr:`SECURITY_UNAUTHORIZED_VIEW`: Specifies the URL to redirect to when a - user attempts to access a view they don't have permission to view. -* :attr:`SECURITY_CONFIRMABLE`: Enables confirmation features. Defaults to - `False`. -* :attr:`SECURITY_REGISTERABLE`: Enables user registration features. Defaults to - `False`. -* :attr:`SECURITY_RECOVERABLE`: Enables password reset/recovery features. - Defaults to `False`. -* :attr:`SECURITY_TRACKABLE`: Enables login tracking features. Defaults to - `False`. -* :attr:`SECURITY_CONFIRM_EMAIL_WITHIN`: Specifies the amount of time a user - has to confirm their account/email. Default is `5 days`. -* :attr:`SECURITY_RESET_PASSWORD_WITHIN`: Specifies the amount of time a user - has to reset their password. Default is `5 days`. -* :attr:`SECURITY_LOGIN_WITHOUT_CONFIRMATION`: Specifies if users can login - without first confirming their accounts. Defaults to `False` -* :attr:`SECURITY_EMAIL_SENDER`: Specifies the email address to send emails on - behalf of. Defaults to `no-reply@localhost`. -* :attr:`SECURITY_TOKEN_AUTHENTICATION_KEY`: Specifies the query string argument - to use during token authentication. Defaults to `auth_token`. -* :attr:`SECURITY_TOKEN_AUTHENTICATION_HEADER`: Specifies the header name to use - during token authentication. Defaults to `X-Auth-Token`. -* :attr:`SECURITY_CONFIRM_SALT`: Specifies the salt value to use for account - confirmation tokens. Defaults to `confirm-salt`. -* :attr:`SECURITY_RESET_SALT`: Specifies the salt value to use for password - reset tokens. Defaults to `reset-salt`. -* :attr:`SECURITY_AUTH_SALT`: Specifies the salt value to use for token based - authentication tokens. Defaults to `auth-salt`. -* :attr:`SECURITY_DEFAULT_HTTP_AUTH_REALM`: Specifies the default basic HTTP - authentication realm. Defaults to `Login Required`. \ No newline at end of file +Core +-------------- + +.. tabularcolumns:: |p{6.5cm}|p{8.5cm}| + +======================================== ======================================= +``SECURITY_BLUEPRINT_NAME`` Specifies the name for the + Flask-Security blueprint. Defaults to + ``security``. +``SECURITY_URL_PREFIX`` Specifies the URL prefix for the + Flask-Security blueprint. Defaults to + ``None``. +``SECURITY_FLASH_MESSAGES`` Specifies wether or not to flash + messages during security procedures. + Defaults to ``True``. +``SECURITY_PASSWORD_HASH`` Specifies the password hash algorith to + use when encrypting and decrypting + passwords. Recommended values for + production systems are ``bcrypt``, + ``sha512_crypt``, or ``pbkdf2_sha512``. + Defaults to ``plaintext``. +``SECURITY_PASSWORD_HMAC`` Specifies if Flask-Security should also + use HMAC when encrypting and decrypting + passwords. If set to ``True`` be sure + to specify a salt value via the + ``SECURITY_PASSWORD_HMAC_SALT`` + configuration option. Defaults to + ``False``. +``SECURITY_PASSWORD_HMAC_SALT`` Specifies the HMAC salt. Defaults to + ``None``. +``SECURITY_EMAIL_SENDER`` Specifies the email address to send + emails as. Defaults to + ``no-reply@localhost``. +``SECURITY_TOKEN_AUTHENTICATION_KEY`` Specifies the query sting parameter to + read when using token authentication. + Defaults to ``auth_token``. +``SECURITY_TOKEN_AUTHENTICATION_HEADER`` Specifies the HTTP header to read when + using token authentication. Defaults to + ``Authentication-Token``. +``SECURITY_DEFAULT_HTTP_AUTH_REALM`` Specifies the default authentication + realm when using basic HTTP auth. + Defaults to ``Login Required`` +======================================== ======================================= + + +URLs and Views +-------------- + +.. tabularcolumns:: |p{6.5cm}|p{8.5cm}| + +=============================== ================================================ +``SECURITY_LOGIN_URL`` Specifies the login URL. Defaults to ``/login``. +``SECURITY_LOGOUT_URL`` Specifies the logout URL. Defaults to + ``/logout``. +``SECURITY_REGISTER_URL`` Specifies the register URL. Defaults to + ``/register``. +``SECURITY_RESET_URL`` Specifies the password reset URL. Defaults to + ``/reset``. +``SECURITY_CONFIRM_URL`` Specifies the email confirmation URL. Defaults + to ``/confirm``. +``SECURITY_POST_LOGIN_VIEW`` Specifies the default view to redirect to after + a user logs in. This value can be set to a URL + or an endpoint name. Defaults to ``/``. +``SECURITY_POST_LOGOUT_VIEW`` Specifies the default view to redirect to after + a user logs out. This value can be set to a URL + or an endpoint name. Defaults to ``/``. +``SECURITY_CONFIRM_ERROR_VIEW`` Specifies the view to redirect to if a + confirmation error occurs. This value can be set + to a URL or an endpoint name. If this value is + ``None`` the user is presented the default view + to resend a confirmation link. Defaults to + ``None``. +``SECURITY_POST_REGISTER_VIEW`` Specifies the view to redirect to after a user + successfully registers. This value can be set to + a URL or an endpoint name. If this value is + ``None`` the user is redirected to the value of + ``SECURITY_POST_LOGIN_VIEW``. Defaults to + ``None``. +``SECURITY_POST_CONFIRM_VIEW`` Specifies the view to redirect to after a user + successfully confirms their email. This value + can be set to a URL or an endpoint name. If this + value is ``None`` the user is redirected to the + value of ``SECURITY_POST_LOGIN_VIEW``. Defaults + to ``None``. +``SECURITY_POST_RESET_VIEW`` Specifies the view to redirect to after a user + successfully resets their password. This value + can be set to a URL or an endpoint name. If this + value is ``None`` the user is redirected to the + value of ``SECURITY_POST_LOGIN_VIEW``. Defaults to + ``None``. +``SECURITY_UNAUTHORIZED_VIEW`` Specifies the view to redirect to if a user + attempts to access a URL/endpoint that they do + not have permission to access. If this value is + ``None`` the user is presented with a default + HTTP 403 response. Defaults to ``None``. +=============================== ================================================ + + +Feature Flags +------------- + +.. tabularcolumns:: |p{6.5cm}|p{8.5cm}| + +========================= ====================================================== +``SECURITY_CONFIRMABLE`` Specifies if users are required to confirm their email + address when registering a new account. If this value + is `True` Flask-Security creates an endpoint to handle + confirmations and requests to resend confirmation + instructions. The URL for this endpoint is specified + by the ``SECURITY_CONFIRM_URL`` configuration option. + Defaults to ``False``. +``SECURITY_REGISTERABLE`` Specifies if Flask-Security should create a user + registration endpoint. The URL for this endpoint is + specified by the ``SECURITY_REGISTER_URL`` + configuration option. Defaults to ``False``. +``SECURITY_RECOVERABLE`` Specifies if Flask-Security should create a password + reset/recover endpoint. The URL for this endpoint is + specified by the ``SECURITY_RESET_URL`` configuration + option. Defaults to ``False``. +``SECURITY_TRACKABLE`` Specifies if Flask-Security should track basic user + login statistics. If set to ``True`` ensure your + models have the required fields/attribues. Defaults to + ``False`` +``SECURITY_PASSWORDLESS`` Specifies if Flask-Security should enable the + passwordless login feature. If set to ``True`` users + are not required to enter a password to login but are + sent an email with a login link. This feature is + experimental and should be used with caution. Defaults + to ``False``. +========================= ====================================================== + + +Miscellaneous +------------- + +.. tabularcolumns:: |p{6.5cm}|p{8.5cm}| + +======================================= ======================================== +``SECURITY_CONFIRM_EMAIL_WITHIN`` Specifies the amount of time a user has + before their confirmation link expires. + Always pluralized the time unit for this + value. Defaults to ``5 days``. +``SECURITY_RESET_PASSWORD_WITHIN`` Specifies the amount of time a user has + before their password reset link + expires. Always pluralized the time unit + for this value. Defaults to ``5 days``. +``SECURITY_LOGIN_WITHIN`` Specifies the amount of time a user has + before a login link expires. This is + only used when the passwordless login + feature is enabled. Always pluralized + the time unit for this value. Defaults + to ``1 days``. +``SECURITY_LOGIN_WITHOUT_CONFIRMATION`` Specifies if a user may login before + confirming their email when the value + of ``SECURITY_CONFIRMABLE`` is set to + ``True``. Defaults to ``False``. +``SECURITY_CONFIRM_SALT`` Specifies the salt value when generating + confirmation links/tokens. Defaults to + ``confirm-salt``. +``SECURITY_RESET_SALT`` Specifies the salt value when generating + password reset links/tokens. Defaults to + ``reset-salt``. +``SECURITY_LOGIN_SALT`` Specifies the salt value when generating + login links/tokens. Defaults to + ``login-salt``. +``SECURITY_REMEMBER_SALT`` Specifies the salt value when generating + remember tokens. Remember tokens are + used instead of user ID's as it is more + secure. Defaults to ``remember-salt``. +======================================= ======================================== diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index f0431f1..45ff59e 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -1,5 +1,5 @@ -Documentation -------------- +Contents +-------- .. toctree:: :maxdepth: 1 @@ -9,5 +9,6 @@ Documentation configuration quickstart models + customizing api changelog \ No newline at end of file diff --git a/docs/customizing.rst b/docs/customizing.rst new file mode 100644 index 0000000..ba7c857 --- /dev/null +++ b/docs/customizing.rst @@ -0,0 +1,95 @@ +Customizing Views +================= + +Flask-Security bootstraps your application with various views for handling its +configured features to get you up and running as quick as possible. However, +you'll probably want to change the way these views look to be more in line with +your application's visual design. + + +Views +----- + +Flask-Security is packaged with a default template for each view it presents to +a user. Templates are located within a subfolder named ``security``. The +following is a list of view templates: + +* `security/forgot_password.html` +* `security/login_user.html` +* `security/register_user.html` +* `security/reset_password.html` +* `security/send_confirmation.html` +* `security/send_login.html` + +Overriding these templates is simple: + +1. Create a folder named ``security`` within your application's templates folder +2. Create a template with the same name for the template you wish to override + +Each template is passed a template context object that includes the following, +including the objects/values that are passed to the template by the main +Flask application context processory: + +* ``_form``: A form object for the view +* ``security``: The Flask-Security extension object + +To add more values to the template context you can specify a context processor +for all views or a specific view. For example:: + + security = Security(app, user_datastore) + + # This processor is added to all templates + @security.context_processor + def security_context_processor(): + return dict(hello="world") + + # This processor is added to only the register view + @security.register_context_processor + def security_register_processor(): + return dict(something="else") + +The following is a list of all the available context processor decorators: + +* ``context_processor``: All views +* ``forgot_password_context_processor``: Forgot password view +* ``login_context_processor``: Login view +* ``register_context_processor``: Register view +* ``reset_password_context_processor``: Reset password view +* ``send_confirmation_context_processor``: Send confirmation view +* ``send_login_context_processor``: Send login view + + +Emails +------ + +Flask-Security is also packaged with a default tempalte for each email that it +may send. Templates are located within the subfolder named ``security/mail``. +The following is a list of email templates: + +* `security/mail/confirmation_instructions.html` +* `security/mail/confirmation_instructions.txt` +* `security/mail/login_instructions.html` +* `security/mail/login_instructions.txt` +* `security/mail/reset_instructions.html` +* `security/mail/reset_instructions.txt` +* `security/mail/reset_notice.html` +* `security/mail/reset_notice.txt` +* `security/mail/welcome.html` +* `security/mail/welcome.txt` + +Overriding these templates is simple: + +1. Create a folder named ``security`` within your application's templates folder +2. Create a folder named ``email`` within the ``security`` folder +3. Create a template with the same name for the template you wish to override + +Each template is passed a template context object that includes values for any +links that are required in the email. If you require more values in the +templates you can specify an email context processor. For example:: + + security = Security(app, user_datastore) + + # This processor is added to all emails + @security.email_context_processor + def security_mail_processor(): + return dict(hello="world") \ No newline at end of file diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 1aed990..ab42032 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -5,29 +5,14 @@ Quick Start Installation ------------ -First, install Flask-Security:: +Install requirements: $ mkvirtualenv - $ pip install flask-security - -Then install your datastore requirement. - -**SQLAlchemy**:: - - $ pip install flask-sqlalchemy - -**MongoEngine**:: - - $ pip install flask-mongoengine - -And lastly install any password encryption library that you may need. For -example:: - - $ pip install py-bcrypt + $ pip install flask-security, flask-sqlalchemy -Application Code ----------------- +Basic Application +----------------- The following code sample illustrates how to get started as quickly as possible using SQLAlchemy.::