Although Lucky is fantastic for building complete applications, I like to build my front-end in Angular so I usually use Lucky as a JSON Api. I prefer it over Rails Api because of the type checking, separation of models from forms and queries, and the way actions and routes are organized.
One feature I usually need in a JSON api is authentication, and today we'll go over setting up JWT authentication with Lucky Api.
Starter App
To start we'll be using the lucky api demo app which has User
and Post
models defined. Run:
git clone git@github.com:mikeeus/lucky_api_demo.git
git checkout jwt-auth-0
bin/setup
You can follow along by switching to the branches shown under the headings for each section. Or look at the finished product by checking out jwt-auth-10-complete
Dependencies
branch: jwt-auth-0
The only dependecy we'll need is a shard for jwt encoding and decoding. We can use the crystal jwt package so lets add the following to our shard.yml and run shards
.
dependencies:
jwt:
github: crystal-community/jwt
Begin with Tests
branch: jwt-auth-01-sign-in-test
How else would we know the app is working? Aight, in spec/blog_api_spec.cr
we'll add a describe block for authentication and our first test which will be for signing in.
Note I got AppVisitor
from Hannes Kaeufler's blog which is a great Lucky site that I use as reference.
# spec/blog_api_spec.cr
require "./spec_helper"
describe App do
visitor = AppVisitor.new
...
describe "auth" do
it "signs in valid user" do
# create a user
# visit sign in endpoint
# check response has status: 200 and authorization header with "Bearer"
end
end
end
We'll user Lucky's boxes to make generating test data easy. We'll also use Authentic's generate_encrypted_password
method to generate our password.
# spec/support/boxes/user_box.cr
class UserBox < LuckyRecord::Box
def initialize
name "Mikias"
email "hello@mikias.net"
encrypted_password Authentic.generate_encrypted_password("password")
end
end
Now we can generate a user in our test and make a post request to our sign_in endpoint using its email and password. And we'll check the response for the correct status code and Authorization header.
# spec/blog_api_spec.cr
...
it "signs in valid user" do
# create a user
user = UserBox.new.create
# visit sign in endpoint
visitor.post("/sign_in", ({
"sign_in:email" => user.email,
"sign_in:password" => "password"
}))
# check response has status: 200 and authorization header with "Bearer"
visitor.response.status_code.should eq 200
visitor.response.headers["Authorization"].should_not be_nil
end
...
Now this test will fail because we don't have an action for this route or the forms to handle user creation, so let's build them.
Sign In
branch: jwt-auth-02-sign-in-form
If we generate a normal Lucky app it will come with Authentic already configured and several forms and actions will be generated for us. Currently, Lucky api configures Authentic
but doesn't generate these files so we'll need to add them ourselves and update them to fit our use case.
Form
Let's start with the SignInForm
which will be used to validate the user credentials, generate a token and return it in the Authorization
header of the response. This form will be the same as the one generated by Authentic
in new non-api apps, and we'll also need to create the form mixin FindAuthenticable
which wasn't generated.
# src/forms/mixins/find_authenticable.cr
module FindAuthenticatable
private def find_authenticatable
email.value.try do |value|
UserQuery.new.email(value).first?
end
end
end
# src/forms/sign_in_form.cr
class SignInForm < LuckyRecord::VirtualForm
include Authentic::FormHelpers
include FindAuthenticatable
virtual email : String
virtual password : String
private def validate(user : User?)
if user
unless Authentic.correct_password?(user, password.value.to_s)
password.add_error "is wrong"
end
else
email.add_error "is not in our system"
end
end
end
Action
branch: jwt-auth-03-complete-sign-in
Following Lucky's conventions we're going to create two actions:
lucky gen.action.api SignIn::Create
These commands will generate classes at src/actions/sign_up/create.cr
and src/actions/sign_in/create.cr
and two post routes to /sign_up
and /sign_in
.
Now we'll need a way to generate tokens from our user, we'll put this method in a GenerateToken
mixin because we'll use it in several of our actions.
# src/actions/mixins/auth/generate_token.cr
require "jwt"
module GenerateToken
def generate_token(user)
exp = 14.days.from_now.epoch
data = ({ id: user.id, name: user.name, email: user.email }).to_s
payload = { "sub" => user.id, "user" => Base64.encode(data), "exp" => exp }
JWT.encode(payload, Lucky::Server.settings.secret_key_base, "HS256")
end
end
We also need to make our User
PasswordAuthenticatable
for it to be used with Authentic
. Optionally you can include Carbon::Emailable
and the emailable
method if you plan to send emails to your users on registration, password reset, etc.
# src/models/user.cr
class User < BaseModel
include Carbon::Emailable
include Authentic::PasswordAuthenticatable
table :users do
column name : String
column email : String
column encrypted_password : String
end
def emailable
Carbon::Address.new(email)
end
end
Now we can include GenerateToken
in our SignIn
action and use our SignInForm
to complete the authentication.
# src/actions/auth/sign_in.cr
class SignIn::Create < ApiAction
include GenerateToken
route do
SignInForm.new(params).submit do |form, user|
if user
context.response.headers.add "Authorization", generate_token(user)
head 200
else
head 401
end
end
end
end
Run the specs with crystal spec
and voila! It works! :)
Sign Up
branch: jwt-auth-04-sign-up-test
I don't allow sign ups on my blog so I return head 401
for my SignIn
action but of course you may want to implement it in yours. It's going to be very similar to the SignIn
feature with some slight differences. Let's get to it.
Test
Let's begin by writing a test to create a user, making sure it returns the Authorization
header and that we can query our new user from the database.
# spec/blog_api_spec.cr
describe App do
...
describe "auth" do
...
it "creates user on sign up" do
visitor.post("/sign_up", ({
"sign_up:name" => "New User",
"sign_up:email" => "test@email.com",
"sign_up:password" => "password",
"sign_up:password_confirmation" => "password"
}))
visitor.response.status_code.should eq 200
visitor.response.headers["Authorization"].should_not be_nil
UserQuery.new.email("test@email.com").first.should_not be_nil
end
...
end
Form
branch: jwt-auth-05-sign-up-form
Now our SignUpForm
will need a PasswordValidations
module to check the passwords, we'll create that first.
# src/forms/mixins/password_validations.cr
module PasswordValidations
private def run_password_validations
validate_required password, password_confirmation
validate_confirmation_of password, with: password_confirmation
validate_size_of password, min: 6
end
end
With that we can build our sign up form.
# src/forms/sign_up_form.cr
class SignUpForm < User::BaseForm
include PasswordValidations
fillable name, email
virtual password : String
virtual password_confirmation : String
def prepare
validate_uniqueness_of email
run_password_validations
Authentic.copy_and_encrypt password, to: encrypted_password
end
end
Action
branch: jwt-auth-06-complete-sign-up
With those two things done our we can create our SignUp::Create
action which will look exactly the same as our SignIn::Create
action. Run lucky gen.action.api SignUp::Create
and fill it in:
# src/actions/sign_up/create.cr
class SignUp::Create < ApiAction
include GenerateToken
route do
SignUpForm.create(params) do |form, user|
if user
context.response.headers.add "Authorization", generate_token(user)
head 200
else
head 401
end
end
end
end
Now we can run our tests and watch them pass!
Protecting Routes
Great we can sign in and sign out, but what good does that do us if we can't protect our resources based on it? Since every action in lucky inerits from ApiAction
or BrowserAction
, it's very straight forward to build our own AuthenticatedAction
that handles getting the current user from the Authorization
header and returning head 401
if it's not valid.
Test
branch: jwt-auth-07-authenticated-action-test
First let's write test to make sure our feature works as expected. Since we are creating posts with this api, lets make sure that the endpoint is protected. We'll create two specs and update an older one that will be effected by our changes.
Make sure to include the GenerateToken
module in our specs so we can mock an authenticated request.
# spec/blog_api_spec.cr
describe App do
include GenerateToken
...
describe "/posts" do
...
it "creates post" do
user = UserBox.create
visitor.post("/posts",
new_post_data,
{ "Authorization" => generate_token(user) })
visitor.response_body["title"].should eq "New Post"
end
end
...
describe "auth" do
...
it "allows authenticated users to create posts" do
user = UserBox.create
visitor.post("/posts",
new_post_data,
{ "Authorization" => generate_token(user) })
visitor.response_body["title"].should eq new_post_data["post:title"]
end
it "rejects unauthenticated requests to protected actions" do
visitor.post("/posts", new_post_data)
visitor.response.status_code.should eq 401
end
end
end
Now our tests will definitely be failing so lets build our AuthenticatedAction
to make them pass.
AuthenticatedAction
In order to do so we'll need a way to get the user from the token, so lets create a mixin called UserFromToken
to do just that.
Note I chose to use mixins for generating and parsing tokens but you can also include these methods directly in the user model.
# src/actions/mixins/user_from_token.cr
module UserFromToken
def user_from_token(token : String)
payload, _header = JWT.decode(token, Lucky::Server.settings.secret_key_base, "HS256")
UserQuery.new.find(payload["sub"].to_s)
end
end
Now we can use that in our AuthenticatedAction
class.
# src/actions/authenticated_action.cr
abstract class AuthenticatedAction < ApiAction
include UserFromToken
before require_current_user
getter current_user : User? = nil
private def require_current_user
token = context.request.headers["Authorization"]?
if token.nil?
head 401
else
@current_user = user_from_token(token)
end
if @current_user.nil?
head 401
else
continue
end
rescue JWT::ExpiredSignatureError
head 401
end
def current_user
@current_user.not_nil!
end
end
So what's happening here? We use a callback before
to run require_current_user
before the action is called. In that method we get the user from the Authorization
token and set it to the current_user
getter. If there is no token, if the user doesn't exist or if the token is expired (raises JWT::ExpiredSignatureError
) we return 401
.
We also add a current_user
method to alias our nilable getter for convenience in our actions.
Protect Actions
branch: jwt-auth-09-complete-authenticated-action
Now we can use it in our Posts::Create
action.
class Posts::Create < AuthenticatedAction # changed this
route do
post = PostForm.create!(params, author: current_user) # and this
json Posts::ShowSerializer.new(post), Status::Created
end
end
Now we can run our specs... and BOOM! Protected.
That's whats up.
Join Us
I hope you enjoyed this tutorial and found it useful. Join us on the Lucky gitter channel to stay up to date on the framework or checkout the docs for more information on how to bring your app idea to life with Lucky.
Top comments (1)
So nice ! Thanks you
I have a post for sharing!
Angular SpringBoot Jwt Authentication Example:
loizenai.com/angular-10-spring-boo...
Please check it for feedback! Thanks