{"id":22787345,"url":"https://github.com/aserto-dev/aserto-rails","last_synced_at":"2025-10-25T21:36:39.584Z","repository":{"id":48182730,"uuid":"516004098","full_name":"aserto-dev/aserto-rails","owner":"aserto-dev","description":"Aserto authorization library for Ruby and Ruby on Rails.","archived":false,"fork":false,"pushed_at":"2025-03-17T11:46:27.000Z","size":94,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-07T12:32:43.130Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aserto-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2022-07-20T13:59:09.000Z","updated_at":"2025-03-17T11:46:37.000Z","dependencies_parsed_at":"2022-08-12T19:41:13.133Z","dependency_job_id":"b35a0b1b-5b3e-4021-a9be-9a1dd03f0b4c","html_url":"https://github.com/aserto-dev/aserto-rails","commit_stats":{"total_commits":30,"total_committers":4,"mean_commits":7.5,"dds":0.09999999999999998,"last_synced_commit":"351295081f4e0129b3b44fff641ce34366624316"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/aserto-dev/aserto-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aserto-dev","download_url":"https://codeload.github.com/aserto-dev/aserto-rails/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-rails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281026266,"owners_count":26431753,"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-25T02:00:06.499Z","response_time":81,"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":[],"created_at":"2024-12-12T00:54:16.175Z","updated_at":"2025-10-25T21:36:39.553Z","avatar_url":"https://github.com/aserto-dev.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aserto Rails\n\n[![Gem Version](https://badge.fury.io/rb/aserto-rails.svg)](https://badge.fury.io/rb/aserto-rails)\n[![ci](https://github.com/aserto-dev/aserto-rails/actions/workflows/ci.yaml/badge.svg)](https://github.com/aserto-dev/aserto-rails/actions/workflows/ci.yaml)\n[![slack](https://img.shields.io/badge/slack-Aserto%20Community-brightgreen)](https://asertocommunity.slack.com\n)\n\nAserto authorization library for Ruby and Ruby on Rails.\n\nBuilt on top of [aserto](https://github.com/aserto-dev/aserto-ruby) and [aserto-grpc-authz](https://github.com/aserto-dev/ruby-grpc-authz).\n\n## Prerequisites\n* [Ruby](https://www.ruby-lang.org/en/downloads/) 3.0 or newer.\n* [Rails](https://rubyonrails.org/) 6 or newer.\n* An [Aserto](https://console.aserto.com) account.\n\n## Installation\nAdd to your application Gemfile:\n\n```ruby\ngem \"aserto-rails\"\n```\n\nAnd then execute:\n```bash\nbundle install\n```\nOr install it yourself as:\n```bash\ngem install aserto-rails\n```\n\n## Configuration\nThe following configuration settings are required for authorization:\n - policy_id\n - tenant_id\n - authorizer_api_key\n - policy_root\n\nThese settings can be retrieved from the [Policy Settings](https://console.aserto.com/ui/policies) page of your Aserto account.\n\nOptional parameters:\n\n| Parameter name | Default value | Description |\n| -------------- | ------------- | ----------- |\n| service_url | `\"authorizer.prod.aserto.com:8443\"` | Sets the URL for the authorizer endpoint. |\n| decision | `\"allowed\"` | The decision that will be used when executing an authorizer request. |\n| logger | `STDOUT` | The logger to be used. |\n| identity_mapping | `{ type: :none }` | The strategy for retrieveing the identity, possible values: `:jwt, :sub, :none` |\n\n## Identity\nTo determine the identity of the user, the gem can be configured to use a JWT token or a claim using the `identity_mapping` config.\n```ruby\n# configure the gem to use a JWT token form the `my-auth-header` header.\nconfig.identity_mapping = {\n  type: :jwt,\n  from: \"my-auth-header\",\n}\n```\n```ruby\n# configure the gem to use a claim from the JWT token.\n# This will decode the JWT token and extract the `sub` field from payload.\nconfig.identity_mapping = {\n  type: :sub,\n  from: :sub,\n}\n```\n\nThe whole identity resolution can be overwritten by providing a custom function.\n```ruby\n# config/initializers/aserto.rb\n\n# needs to return a hash with the identity having `type` and `identity` keys.\n# supported types: `:jwt, :sub, :none`\nAserto.with_identity_mapper do |request|\n  {\n    type: :sub,\n    identity: \"my custom identity\",\n  }\nend\n```\n\n## URL path to policy mapping\nBy default, when computing the policy path:\n* converts all slashes to dots\n* converts any character that is not alpha, digit, dot or underscore to underscore\n* converts uppercase characters in the URL path to lowercases\n\nThis behavior can be overwritten by providing a custom function:\n\n```ruby\n# config/initializers/aserto.rb\n\n# must return a String\nAserto.with_policy_path_mapper do |policy_root, request|\n  method = request.request_method\n  path = request.path_info\n\n  \"custom: #{policy_root}.#{method}.#{path}\"\nend\n```\n\n## Resource\nA resource can be any structured data that the authorization policy uses to evaluate decisions. By default, gem do not include a resource in authorization calls.\n\nThis behavior can be overwritten by providing a custom function:\n\n```ruby\n# config/initializers/aserto.rb\n\n# must return a Hash\nAserto.with_resource_mapper do |request|\n  { resource:  request.path_info }\nend\n```\n## Examples\n\n```ruby\n# config/initializers/aserto.rb\nrequire \"aserto/rails\"\n\nAserto.configure do |config|\n  config.enabled = true\n  config.policy_name = \"my-policy-name\"\n  config.instance_label = \"my-instance\"\n  config.authorizer_api_key = Rails.application.credentials.aserto[:authorizer_api_key]\n  config.policy_root = \"peoplefinder\"\n  config.service_url = \"localhost:8282\"\n  config.cert_path = \"/path/to/topaz/cert.crt\"\n  config.decision = \"allowed\"\n  config.logger = Rails.logger\n  config.identity_mapping = {\n    type: :sub,\n    from: :sub\n  }\nend\n```\n\n## Controller helpers\n\n### aserto_authorize!\n\nThe `aserto_authorize!` method in the controller will raise an exception if the user is not able to perform the given action.\n\n```ruby\ndef show\n  aserto_authorize!\n  @post = Post.find(params[:id])\nend\n```\n\nSetting this for every action can be tedious, therefore the `aserto_authorize_resource` method is provided to\nautomatically authorize all actions in a RESTful style resource controller.\nIt will use a before action to load the resource into an instance variable and authorize it for every action.\n\n```ruby\nclass PostsController \u003c ApplicationController\n  aserto_authorize_resource\n  # aserto_authorize_resource only: %i[show]\n  # aserto_authorize_resource except: %i[index]\n\n  def show\n    # getting a single post authorized\n  end\n\n  def index\n    # getting all posts is authorized\n  end\nend\n```\n\n### check!\n\nThe `check!` method in the controller will raise an exception if the user is not able to perform the given action.\n\n```ruby\ndef show\n  # only users in the \"evil_genius\" group are allowed to get this resource\n  check!(object_id: \"evil_genius\", object_type: \"group\", relation: \"member\")\n  @post = Post.find(params[:id])\nend\n```\n\nSetting this for every action can be tedious, therefore the `aserto_check_resource` method is provided to\nautomatically authorize all actions in a RESTful style resource controller.\nIt will use a before action to load the resource into an instance variable and authorize it for every action.\n\n```ruby\nclass PostsController \u003c ApplicationController\n  aserto_authorize_resource\n  # aserto_check_resource only: %i[show], params: { object_id: \"evil_genius\", object_type: \"group\", relation: \"member\" }\n  # aserto_check_resource except: %i[index], params: { object_id: \"evil_genius\", object_type: \"group\", relation: \"member\" }\n\n  def show\n    # getting a single post authorized\n  end\n\n  def index\n    # getting all posts is authorized\n  end\nend\n```\n\n## Check Permissions\n\nThe current user's permissions can then be checked using the `allowed?`, `visible?` and `enabled?` methods in views and controllers.\n\n```erb\n\u003c% if allowed? :get, \"/posts/:id\", @post %\u003e\n  \u003c%= link_to \"View\", @post %\u003e\n\u003c% end %\u003e\n```\n\n## Development\nPrerequisites:\n    - Ruby \u003e= 3.0 to run the code\n\n\n Run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\n\naserto-rails uses [appraisals](https://github.com/thoughtbot/appraisal) to test the code base against multiple versions\nof Rails, as well as the different model adapters.\n\nWhen first developing, you need to run `bundle exec appraisal install`, to install the different sets.\n\nYou can then run all appraisal files (like CI does), with `bundle exec appraisal rake spec` or just run a specific set `bundle exec appraisal rails_7.0.0 rake spec`.\n\nIf you'd like to run a specific set of tests within a specific file or folder you can use `SPEC=path/to/file/or/folder bundle exec appraisal rails_7.0.0 rake spec rake`.\n\nEg: `SPEC=spec/aserto/rails/controller_additions_spec.rb:31 bundle exec appraisal rails_7.0.0 rake spec rake`\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/aserto-dev/aserto-rails. This project is intended to be a safe, welcoming space for collaboration.\n\n## License\n\nThe gem is available as open source under the terms of the [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserto-dev%2Faserto-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faserto-dev%2Faserto-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserto-dev%2Faserto-rails/lists"}