Skip to main content

Ruby Quickstart

Prerequisites:

This guide assumes you have created at least one policy in Permit. If you haven't, complete the Quickstart first.

1. Get your Permit Environment API Key​

  • In the Permit Dashboard, navigate to the Projects screen.
  • Find the Project and Environment you want to connect to.
  • Click the Dots icon on the top right of the environment card.
  • Click Copy API Key.
Copy secret key from user menu
note

You can also copy the API key of the active environment from User Menu > Copy Environment Key.

Copy secret key from Projects management
Remember

The API key you copy from the user menu belongs to the active environment in the sidebar. If you switch the active environment and click Copy Environment Key again, you copy a different API key: the key of the newly active environment.

2. Setup your PDP (Policy Decision Point) Container​

Your application sends permission checks to a policy decision point (PDP), the microservice that evaluates your policy. Run the PDP as a Docker container, or use the managed Cloud PDP that Permit.io runs for you.

To use the Cloud PDP, pass the Cloud PDP URL when you initialize the Permit SDK.

note

Cloud PDP is a managed, production-ready service that Permit.io runs for you. It supports RBAC and ReBAC authorization models, but does not support ABAC.

For more details on capabilities, limits, and when to use Cloud PDP vs. a container PDP, see Cloud PDP Capabilities.

// This line initializes the SDK and connects your app
// to the Permit.io Cloud PDP.

const permit = new Permit({
  pdp: "https://cloudpdp.api.permit.io",
  // your API Key
  token: "[YOUR_API_KEY]",
});

Add the SDK to your Ruby code​

Initialise the Ruby SDK and check for permissions.

  1. Install the Permit.io SDK for Ruby
gem install permit-sdk
  1. Import the SDK into your code
require 'permit-sdk'
  1. Create a new instance of the SDK.
    You can find instructions on getting a secret API key in the previous section.
require 'permit-sdk'
permit = Permit.new("TOKEN", "localhost:7766") # the PDP url is optional

Check for permissions using the SDK​

You can run a permission check with permit.check(). You need to pass 3 arguments to the function:

  • user: a unique user that identifies the user doing the action - this can be created using hash or a string.
  • action: the action performed, as string.
  • resource: the resource the action is performed on - this can be created using a hash or a string.

In the following examples we are checking that a user with the unique key john@permit.io can create a document resource.

Here is an example using strings:

require 'permit-sdk'
permit = Permit.new("TOKEN", "localhost:7766") # the PDP url is optional

permitted = permit.check("john@permit.io", "create" , "document")
if permitted
  puts "john@permit.io is permitted to create a document"
else
  puts "john@permit.io is not permitted to create a document"
end

And here is an example using Hash objects:

require 'permit-sdk'
permit = Permit.new("TOKEN", "localhost:7766") # the PDP url is optional

user_hash = {"key": "john@permit.io", "first_name": "john", "last_name": "doe", "email": "john@permit.io"}
resource_hash = {"type": "document", "tenant": "default"}
permitted = permit.check(user_hash, "create" , resource_hash)
if permitted
  puts "john@permit.io is permitted to create a document"
else
  puts "john@permit.io is not permitted to create a document"
end
info

Usually instead of an email you'd use the unique identifier provided by your chosen authentication solution. You can also pass the entire decoded JWT, to include attributes about the user.

REMEMBER

In cases where you are dealing with more than one tenant in your application, Permit.check() can pass the tenant as part of the resource like we showed before in the Hash objects example.

The tenant passed in needs to be either the tenant id or the tenant key.

You can use the list_tenants API to get the ids and keys set for your tenants.

tenant: a unique tenant id or tenant key that you have defined within Permit.

if permit.check("user", "action", { "key": "resource", "tenant": "tenant" })
  # Allow to close document
end

Check permissions against ABAC policies​

Above we have checked for permissions against an RBAC policy - but what if we have an ABAC policy we want to run a permission check for? An ABAC policy is made up of User Sets and Resource Sets, which you can read more about here.

With ABAC we define conditions based on pre-configured attributes.

If we are running a permit.check() for an ABAC policy, we replace the userId and the resource with objects, containing attributes.

if permit.check(user, 'close', { "key": "resource", "attributes": {"hasApproval": "true"} })
  # Allow to close document
end
REMEMBER

Permission checks are being run against the PDP container that's running locally on your machine - offering minimal latency and without leaving your network.

This means that your user data never goes outside your system, keeping security high.

Full app example​

Assuming a Ruby app made up of a single file, with the permit-sdk and webrick gem packages installed with the following command :

gem install permit-sdk webrick

Here is a full example of a Ruby app that uses the Permit.io SDK to check for permissions:

require 'webrick'
require 'permit-sdk'

permit = Permit.new("<YOUR_API_KEY>")

server = WEBrick::HTTPServer.new(Port: 4000)

server.mount_proc '/' do |_, res|
  res['Content-Type'] = 'application/json'

  permitted = permit.check("user@mail.com", "read", "document")
  if permitted
    res.status = 200
    res.body = { result: "user@mail.com is PERMITTED to read document!" }.to_json
    next
  end
  res.status = 403
  res.body = { result: "user@mail.com is NOT PERMITTED to read document" }.to_json
end

trap 'INT' do server.shutdown end

server.start

Contents

Edit this page

Need help?