{"id":22787397,"url":"https://github.com/aserto-dev/aserto-ruby","last_synced_at":"2025-04-15T23:39:49.816Z","repository":{"id":42375669,"uuid":"509058750","full_name":"aserto-dev/aserto-ruby","owner":"aserto-dev","description":"Ruby Rack Middleware for Aserto","archived":false,"fork":false,"pushed_at":"2024-03-25T09:37:22.000Z","size":142,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-28T02:04:18.694Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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}},"created_at":"2022-06-30T11:49:51.000Z","updated_at":"2024-06-04T11:41:05.956Z","dependencies_parsed_at":"2024-03-25T10:54:58.133Z","dependency_job_id":null,"html_url":"https://github.com/aserto-dev/aserto-ruby","commit_stats":{"total_commits":38,"total_committers":4,"mean_commits":9.5,"dds":"0.21052631578947367","last_synced_commit":"a78a8f2f5ceb4c67b25b0fc9da599fd6abbb5960"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aserto-dev%2Faserto-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aserto-dev","download_url":"https://codeload.github.com/aserto-dev/aserto-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229313609,"owners_count":18053714,"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":[],"created_at":"2024-12-12T00:56:11.873Z","updated_at":"2024-12-12T00:56:12.366Z","avatar_url":"https://github.com/aserto-dev.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aserto Ruby SDK\n\n[![Gem Version](https://badge.fury.io/rb/aserto.svg)](https://badge.fury.io/rb/aserto)\n[![ci](https://github.com/aserto-dev/aserto-ruby/actions/workflows/ci.yaml/badge.svg)](https://github.com/aserto-dev/aserto-ruby/actions/workflows/ci.yaml)\n[![slack](https://img.shields.io/badge/slack-Aserto%20Community-brightgreen)](https://asertocommunity.slack.com\n)\n\n## Installation\nAdd to your application Gemfile:\n\n```ruby\ngem \"aserto\"\n```\n\nAnd then execute:\n```bash\nbundle install\n```\nOr install it yourself as:\n```bash\ngem install aserto\n```\n\n## Directory\n\nThe Directory APIs can be used to get or set object instances and relation instances. They can also be used to check whether a user has permission or relation on an object instance.\n\n### Directory Client\n\nYou can initialize a directory client as follows:\n\n```ruby\nrequire 'aserto/directory/client'\n\ndirectory_client = Aserto::Directory::V3::Client.new(\n  url: \"directory.eng.aserto.com:8443\",\n  tenant_id: \"aserto-tenant-id\",\n  api_key: \"basic directory api key\",\n)\n```\n\n- `url`: hostname:port of directory service (_required_)\n- `api_key`: API key for directory service (_required_ if using hosted directory)\n- `tenant_id`: Aserto tenant ID (_required_ if using hosted directory)\n- `cert_path`: Path to the grpc service certificate when connecting to the local topaz instance.\n\nSee [Aserto::Directory::V3::Client](https://rubydoc.info/gems/aserto/Aserto/Directory/V3/Client) for full documentation\n\n## Authorizer\n`Aserto::Authorization` is a middleware that allows Ruby applications to use Aserto as the Authorization provider.\n\n### Prerequisites\n* [Ruby](https://www.ruby-lang.org/en/downloads/) 3.0 or newer.\n* An [Aserto](https://console.aserto.com) account.\n\n### Configuration\nThe following configuration settings are required for the authorization middleware:\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\nThe middleware accepts the following optional parameters:\n\n| Parameter name | Default value | Description |\n| -------------- | ------------- | ----------- |\n| enabled | true | Enables or disables Aserto Authorization |\n| policy_name | `\"\"` | The Aserto policy name. |\n| instance_label | `\"\"` | The label of the active policy runtime. |\n| authorizer_api_key | \"\" | The authorizer API Key |\n| tenant_id | \"\" | The Aserto Tenant ID |\n| service_url | `\"localhost:8282\"` | Sets the URL for the authorizer endpoint. |\n| cert_path | `\"\"` | Path to the grpc service certificate when connecting to local topaz instance. |\n| decision | `\"allowed\"` | The decision that will be used by the middleware when creating an authorizer request. |\n| logger | `STDOUT` | The logger to be used by the middleware. |\n| identity_mapping | `{ type: :none }` | The strategy for retrieving the identity, possible values: `:jwt, :sub, :manual, :none` |\n| disabled_for | `[{}]` | Which path and actions to skip the authorization for. |\n| on_unauthorized | `-\u003e { return [403, {}, [\"Forbidden\"]] }`| A lambda that is executed when the authorization fails. |\n\n### Identity\nTo determine the identity of the user, the middleware can be configured to use a JWT token or a claim using the `identity_mapping` config.\n```ruby\n# configure the middleware to use a JWT token from the `my-auth-header` header.\nconfig.identity_mapping = {\n  type: :jwt,\n  from: \"my-auth-header\",\n}\n```\n```ruby\n# configure the middleware to use a claim from the JWT token.\n# This will decode the JWT token and extract the `sub` field from the payload.\nconfig.identity_mapping = {\n  type: :sub,\n  from: :sub,\n}\n```\n\n```ruby\n# configure the middleware to use a manual identity.\nconfig.identity_mapping = {\n  type: :manual,\n  value: \"my-identity\",\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, the middleware:\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 lowercase\n\nThis behaviour 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  \"custom: #{policy_root}.#{method}.#{path}\"\nend\n```\n\n### Resource\nA resource can be any structured data the authorization policy uses to evaluate decisions. By default, middleware does not include a resource in authorization calls.\n\nThis behaviour 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\n### Disable authorization for specific paths\n\nThe middleware exposes a `disable_for` configuration option that\naccepts an array of hashes with the following keys:\n - path - the path to disable authorization for\n - actions - an array of actions to disable authorization for\n\n#### Rails\nYou can find the paths and actions using `bundle exec rails routes`\n```bash\nbundle exec rails routes\n\n  Prefix       Verb   URI Pattern               Controller#Action\n\n  api_v1_users GET    /api/users(.:format)      api/v1/users#index {:format=\u003e:json}\n               POST   /api/users(.:format)      api/v1/users#create {:format=\u003e:json}\n  api_v1_user  GET    /api/users/:id(.:format)  api/v1/users#show {:format=\u003e:json}\n```\n```ruby\n# disables get user by id\nconfig.disabled_for = [\n  {\n    path: '/api/users/:id'\n    actions: [:GET]\n  }\n]\n```\n### Examples\n\n#### Rails\n```ruby\n# config/initializers/aserto.rb\n\nRails.application.config.middleware.use Aserto::Authorization 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  }\n  config.disabled_for = [\n    {\n      path: \"/api/users\",\n      actions: %i[GET POST]\n    },\n    {\n      path: \"/api/authentication\",\n      actions: %i[POST]\n    }\n  ]\n  config.on_unauthorized = lambda do |env|\n    puts env\n    return [403, {}, [\"Forbidden\"]]\n  end\nend\n```\n\n#### Sinatra\n```ruby\n# server.rb\n\n# aserto middleware\nuse Aserto::Authorization do |config|\n  config.enabled = true\n  config.policy_name = \"my-policy-name\"\n  config.authorizer_api_key = ENV['authorizer_api_key']\n  config.policy_root = \"peoplefinder\"\n  config.instance_label = \"my-instance\"\n  config.service_url = \"localhost:8282\"\n  config.cert_path = \"/path/to/topaz/cert.crt\"\n  config.decision = \"allowed\"\n  config.disabled_for = [\n    {\n      path: \"/api/users/:id\",\n      actions: %i[GET]\n    },\n    {\n      path: \"/\",\n      actions: %i[GET]\n    }\n  ]\n\nend\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\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/aserto-dev/aserto-ruby. 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-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faserto-dev%2Faserto-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faserto-dev%2Faserto-ruby/lists"}