Aserto Ruby SDK
Installation
Add to your application Gemfile:
gem "aserto"And then execute:
bundle installOr install it yourself as:
gem install asertoDirectory
The 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.
Directory Client
You can initialize a directory client as follows:
require 'aserto/directory/client'
directory_client = Aserto::Directory::V3::Client.new(
url: "directory.eng.aserto.com:8443",
tenant_id: "aserto-tenant-id",
api_key: "basic directory api key",
)-
url: hostname:port of directory service (required) -
api_key: API key for directory service (required if using hosted directory) -
tenant_id: Aserto tenant ID (required if using hosted directory) -
cert_path: Path to the grpc service certificate when connecting to the local topaz instance.
See Aserto::Directory::V3::Client for full documentation
Authorizer
Aserto::Authorization is a middleware that allows Ruby applications to use Aserto as the Authorization provider.
Prerequisites
Configuration
The following configuration settings are required for the authorization middleware:
- policy_root
These settings can be retrieved from the Policy Settings page of your Aserto account.
The middleware accepts the following optional parameters:
| Parameter name | Default value | Description |
|---|---|---|
| enabled | true | Enables or disables Aserto Authorization |
| policy_name | "" |
The Aserto policy name. |
| instance_label | "" |
The label of the active policy runtime. |
| authorizer_api_key | "" | The authorizer API Key |
| tenant_id | "" | The Aserto Tenant ID |
| service_url | "localhost:8282" |
Sets the URL for the authorizer endpoint. |
| cert_path | "" |
Path to the grpc service certificate when connecting to local topaz instance. |
| decision | "allowed" |
The decision that will be used by the middleware when creating an authorizer request. |
| logger | STDOUT |
The logger to be used by the middleware. |
| identity_mapping | { type: :none } |
The strategy for retrieving the identity, possible values: :jwt, :sub, :manual, :none
|
| disabled_for | [{}] |
Which path and actions to skip the authorization for. |
| on_unauthorized | -> { return [403, {}, ["Forbidden"]] } |
A lambda that is executed when the authorization fails. |
Identity
To determine the identity of the user, the middleware can be configured to use a JWT token or a claim using the identity_mapping config.
# configure the middleware to use a JWT token from the `my-auth-header` header.
config.identity_mapping = {
type: :jwt,
from: "my-auth-header",
}# configure the middleware to use a claim from the JWT token.
# This will decode the JWT token and extract the `sub` field from the payload.
config.identity_mapping = {
type: :sub,
from: :sub,
}# configure the middleware to use a manual identity.
config.identity_mapping = {
type: :manual,
value: "my-identity",
}The whole identity resolution can be overwritten by providing a custom function.
# config/initializers/aserto.rb
# needs to return a hash with the identity having `type` and `identity` keys.
# supported types: `:jwt, :sub, :none`
Aserto.with_identity_mapper do |request|
{
type: :sub,
identity: "my custom identity",
}
endURL path to policy mapping
By default, when computing the policy path, the middleware:
- converts all slashes to dots
- converts any character that is not alpha, digit, dot or underscore to underscore
- converts uppercase characters in the URL path to lowercase
This behaviour can be overwritten by providing a custom function:
# config/initializers/aserto.rb
# must return a String
Aserto.with_policy_path_mapper do |policy_root, request|
method = request.request_method
path = request.path_info
"custom: #{policy_root}.#{method}.#{path}"
endResource
A resource can be any structured data the authorization policy uses to evaluate decisions. By default, middleware does not include a resource in authorization calls.
This behaviour can be overwritten by providing a custom function:
# config/initializers/aserto.rb
# must return a Hash
Aserto.with_resource_mapper do |request|
{ resource: request.path_info }
endDisable authorization for specific paths
The middleware exposes a disable_for configuration option that
accepts an array of hashes with the following keys:
- path - the path to disable authorization for
- actions - an array of actions to disable authorization for
Rails
You can find the paths and actions using bundle exec rails routes
bundle exec rails routes
Prefix Verb URI Pattern Controller#Action
api_v1_users GET /api/users(.:format) api/v1/users#index {:format=>:json}
POST /api/users(.:format) api/v1/users#create {:format=>:json}
api_v1_user GET /api/users/:id(.:format) api/v1/users#show {:format=>:json}# disables get user by id
config.disabled_for = [
{
path: '/api/users/:id'
actions: [:GET]
}
]Examples
Rails
# config/initializers/aserto.rb
Rails.application.config.middleware.use Aserto::Authorization do |config|
config.enabled = true
config.policy_name = "my-policy-name"
config.instance_label = "my-instance"
config.authorizer_api_key = Rails.application.credentials.aserto[:authorizer_api_key]
config.policy_root = "peoplefinder"
config.service_url = "localhost:8282"
config.cert_path = "/path/to/topaz/cert.crt"
config.decision = "allowed"
config.logger = Rails.logger
config.identity_mapping = {
type: :sub,
from: :sub
}
config.disabled_for = [
{
path: "/api/users",
actions: %i[GET POST]
},
{
path: "/api/authentication",
actions: %i[POST]
}
]
config.on_unauthorized = lambda do |env|
puts env
return [403, {}, ["Forbidden"]]
end
endSinatra
# server.rb
# aserto middleware
use Aserto::Authorization do |config|
config.enabled = true
config.policy_name = "my-policy-name"
config.authorizer_api_key = ENV['authorizer_api_key']
config.policy_root = "peoplefinder"
config.instance_label = "my-instance"
config.service_url = "localhost:8282"
config.cert_path = "/path/to/topaz/cert.crt"
config.decision = "allowed"
config.disabled_for = [
{
path: "/api/users/:id",
actions: %i[GET]
},
{
path: "/",
actions: %i[GET]
}
]
endDevelopment
Prerequisites:
- go >= 1.17 to run mage
- Ruby >= 3.0 to run the code
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.
Contributing
Bug 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.
License
The gem is available as open source under the terms of the Apache-2.0 License.