{"id":28366898,"url":"https://github.com/pixielabs/balrog","last_synced_at":"2025-10-29T04:38:29.247Z","repository":{"id":34415713,"uuid":"178879246","full_name":"pixielabs/balrog","owner":"pixielabs","description":"A lightweight authorization library for Ruby on Rails that protects your routes with a simple password form.","archived":false,"fork":false,"pushed_at":"2023-01-19T12:49:53.000Z","size":189,"stargazers_count":9,"open_issues_count":26,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-10-07T12:44:30.309Z","etag":null,"topics":["authentication","basic-authentication","ruby","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pixielabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-01T14:19:09.000Z","updated_at":"2023-11-14T19:23:48.000Z","dependencies_parsed_at":"2023-02-11T00:05:19.526Z","dependency_job_id":null,"html_url":"https://github.com/pixielabs/balrog","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/pixielabs/balrog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixielabs%2Fbalrog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixielabs%2Fbalrog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixielabs%2Fbalrog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixielabs%2Fbalrog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pixielabs","download_url":"https://codeload.github.com/pixielabs/balrog/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixielabs%2Fbalrog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281563757,"owners_count":26522696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-29T02:00:06.901Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","basic-authentication","ruby","ruby-on-rails"],"created_at":"2025-05-29T00:13:24.811Z","updated_at":"2025-10-29T04:38:29.229Z","avatar_url":"https://github.com/pixielabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balrog\n\n![Balrog logo](https://user-images.githubusercontent.com/32128719/55335192-9566a000-5492-11e9-9449-746de68fbe94.png)\n\n[![Gem Version](https://badge.fury.io/rb/balrog.svg)](https://badge.fury.io/rb/balrog)\n[![CircleCI](https://circleci.com/gh/pixielabs/balrog.svg?style=svg)](https://circleci.com/gh/pixielabs/balrog)\n\nBalrog is a lightweight authorization library for Ruby on Rails \u003e= 5 written by\n[Pixie Labs](https://pixielabs.io) that can protect your routes. Balrog can be \nconfigured to authorize users using a simple password or single sign-on or both.\n\n- If you choose to protect your routes with a password, the password will be \n stored as a password hash, not plain text, and Balrog provides a lightweight \n HTML form that can be styled and used with password managers.\n- If you choose to configure Balrog to use SSO, you can whitelist multiple email \ndomains, allowing groups of users access parts of your app, without circulating\na password.\n- Balrog's authentication can and should be configured to expire, requiring \nusers to sign-in again in accordance with [OWASP](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#session-expiration) best practices.\n- Balrog can also be used to restrict access to [mounted Rack applications](#Restricting-access-to-mounted-Rack-applications-within-config/routes.rb) like Sidekiq.\n\n## Table of Contents\n\n- [Installation](#Installation)\n- [Regenerating a password hash](#Regenerating-a-password-hash)\n- [Restricting access in a controller](#Restricting-access-in-a-controller)\n- [Restricting access to mounted Rack applications](#Restricting-access-to-mounted-Rack-applications-within-config/routes.rb)\n- [Logout button](#Logout-button)\n- [Changing session expiry length](#Changing-session-expiry-length)\n- [Configuring the Balrog gate view](#Configuring-the-Balrog-gate-view)\n- [Single Sign On](#Single-Sign-On)\n- [Upgrading from 1.1 to 2.0](#Upgrading-from-1.1-to-2.0)\n- [Contributing](#Contributing)\n\n## Installation\n\nAdd the gem to your Gemfile:\n\n```ruby\ngem 'balrog'\n```\n\nRun the installer to generate an initializer:\n\n```shell\n$ bundle exec rails generate balrog:install\nEnter New Password: \nConfirm New Password: \n      create  config/initializers/balrog.rb\n$\n```\n\n## Regenerating a password hash\n\nIf you need to create a new password, modify the hash in the Balrog initializer.\nYou can generate a new hash with the provided Rake task:\n\n```\n$ bundle exec rails balrog:generate_hash\nNew password: *******\nType again: *******\n\n$2a$04$8U/Yun3MZ5..FuT9yUJNK.F2uUuHagtvsD.CNc5lSZegzq9eJjwqu\n\nCopy this hash into config/initializers/balrog.rb\n```\n\n## Restricting access in a controller\n\n```ruby\nclass AdminController \u003c ApplicationController\n  before_action :authenticate_with_balrog!\nend\n```\n\n## Restricting access to mounted Rack applications within config/routes.rb\n\nUse the `.use` [method](https://www.rubydoc.info/gems/rack/Rack%2FBuilder:use) to add Balrog to the 'stack'. \n\nFor example with Sidekiq::Web...\n\n```ruby\n# Then we tell SideKiq to use Balrog::RoutesMiddleware\nSidekiq::Web.use Balrog::RoutesMiddleware\n\nmount Sidekiq::Web =\u003e '/sidekiq'\n```\n\nN.B. If you are mounting Sidekiq Web, you need to [disable Sidekiq Web's session in config/initializers/sidekiq.rb](https://github.com/mperham/sidekiq/issues/3377#issuecomment-381254940).\n\n```ruby\nrequire 'sidekiq/web'\n\n# In order to force sidekiq to use the rails app's session,\n# we need to disable the Sidekiq's session.\nSidekiq::Web.disable(:sessions)\n```\n\n## Logout button\n\nTo add a logout button, you can call the `balrog_logout_button` view helper\nmethod and pass in a hash of HTML options to style it. After logout, the user\nwill be redirected to the root of the app.\n\nFor example, in your view:\n\n```erb\n\u003cul class='nav'\u003e\n  \u003cli\u003e....\u003c/li\u003e\n  \u003cli\u003e\u003c%= balrog_logout_button 'Admin Logout' %\u003e\u003c/li\u003e\n  \u003cli\u003e....\u003c/li\u003e\n\u003c/ul\u003e\n```\n\nOther usage examples:\n\n```erb\n\u003c%= balrog_logout_button %\u003e\n\u003c%= balrog_logout_button \"Leave this place\" %\u003e\n\u003c%= balrog_logout_button \"Click me\", class: 'fancy-button--with-custom-text' %\u003e\n\u003c%= balrog_logout_button class: 'fancy-button--with-default-text' %\u003e\n```\n\n## Changing session expiry length\n\n`set_session_expiry` requires the user to login again after a period of time.\nTo customise this value, open `config/initializers/balrog.rb` after running `balrog:install`\nand change the argument being passed to `set_session_expiry`.\n\nThe argument passed to `set_session_expiry` can be any of the\n[Rails time extensions](https://api.rubyonrails.org/classes/Numeric.html).\n\nIf you don't want sessions to expire, remove `set_session_expiry`\nfrom the initializer completely.\n\n```ruby\nBalrog::Middleware.setup do |config|\n  config.password_hash '$2a$12$BLz7XCFdG9YfwL64KlTgY.T3FY55aQk8SZEzHfpHfw15F2uN1kuSi'\n  config.set_session_expiry 30.minutes\nend\n```\n\n## Configuring the Balrog gate view\n\nWe built Balrog to have a default view and stylesheet so that you can drop \nBalrog into your project and everything should “just work”.\nHowever, we don't want to be in your way if you needed to customise \nyour Balrog gate view.\n\nIf you want to customise the Balrog view, you can run the `balrog:view` \ngenerator, which will copy the required view and layout to your application:\n\n```shell\n$ rails generate balrog:view\n```\n\nAfter running the generator, you can now add elements and classes to the \n`views/balrog/gate.html.erb`, add styles to the \n`assets/stylesheets/application.css` and import the application stylesheet in \n`app/views/layouts/balrog.html.erb`. For an example, see the \n[dummy-rails-app](https://github.com/pixielabs/balrog/tree/master/spec/dummy-rails-app) in the spec folder.\n\n## Single Sign On\n\nTo add single sign on you will need to add the [omniauth gem](https://github.com/omniauth/omniauth)\nto your gem file, along with the omniauth gem for your chosen\n[provider](https://github.com/omniauth/omniauth/wiki/List-of-Strategies).\n\nIn `config/initializers/balrog.rb`, call `config.set_omniauth` in the setup block.\n`.set_omniauth` takes the same arguments as the `OmniAuth::Builder#provider`\n[method](https://github.com/omniauth/omniauth#getting-started),\na provider and any required keys.\n\nTo whitelist any email addresses with a specific domain, call\n`config.set_domain_whitelist`in the setup block and pass in the domain.\nIf you want to whitelist multiple domains, you can pass multiple domains\nto the `.set_domain_whitelist`.\n\nBalrog does not require a password to be set if you wish to use single sign-on only. \n\n```ruby\nBalrog::Middleware.setup do |config|\n  credentials = Rails.application.credentials\n  config.set_omniauth :google_oauth2, credentials.google_client_id, credentials.google_client_secret\n  config.set_domain_whitelist 'pixielabs.io', 'the_fellowship.com'\nend\n```\n**Please note:** there is currently a CSRF vulnerability which affects OmniAuth \n(designated [CVE-2015-9284](https://nvd.nist.gov/vuln/detail/CVE-2015-9284)) \nthat requires mitigation at the application level. More details on how to do \nthis can be found on the [Omniauth Wiki](https://github.com/omniauth/omniauth/wiki/Resolving-CVE-2015-9284).\n\n## Upgrading from 1.1 to 2.0\n\nTo upgrade, you will need to change your Balrog initializer. \n\n1. Instead of calling `Rails.application.config.middleware.use Balrog::Middleware`, you will now need to call `Balrog::Middleware.setup`. \n\n2. Change the block you pass into these methods. `#password_hash` and `#set_session_expiry` now need to called on a block parameter, e.g `set_session_expiry 30.minutes` needs to be changed to `config.set_session_expiry 30.minutes`.\n\nSee below for code examples.\n\n```ruby\n# Balrog 1.1\nRails.application.config.middleware.use Balrog::Middleware do\n  password_hash '$2a$12$I8Fp3e2GfSdM7KFyoMx56.BVdHeeyk9DQWKkdsxw7USvU/mC8a8.q'\n  set_session_expiry 30.minutes\nend\n```\n\n```ruby\n# Balrog 2.0\nBalrog::Middleware.setup do |config|\n  config.set_password_hash '$2a$12$9lquJW6mVYYS1pD1xYMGzulyC6sEDuLIUfkA/Y7F3RQ8psLNYyLeO'\n  config.set_session_expiry 30.minutes\nend\n```\n\n## Contributing\n\n### Running the tests\n\nTests are part of the dummy Rails app within the spec folder. To run the tests:\n\n```\n$ cd spec/dummy-rails-app\n$ bundle\n$ rails generate active_record:session_migration\n$ redis-server\n```\n\nThen in a different terminal:\n\n```\n$ cd spec/dummy-rails-app\n$ rspec\n```\n\nBefore contributing, please read the [code of conduct](CODE_OF_CONDUCT.md).\n- Check out the latest master to make sure the feature hasn't been implemented\n  or the bug hasn't been fixed yet.\n- Check out the issue tracker to make sure someone already hasn't requested it\n  and/or contributed it.\n- Fork the project.\n- Start a feature/bugfix branch.\n- Commit and push until you are happy with your contribution.\n- Please try not to mess with the package.json, version, or history. If you\n  want to have your own version, or is otherwise necessary, that is fine, but\n  please isolate to its own commit so we can cherry-pick around it.\n\n## TODO\n\n * Restricting access via `routes.rb`\n * Test coverage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixielabs%2Fbalrog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixielabs%2Fbalrog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixielabs%2Fbalrog/lists"}