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