rails_keycloak_authorization

Rails Keycloak Authorization

You can find more in this blog.

Rails middleware to authorize requests using Keycloak and gem keycloak-admin-ruby.

This gem uses JWT token to authorize requests. To read more how this gem works:

• Keycloak authorization services
• Policy Enforcement Point (PEP)

For the moment it only support permission_resource_format=uri. it does not support permission_resource_format=resource.

It does not support rails cookie-based-sessions, so it is only suitable for APIs.

This gem uses regular-expression for URLs matching, so it is very powerful and flexible.

How it works

This gem is a middleware that checks if the request is authorized by Keycloak. It will check if the request's token is valid and if the user has the required roles to access the requested resource.

Keycloak setup for authorization has many options, the following conventions were followed building this gem:

Rails component	Keycloak component
Controller	Authz Resource
Controller Action	Authz Scope
Route	permission subject

Flow

sequenceDiagram
    actor User
    User->>Application: Request ${URL} with ${JWT_TOKEN}
    create participant Keycloak
    Application-->>Keycloak: is ${JWT_TOKEN} authorized for ${URL}?
    note right of Keycloak: Keycloak will validate the token <br/> and check if the user has the required roles
    destroy Keycloak
    Keycloak-->>Application: ${JWT_TOKEN} is authorized for ${URL}
    destroy Application
    Application-->>User: Response ${URL} with ${DATA}

Configuration

In order to use this gem, you need to configure it in an initializer file. You can create a new file in config/initializers/rails_keycloak_authorization.rb with the following content:

RailsKeycloakAuthorization.keycloak_auth_client_realm_name = ENV.fetch("KEYCLOAK_AUTH_CLIENT_REALM_NAME", "dummy")
RailsKeycloakAuthorization.keycloak_auth_client_id         = ENV.fetch("KEYCLOAK_AUTH_CLIENT_ID", "dummy-client")
RailsKeycloakAuthorization.keycloak_server_url             = ENV.fetch("KEYCLOAK_SERVER_URL", "http://localhost:8080")
RailsKeycloakAuthorization.keycloak_server_domain          = ENV.fetch("KEYCLOAK_ADMIN_SERVER_DOMAIN", "localhost")
RailsKeycloakAuthorization.keycloak_admin_realm_name       = ENV.fetch("KEYCLOAK_ADMIN_REALM_NAME", "master")
RailsKeycloakAuthorization.keycloak_admin_client_id        = ENV.fetch("KEYCLOAK_ADMIN_CLIENT_ID", "keycloak-admin")
RailsKeycloakAuthorization.keycloak_admin_client_secret    = ENV.fetch("KEYCLOAK_ADMIN_CLIENT_SECRET", "keycloak-admin-client-secret-xxx")
RailsKeycloakAuthorization.match_patterns                  = [
  /^\/organizations(\.json)?/,
  /^\/api/,
  /internal/
]

Add the route to the UI helper config/routes.rb:

# make sure to change the constraint to suite your security
mount RailsKeycloakAuthorization::Engine, at: "/rka", constraints: lambda { |request| request.remote_ip == "127.0.0.1" }

How to easily test it?

Create development environment with Keycloak and Tofu:

• checkout the source-code of this project
  • git checkout https://github.com/tillawy/rails_keycloak_authorization.git
  • cd rails_keycloak_authorization
• Run keycloak in a Docker container
  • cd docker
  • docker-compose up
  • verify keycloak is running at http://localhost:8080, username: admin, password: admin
• Run tofu to setup keycloak realm & client
  • brew install opentofu
  • cd ../tofu
  • tofu -chdir=tofu init
  • tofu -chdir=tofu apply -auto-approve

Running the previous steps should:

• Start Keycloak server
• Create realm called: Dummy
• Create openid-client called: dummy-client in realm dummy with:
  • client secret dummy-client-super-secret-xxx
  • valid_redirect_uri http://localhost:3000/*
• Create user [e-mail] with password test
• Create openid-client called: keycloak-admin in realm master with:
  • client secret keycloak-admin-client-secret-xxx
  • role to manager users in realm dummy

Run the server:

bundle exec rails s

make the first request (should fail) Authorization Failed:

bash test/curl/test.curl.bash

How let us setup Authorization:

• Open rka http://localhost:3000/rka/management/
• On the first tab Rails Routes
• The first route /organizations(.:format), click inspect
• Click on Create Resource? to create Authz Resource for controller
• Click on Create Scope? to create resource for controller action
• Click on Attach scope index to resource to attach the scope (action: index) to the resource (controller: organizations_controller)
• Select the second tab Keycloak Policies
• From the Role dropdown list select default-roles-dummy
• Click Create
• Select the third tab Keycloak Permissions
• From the Policy dropdown list select RKA-Policy
• From the Resource dropdown list select organization_controllers
• Another dropdown will appear Select Scope, select index
• Click Create

Now let us run the test bash test/curl/test.curl.bash again, it should pass.

Installation

Add this line to your application's Gemfile:

gem "rails_keycloak_authorization"

And then execute:

$ bundle

Contributing

Contribution directions go here.

License

The gem is available as open source under the terms of the MIT License.