KeycloakOauth

Keycloak integration for Ruby on Rails.

Installation

Add this line to your application's Gemfile:

gem 'keycloak_oauth'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install keycloak_oauth

Usage

Using keycloak_oauth in a Ruby on Rails app

Unless you plan to overwrite the oauth callback controller (see further below), mount the Rails engine into your application by specifying the following in config/routes.rb

mount KeycloakOauth::Engine => "/keycloak_oauth"

The configuration must be defined in the app by initialising the relevant attributes within a configuration block. For example, you could add an initializer script called keycloak_oauth.rb holding the following code:

KeycloakOauth.configure do |config|
  config.auth_url = 'TBA' # (you could reference a Rails credential here for example)
  config.realm = 'TBA'
  config.client_id = 'TBA'
  config.client_secret = 'TBA'
end

This then allows you to access the KeycloakOauth APIs: KeycloakOauth.connection.authorization_endpoint

Ensure you have default_url_options set. Here is an example of default_url_options appropriate for a development environment in config/environments/development.rb:

config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }

You can allow the user to log in with Keycloak by adding a link that points to KeycloakOauth.connection.authorization_endpoint: e.g. <%= link_to 'Login with Keycloak', KeycloakOauth.connection.authorization_endpoint(options: { redirect_uri: keycloak_oauth.oauth2_url }) %>

Once authentication is performed, the access and refresh tokens are stored in the session and can be used in your app as wished. As the session can become larger than we can store in a cookie (CookieOverflow exception), we recommend to use activerecord-session_store.

If you are calling Keycloak in your ApplicationController, for example, as a callback:

  before_action :authenticate_with_keycloak

  def authenticate_with_keycloak
    unless session&.dig(:refresh_token).present? && session&.dig(:access_token).present?
      redirect_to KeycloakOauth.connection.authorization_endpoint(options: { redirect_uri: keycloak_oauth.oauth2_url })
    end
  end

you may get into infinite loop issue, because KeycloakOauth::CallbacksController also inherits from the ApplicationController and keeps redirecting to authentication endpoint. As a workaround, create a BaseController from which the controllers in your application inherit and move the authenticate callback to it.

Customising redirect URIs

There are situations where you would want to customise the oauth2 route (e.g. to use a localised version of the callback URL). In this case, you can do the following:

• add a controller to your app: e.g. CallbackOverrides
• add the following to your routes.rb file: get 'oauth2', to: 'callback_overrides#oauth2'
• add whatever logic you need in the controller, e.g. a skip_before_action; it can also be blank
• add redirect URI to the authorization link: e.g. <%= link_to 'Login with Keycloak', KeycloakOauth.connection.authorization_endpoint(options: {redirect_uri: 'http://myapp.com/en/oauth2'}) %>

Keycloak callback URL Keycloak needs a callback URL to send the authorization code to once a user logs in. By default, once authentication is performed, we redirect to the / path (i.e. whatever the root path is set to in the host app). If you need the user to be redirected to something other than the root path, you can achieve that in the following way:

1. Add a new module (could be a controller concern) e.g. KeycloakOauthCallbacks
2. In this module, define a method after_sign_in_path
3. In the method, perform whatever logic you need to return the right path e.g.

def after_sign_in_path
  main_app.my_custom_path
end

4. Tell the gem where you've overridden the paths by setting the following config in your configuration initializer file:

KeycloakOauth.configure do |config|
  ...
  config.callback_module = KeycloakOauthCallbacks
end

User mapping The host app is responsible for mapping a Keycloak session with a Rails user session. This can be achieved by implementing the map_authenticatable method in the module configured above (e.g. KeycloakOauthCallbacks in our example). You can get the user information by making a call to KeycloakOauth.connection.get_user_information to which you pass in the access token. See here an example of retrieving the user information and saving the email address in the Rails session:

def map_authenticatable(_request)
  service = KeycloakOauth.connection.get_user_information(access_token: session[:access_token], refresh_token: session[:refresh_token])
  session[:user_email_address] = service.user_information['email']
end

Logging out In order to log out, you can use the following API call: KeycloakOauth.connection.logout(session: session)

Note that you need to pass in the session, as the gem needs to remove the Keycloak tokens from there.

e.g.

class SessionsController < ApplicationController
  def destroy
    KeycloakOauth.connection.logout(session: session)
    redirect_to new_session_path
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/simplificator/keycloak_oauth. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the KeycloakOauth project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.