Openmaize v1.0.0-beta.5 Openmaize.Login
Module to handle login.
There are five options:
db_module - the module that is used to query the database
- in most cases, this will be generated by
mix openmaize.gen.ectodb
and will be called MyApp.OpenmaizeEcto - if you implement your own database module, it needs to implement the Openmaize.Database behaviour
- in most cases, this will be generated by
storage - store the token in a cookie, which is the default, or not have Openmaize handle the storage
- if you are developing an api or want to store the token in sessionStorage, set storage to nil
unique_id - the name which is used to identify the user (in the database)
- the default is
:username
- this can also be a function which checks the user input and returns an atom
- see the Openmaize.Login.Name module for some example functions
- the default is
add_jwt - the function used to add the JSON Web Token to the response
- the default is
&OpenmaizeJWT.Plug.add_token/5
- the default is
override_exp - set the default number of minutes that a token is valid for (overriding the default)
- the default token validity is set in the OpenmaizeJWT config
- the default is nil (no override)
Remember me
By using the override_exp
option, you can override the default token
validity on a case-by-case basis. This can help you implement a remember
me
option on the login page.
It is recommended that override_exp
is not set too high (in the example
below, it is set to 10_080 [7 days]). In addition, it should not be used
when protecting high, or even medium, value resources.
Examples with Phoenix
Replace MyApp with the name of your application in the examples below.
If you have used the mix openmaize.gen.phoenixauth
command to generate
an Authorize module, the login_user
function in the examples below
will simply call the Authorize.handle_login
function.
In the web/router.ex
file, add the following line (you can use
a different controller and route):
post "/login", PageController, :login_user
And then in the page_controller.ex
file, add:
plug Openmaize.Login, [db_module: MyApp.OpenmaizeEcto] when action in [:login_user]
If you want to use email
to identify the user:
plug Openmaize.Login, [db_module: MyApp.OpenmaizeEcto,
unique_id: :email] when action in [:login_user]
If you want to use email
or username
to identify the user (allowing the
end user a choice):
plug Openmaize.Login, [db_module: MyApp.OpenmaizeEcto,
unique_id: &Openmaize.Login.Name.email_username/1] when action in [:login_user]
And if you want to override the default value for token validity, to implement a ‘remember me’ functionality, for example:
plug Openmaize.Login, [db_module: MyApp.OpenmaizeEcto,
override_exp: 10_080] when action in [:login_user]
The above command creates a token that is valid for 7 days (10080 minutes) if “remember_me” in the user_params is set to true.
Summary
Functions
Handle the login POST request.
If the login is successful and otp_required: true
is not in the
user model, a JSON Web Token will be added to the conn, either in
a cookie or in the body of the response. The conn is then returned.
If otp_required: true
is in the user model, conn.private.openmaize_otp_required
will be set to true, but no token will be issued yet.