Forem: Mohammed O. Tillawy

[Boost]

Mohammed O. Tillawy — Sun, 23 Feb 2025 17:06:45 +0000

10 Open-Source Documentation Frameworks to Check Out

Silvia O'Dwyer ・ Feb 21

Rails and Keycloak, Authentication, Authorization, part three

Mohammed O. Tillawy — Sat, 17 Aug 2024 17:44:09 +0000

In part one, we have discussed what Keycloak is.
In part two, we have setup our Rails application to use Keycloak for authentication.
In the third part, we will use Keycloak as a an extra security later to provide authorization checks for our API requests.

How does it work

This gem is a simple middle-ware that intercepts and filters the API requests before they are processed by the application.

Let us start with adding the gem rails_keycloak_authorization to our Gemfile.

# Gemfile
gem "rails_keycloak_authorization"

Gem initializer config/initializers/rails_keycloak_authorization.rb

# initializers/rails_keycloak_authorization.rb 

# initializers/rails_keycloak_authorization.rb 

# the realm that contains the open-client client
RailsKeycloakAuthorization.keycloak_auth_client_realm_name = ENV.fetch("KEYCLOAK_AUTH_CLIENT_REALM_NAME", "dummy")

# the subject open-id client containing
RailsKeycloakAuthorization.keycloak_auth_client_id         = ENV.fetch("KEYCLOAK_AUTH_CLIENT_ID", "dummy-client")

# keycloak server_url
RailsKeycloakAuthorization.keycloak_server_url             = ENV.fetch("KEYCLOAK_SERVER_URL", "http://localhost:8080")

# keycloak server_domain
RailsKeycloakAuthorization.keycloak_server_domain          = ENV.fetch("KEYCLOAK_ADMIN_SERVER_DOMAIN", "localhost")

# keycloak realm that contains the admin-client
RailsKeycloakAuthorization.keycloak_admin_realm_name       = ENV.fetch("KEYCLOAK_ADMIN_REALM_NAME", "master")

# keycloak admin_client 
RailsKeycloakAuthorization.keycloak_admin_client_id        = ENV.fetch("KEYCLOAK_ADMIN_CLIENT_ID", "keycloak-admin")

# keycloak admin_client's secret
RailsKeycloakAuthorization.keycloak_admin_client_secret    = ENV.fetch("KEYCLOAK_ADMIN_CLIENT_SECRET", "keycloak-admin-client-secret-xxx")

# List of regext for pattern to protect
RailsKeycloakAuthorization.match_patterns                  = [
  /^\/organizations\.json/,
  /^\/api\/projects/,
  /^\/secrets\.json/,
  /^\/api\/secrets/
]

Now we will add the UI tool, this part is not mandatory, but it will ease the setup.

mount RailsKeycloakAuthorization::Engine, at: "/rka", constraints: lambda { |request| request.remote_ip == "127.0.0.1" }
# Please make sure to secure this route, for the purposes of this tutorial, I will secure it by forcing the remote_ip to be localhost.

Please make sure to restart the server.
Now open the Rails Keycloak Authorization Helper.

This tool consists of four tabs:

1 - Rails routes
In this tab we:

Map Rails controller into Keycloak Authorization Resources
Map Rails controller actions to scopes.
Attach Keycloak scopes to Keycloak resources

2 - Keycloak Policies
In this tab we:

Create policies.

3 - Keycloak Permissions
In this tab web:

Attach Policies to Resources.

4 - Keycloak Resource
You can skip this tab for now, it is work in progress.

So let us do the following:

Setup Routes: SecretsController#index only for managers.

We will:
1 - Create Keycloak resource: secrets_controller
2 - Create Keycloak scope: index
3 - Attach (scope: index) to (resource: secrets_controller)
3 - Create Policy: RKA-Policy-Managment for role: management-client-role
4 - Create Permission: (Policy: RKA-Policy-Managment) + (Resource: secrets_controller) + (Scope: index)
5 - Validate our setup

Let us do it:

Select tab: Rails Routes
- The first route /secret(.:format), click inspect
- click: Create Resource?
- click: Create Scope?
- click: Attach scope index to resource?
- click: Close
Select tab: Keycloak Policies
- In the Name type: RKA-Policy-Management
- From the Role drop-down list select: management-client-role
- Click Create
Select tab: Keycloak Permissions
- From the drop-down list Policy select: RKA-Policy-Management
- From the drop-down list Resource select: secrets_controller
- From the drop-down Scope Select: index
- Click Create

Now it is time to test it:


readonly username="manager@test.com";
readonly password="secret";
function get_access_token {
curl --silent \
    -d 'client_id=dummy-client' \
    -d 'client_secret=dummy-client-super-secret-xxx' \
    -d "username=${username}" \
    -d "password=${password}" \
    -d 'grant_type=password' \
    -d 'response_type=code' \
    -d 'scope=openid' \
    'http://localhost:8080/realms/dummy/protocol/openid-connect/token' | jq -r '.access_token'
}
access_token=$(get_access_token);
readonly url1="http://localhost:3000/secrets.json"
echo requesting ${url1};
curl -H "Authorization: bearer ${access_token}" ${url1};

If you see the input: []%, setup is good.

You can find the source for this project in this Github repo

You can find the docker-compose & tofu setup in this Github repo

You can watch this video for quick walk through:

Rails and Keycloak, Authentication, Authorization, part two

Mohammed O. Tillawy — Sat, 17 Aug 2024 07:11:09 +0000

In the second part, let us setup Keycloak authentication with Rails.

Run Keycloak

First let us run Keycloak with some boilerplate setup.

Please run Keycloak on docker, please use the docker-compose.yml from the following repository to save time.

# checkout this repo
git clone https://github.com/tillawy/rails_keycloak_authorization.git
cd rails_keycloak_authorization/docker
docker compose up

The previous step should run Keycloak on port 8080.
Credentials: Username=admin, password=admin

Let us use opentofu to setup keycloak.

# if you don't have opentofu
brew install opentofu
rails_keycloak_authorization/tofu
tofu apply -var-file=./secrets.tfvars -auto-approve

The previous steps should create:

Keycloak Realm, called (Dummy)
Keycloak admin client with a secret with necessary roles and access
Keycloak client with a secret for our application
couple of users, groups and roles to do our tests

Our Rails project

Let us create our project

rails new ./rails_keycloak_authorization_demo --database=sqlite3
cd rails_keycloak_authorization_demo

Let us create our User model:

bin/rails generate model User

Let us change the migration to use UUID instead of int for id:

vim ./db/migrate/*_create_users.rb

# ./db/migrate/*_create_users.rb

class CreateUsers < ActiveRecord::Migration[7.2]
  def change
    create_table :users, id: false do |t|
      t.primary_key :id, :string, default: -> { "lower(hex(randomblob(16)))" }
      t.string :email, null: false, index: { unique: true }
      t.string :first_name
      t.string :last_name

      t.timestamps
    end
  end
end

Now let us scaffold couple of models:

bin/rails generate scaffold Project name:string
bin/rails generate scaffold Secret name:string

Now migrate changes to database

bin/rails db:migrate

Let us run the server:

bin/rails s

Let us check that our server is up & running using the following links: secrets, projects

Keycloak & Rails & Omniauth setup

Let us add the gems

# Gemfile
gem "omniauth"
gem "omniauth-keycloak"

Let us create an initialize config/initializers/omniauth.rb

# config/initializers/omniauth.rb
Rails.application.config.middleware.use OmniAuth::Builder do
  provider :keycloak_openid, ENV.fetch("KEYCLOAK_AUTH_CLIENT_ID", "dummy-client"),
  ENV.fetch("KEYCLOAK_AUTH_CLIENT_SECRET", "dummy-client-super-secret-xxx"),
  client_options: {
    site: ENV.fetch("KEYCLOAK_SERVER_URL", "http://localhost:8080"),
    realm: ENV.fetch("KEYCLOAK_AUTH_CLIENT_REALM_NAME", "dummy"),
    raise_on_failure: true,
    base_url: ""
  },
  name: "keycloak",
  provider_ignores_state: true
end

OmniAuth.config.logger = Rails.logger

OmniAuth.config.path_prefix = ENV.fetch("KEYCLOAK_AUTH_SERVER_PATH_PREFIX", "/oauth")

OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE if Rails.env.development?

Make sure your restart your Rails server after creating this initializer.

./bin/rails s

let us add omniauth-keycloak routes:

# config/routes.rb
# assume any user visiting root / needs to authenticate
get "/", to: "oauth#new"
# callbacks from keycloak handling 
get "/oauth/:provider/callback", to: "oauth#create"

Let us create the controller to handle our OAuth requests:

class OauthController < ApplicationController

  # to initiate the login process,
  # We will redirect the user to Keycloak with the parameter: redirect_uri
  # the user will be redirected to keycloak, and upon success redirected back to the application

  def new
    port_str = [80, 443].include?(request.port.to_i) ? "" : ":" + request.port.to_s
    redirect_uri = "#{request.scheme}://#{request.host}#{port_str}/oauth/keycloak/callback"
    redirect_uri_escaped = CGI.escape(redirect_uri)
    client_id =  ENV.fetch("KEYCLOAK_CLIENT_ID", "dummy-client")
    realm = ENV.fetch("KEYCLOAK_REALM", "dummy" )
    auth_server_url = ENV.fetch("KEYCLOAK_AUTH_SERVER_URL", "http://localhost:8080" )
    to = "#{auth_server_url}/realms/#{realm}/protocol/openid-connect/auth?response_type=code&client_id=#{client_id}&redirect_uri=#{redirect_uri_escaped}&login=true&scope=openid"
    redirect_to to, allow_other_host: true
  end

  # final callback from keycloak
  # the user is redirected back from keycloak with the user object in request.env

  def create
    current_user = User.find_or_create_by(id: auth_hash.extra.raw_info.sub, email: auth_hash.info.email, first_name: auth_hash.info.first_name, last_name: auth_hash.info.last_name)

    session[:current_user_id] = current_user.id
    redirect_to projects_path
  end

  protected

  def auth_hash
    auth = request.env["omniauth.auth"]
    raise 'NotAuthenticatedError' unless auth

    auth
  end
end

We need a Rails concern to authenticate users on controllers
Please create the concern file app/controllers/concerns/with_current_user.rb

# app/controllers/concerns/with_current_user.rb

module WithCurrentUser
  extend ActiveSupport::Concern
  included do
    before_action :authenticate_user!

    def authenticate_user!
      raise "NotAuthenticatedError" unless current_user
    end

    def current_user
      current_jwt_user(nil_on_failure: true) || (session[:current_user_id] && User.find(session[:current_user_id]))
    end

    def user_with(id:, email:, first_name:, last_name:)
      upsert = User.upsert({ id: id, email: email, first_name: first_name, last_name: last_name }, unique_by: :id)
      User.find(upsert.first["id"])
    end

    def jwk_user_from(jwt:)
      jwk_loader = ->(options) do
        @cached_keys = nil if options[:invalidate] # need to reload the keys
        return @cached_keys if @cached_keys

        keycloak = ENV.fetch("KEYCLOAK_AUTH_SERVER_URL", "http://localhost:8080")
        realm = ENV.fetch("KEYCLOAK_REALM", "dummy")
        uri = URI("#{keycloak}/realms/#{realm}/protocol/openid-connect/certs")
        req = Net::HTTP::Get.new uri
        res = Rails.cache.fetch("jwk_loader-certs") do
          Net::HTTP.start(uri.host, uri.port, open_time: 1, read_timeout: 1, write_timeout: 1) { |http| http.request(req) }
        end
        unless res.is_a?(Net::HTTPSuccess)
          logger.warn res.body
          raise "JWKS #{uri} FAILED"
        end
        @cached_keys ||= JSON.parse res.body
      end

      decoded = JWT.decode(jwt, nil, !Rails.env.test?, { algorithms: [ "RS256" ], jwks: jwk_loader })

      email = decoded[0]["email"] || decoded[0]["preferred_username"]
      id = decoded[0]["sub"]
      logger.debug("found (email:#{email}, id: #{id})")
      { email: email, id: id, first_name: decoded[0]["given_name"], last_name: decoded[0]["family_name"] }
    end

    def extract_token_from(headers:)
      header = headers["Authorization"]
      header&.split(" ")&.last
    end

    def current_jwt_user(nil_on_failure: false)
      return nil unless request.authorization&.downcase&.start_with?("bearer ")

      token = extract_token_from(headers: request.headers)
      begin
        user = jwk_user_from(jwt: token)
        user_with(email: user[:email], id: user[:id], first_name: user[:first_name], last_name: user[:last_name])
      rescue ActiveRecord::RecordNotFound => e
        logger.error("User NOT found in DB, make sure to run Kafka consumer")
        return nil if nil_on_failure
        raise e
      rescue JWT::JWKError => e
        logger.info "ApplicationController current_jwt_user JWT::JWKError " + e.message
        return nil if nil_on_failure
        raise e
      rescue JWT::DecodeError => e
        logger.info "ApplicationController current_jwt_user JWT::DecodeError " + e.message
        return nil if nil_on_failure
        raise e
      end
    end
  end
end

We will enforce authentication on the controllers level, we will use the concern in the controllers include WithCurrentUser:

file: app/controllers/projects_controller.rb

class ProjectsController < ApplicationController
  before_action :set_project, only: %i[ show edit update destroy ]
  include WithCurrentUser   # <!--- Add this line

file: app/controllers/secrets_controller.rb

class SecretsController < ApplicationController
  before_action :set_secret, only: %i[ show edit update destroy ]
  include WithCurrentUser   # <!--- Add this line

Let us test our setup:

Please open link, you should be redirected to Keyloak,
Authenticate using username: test@test.com, password: test.
You should be redirect to back to the http://localhost:3000/projects.
You should see: Welcome tester

Let us test our project using curl / JWT

#!/bin/bash

readonly username="employee@test.com";
readonly password="secret";

function get_access_token {
curl --silent \
    -d 'client_id=dummy-client' \
    -d 'client_secret=dummy-client-super-secret-xxx' \
    -d "username=${username}" \
    -d "password=${password}" \
    -d 'grant_type=password' \
    -d 'response_type=code' \
    -d 'scope=openid' \
    'http://localhost:8080/realms/dummy/protocol/openid-connect/token' | jq -r '.access_token'
}

access_token=$(get_access_token);

readonly url1="http://localhost:3000/projects.json"

echo requesting ${url1};

curl -H "Authorization: bearer ${access_token}" ${url1};

You should see:

[]%

Congratulation!
You have setup Keycloak with Rails.

In the third part of this series, we will setup Authorization for Rails using keycloak.

You can find the source of this project in the repo:

Rails and Keycloak, Authentication Authorization, part one

Mohammed O. Tillawy — Fri, 16 Aug 2024 17:52:48 +0000

First things first, what is Keycloak? and why would you want to use it with Rails?

What is Keycloak?

Keycloak is an open source identity and access management under the CNCF.

What does that mean?
In simple words: Keycloak will find out the identify of your visitors and make sure they are who they claim to be, and maybe grant them proper access to certain resources.

What does Keycloak do for me?

It acts as a standalone authentication system for all your application, Rails, Django, Nodes, etc ...
Your application is an OpenID client that trusts Keycloak.
Keycloak helps you can keep all authentication logic out of your application.
For example:

You can set Google, Microsoft, Gihtub login in Keycloak, and all your applications will get those for free.
Web Authentication, user registration, forgot password, etc ...

Keycloak is highly configurable. You can change Keycloak's behavior without deployment.
You can configure Keycloak using:

Keycloak web interface
Terraform or opentofu using terraform-provider
REST API
Third party libraries that use Keycloak REST APIs, for example Keycloak Admin Ruby

Keycloak is also highly theme-able.

Shall I use Keycloak with Ruby on Rails?

Authentication

Authentication means: making sure someone is in fact who he claims to be.

There are numerous options for authentication for Rails, for example:

Option 1:

You can keep things simple, and use Rails built in authenticate_by.

class User < ActiveRecord::Base
  has_secure_password
end

User.create(name: "John Doe", email: "jdoe@example.com", password: "abc123")

User.authenticate_by(email: "jdoe@example.com", password: "abc123").name

Option 2:

Use devise gem, which is probably the most famous rails authentication system.

Option 3:

Use revise gem, which is very similar to devise gem.

What ever option your choose, you won't go wrong.
But what if you want your users to login seamlessly using the same credentials to your other applications.

You can use doorkeeper gem. Which can convert your Rails application into an identity provider. But this means that one of your applications will be the single source of truth for users management.

Authorization

Authorization means granting users access to specific resources after being authenticated successfully.

There are several options, for example:

CanCanCan.
Pundit.

Both are great options, they are baked for Rails. and each has it's own fan base.

Can Keycloak totally replace Rails authorization systems?

Nope.
CanCanCan & Pundit have the advantage of database access, they can offer fine grained access to every user.

Can Keycloak support Rails authorization systems?

If Keycloak has the users classified into groups, and groups are granted role, Keycloak can offer an extra layer of security for APIs.

We will setup Keycloak authorization for APIs in part 3 of this series.

In part two of this series, we will:

Setup Keycloak using docker and (terraform or opentofu)
Create a Rails demo application and set it up with Keycloak using omniauth.

In part three of this series, we will:

Setup Rails with Keycloak for authorization