{"id":15527228,"url":"https://github.com/jdtornow/challah","last_synced_at":"2025-08-26T12:32:22.440Z","repository":{"id":2314614,"uuid":"3274736","full_name":"jdtornow/challah","owner":"jdtornow","description":"User authorization and session management in Rails.","archived":false,"fork":false,"pushed_at":"2024-10-21T18:32:35.000Z","size":662,"stargazers_count":18,"open_issues_count":3,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-16T22:10:05.524Z","etag":null,"topics":["authentication","rails","ruby"],"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/jdtornow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-01-26T15:22:12.000Z","updated_at":"2024-06-05T14:15:55.000Z","dependencies_parsed_at":"2024-12-16T22:09:27.327Z","dependency_job_id":"0c6a7ea0-2d78-4929-8cb8-cf54123f61df","html_url":"https://github.com/jdtornow/challah","commit_stats":{"total_commits":404,"total_committers":10,"mean_commits":40.4,"dds":"0.34158415841584155","last_synced_commit":"164cbbc4af1e734998606a4653ac782305e80e15"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtornow%2Fchallah","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtornow%2Fchallah/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtornow%2Fchallah/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdtornow%2Fchallah/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdtornow","download_url":"https://codeload.github.com/jdtornow/challah/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231038826,"owners_count":18318700,"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","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","rails","ruby"],"created_at":"2024-10-02T11:05:08.751Z","updated_at":"2024-12-24T02:10:58.717Z","avatar_url":"https://github.com/jdtornow.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Challah\n\n[![CircleCI](https://circleci.com/gh/jdtornow/challah.svg?style=svg)](https://circleci.com/gh/jdtornow/challah) [![Code Climate](https://codeclimate.com/github/jdtornow/challah/badges/gpa.svg)](https://codeclimate.com/github/jdtornow/challah) [![Gem Version](https://badge.fury.io/rb/challah.svg)](https://badge.fury.io/rb/challah)\n\nChallah (pronounced HAH-lah) is a simple Rails authentication gem that provides users a way to authenticate with your app. Most of the functionality within the gem lives within a Rails engine and tries to stay out of the way of your app.\n\nChallah doesn't provide any fancy controllers or views that clutter your app or force you to display information a certain way. That part is up to you. The functionality within Challah is designed to be a starting point for users and sign-ins you can tweak the rest to your app's needs.\n\n## Requirements\n\n* Ruby 2.5.0+\n* Rails 5.2+\n\n## Installation\n\nIn your `Gemfile`\n\n```ruby\ngem \"challah\"\n```\n\n## Set up\n\nOnce the gem has been set up and installed, run the following command to set up the database migrations:\n\n```bash\nrails challah:setup\n```\n\nThis will copy over the necessary migrations to your app and migrate the database. You will be prompted to add the first user as the last step in this process.\n\n### Manual set up\n\nIf you would prefer to handle these steps manually, you can do so by using these rake tasks instead:\n\n```bash\nrails generate challah\nrails challah:unpack:user\nrails db:migrate\n```\n\n### Creating users\n\nSince Challah doesn't provide any controller and views for users there are a few handy rake tasks you can use to create new records.\n\nUse the following task to create a new user:\n\n```bash\n# Creates a new User record\nrails challah:users:create\n```\n\n## User Model\n\nChallah provides the core `User` model for your app, and a database migration to go along with it. You can do anything you want with the model, just leave the `Challah::Userable` concern intact to keep Challah's standard user methods included.\n\nA user is anyone that needs to be able to authenticate (sign in) to the application. Each user requires a first name, last name, email address, username, and password.\n\nBy default a user is marked as \"active\" and is able to log in to your application. If the active status column is toggled to `inactive`, then this user is no longer able to log in. The active status column can be used as a soft-delete function for users.\n\n## Checking for a current user\n\nThe basic way to restrict functionality within your app is to require that someone authenticate (log in) before they can see it. From within your controllers and views you can call the `current_user?` method to determine if someone has authenticated. This method doesn't care about who the user is, or what it has access to, just that it has successfully authenticated and is a valid user.\n\nFor example, restrict the second list item to only users that have logged in:\n\n```erb\n\u003cul\u003e\n  \u003cli\u003e\u003ca href=\"/\"\u003eHome\u003c/a\u003e\u003c/li\u003e\n\n  \u003c% if current_user? %\u003e\n    \u003cli\u003e\u003ca href=\"/secret-stuff\"\u003eSecret Stuff\u003c/a\u003e\u003c/li\u003e\n  \u003c% end %\u003e\n\n  \u003cli\u003e\u003ca href=\"/public-stuff\"\u003eNot-so-secret Stuff\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n```\n\nControllers can also be restricted using `before_action`:\n\n```ruby\nclass WidgetsController \u003c ApplicationController\n  before_action :signin_required\n\n  # ...\nend\n```\n\nOr, you can call `restrict_to_authenticated` instead, which does the same thing:\n\n```ruby\nclass WidgetsController \u003c ApplicationController\n  restrict_to_authenticated\n\n  # ...\nend\n```\n\nAll normal Rails `before_action` options apply, so you can always limit this restriction to a specific action:\n\n\n```ruby\nclass WidgetsController \u003c ApplicationController\n  restrict_to_authenticated only: [ :edit, :update, :destroy ]\n\n  # ...\nend\n```\n\n## Default Routes\n\nBy default, there are a few routes included with the Challah engine. These routes provide a basic method for a username and password sign in page. These routes are:\n\n```text\nGET   /sign-in      # =\u003e SessionsController#new\nPOST  /sign-in      # =\u003e SessionsController#create\nGET   /sign-out     # =\u003e SessionsController#new\n```\n\nFeel free to override the `SessionsController` with something more appropriate for your app.\n\nIf you'd prefer to set up your own \"sign in\" and \"sign out\" actions, you can skip the inclusion of the default routes by adding the following line to an initializer file in your app:\n\n```ruby\n# in config/initializers/challah.rb\nChallah.options[:skip_routes] = true\n```\n\n## Sign In Form\n\nBy default, the sign in form is tucked away within the Challah gem. If you'd like to customize the markup or functionality of the sign in form, you can unpack it into your app by running:\n\n```bash\n# Copy the sign in view into your app\nrails challah:unpack:views\n```\n\nIf necessary, the sessions controller which handles creating new sessions and signing users out can also be unpacked into your app. This is really only recommended if you need to add some custom behavior or have advanced needs.\n\n```bash\n# Copy the sessions controller into your app\nrails challah:unpack:signin\n```\n\n## API Controllers\n\nFor apps that use JSON API controllers, Challah can be used to authenticate a user with a url parameter or an HTTP request header. This feature is disabled by default, so to use it you will need to change the `token_enabled` setting to `true`:\n\n```ruby\n# in config/initializers/challah.rb\nChallah.options[:token_enabled] = true\n```\n\nOnce enabled, this setting will allow the `api_key` for the user to be used to authenticate them via the `token` parameter, or `X-Auth-Token` HTTP header.\n\nFor example, the following request would authenticate a valid active user that has the `api_key` value of `abc123`:\n\n``` shell\ncurl -H \"X-Auth-Token: abc123\" \\\n  -H 'Content-Type: application/json' \\\n  http://localhost:3000/api/test.json\n```\n\nUsing the `token` param, you could write the same thing as:\n\n``` shell\ncurl -H 'Content-Type: application/json' \\\n  http://localhost:3000/api/test.json?token=abc123\n```\n\nIf you'd like to change the HTTP header used to fetch the user's api key from, you can change it using the `token_header` setting:\n\n```ruby\n# in config/initializers/challah.rb\nChallah.options[:token_enabled] = true\nChallah.options[:token_header] = \"X-App-User\"\n```\n\nThen:\n\n``` shell\ncurl -H \"X-App-User: abc123\" \\\n  -H 'Content-Type: application/json' \\\n  http://localhost:3000/api/test.json\n```\n\n_Note: Custom HTTP headers should always start with X-_\n\n## ActionCable\n\nChallah works well with securing your ActionCable channels since Rails 5. Here is a sample `ApplicationCable::Connection` file to secure connections to a valid signed-in user:\n\n```ruby\nmodule ApplicationCable\n  class Connection \u003c ActionCable::Connection::Base\n\n    identified_by :current_user\n\n    def connect\n      self.current_user = find_current_user\n    end\n\n    private\n\n    def find_current_user\n      if user = Challah::Session.find(request)\n        user\n      else\n        reject_unauthorized_connection\n      end\n    end\n\n  end\nend\n```\n\n## User Validations\n\nBy default, the `first_name`, `last_name`, and `email` fields are required on the user model. If you'd prefer to add your own validations and leave the defaults off, you can use the following option within an initializer:\n\n```ruby\n# in config/initializers/challah.rb\nChallah.options[:skip_user_validations] = true\n```\n\n## Authorization Model\n\nThe `Authorization` model can be used to store user credentials for a variety of different sources. By default, usernames and passwords are hashed and stored in this table.\n\nIn addition to the username/password, you can also use the authorizations table to store credentials or tokens for other services as well. For example, you could store a successful Facebook session using the following method:\n\n```ruby\nAuthorization.set({\n  # provider is just a key and can be anything to denote this service\n  provider: :facebook,\n\n  # the user's Facebook UID\n  uid: \"000000\",\n\n  # the user's Facebook-provided access token\n  token: \"abc123\",\n\n  # the user ID to link to this authorization\n  user_id: user.id,\n\n  # (optional, when this token expires)\n  expires_at: 60.minutes.from_now\n})\n```\n\nThen, to remove an authorization, just provide the user'd ID and the provider:\n\n```ruby\nAuthorization.del({\n  provider: :facebook,\n  user_id: user.id\n})\n```\n\n## Full documentation\n\nDocumentation is available at: [http://rubydoc.info/gems/challah](http://rubydoc.info/gems/challah)\n\n## Issues\n\nIf you have any issues or find bugs running Challah, please [report them on Github](https://github.com/jdtornow/challah/issues). While most functions should be stable, Challah is still in its infancy and certain issues may be present.\n\n## Testing\n\nChallah is fully tested using RSpec. To run the test suite, `bundle install` then run:\n\n```bash\nrspec\n```\n\n## License\n\nChallah is released under the [MIT license](http://www.opensource.org/licenses/MIT)\n\nContributions and pull-requests are more than welcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdtornow%2Fchallah","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdtornow%2Fchallah","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdtornow%2Fchallah/lists"}