Project

auth_scope

0.0
No commit activity in last 3 years
No release in over 3 years
Authorization library using namespaced strings. Great for OAuth 2.0 APIs.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 1.6
>= 0
>= 0
 Project Readme

AuthScope

AuthScope is a simple library for describing authorization patterns through strings. It is intended to work in conjunction with (for example) an OAuth 2.0 API.

Installation

Add this line to your application's Gemfile:

gem 'auth_scope'

Scope Structure

Authorization scope strings look something like this:

user:email apps:one,another:read profile:*

Spaces delimit individual authorization grants and can be treated as completely independent of one another. When specified together they are considered to authorize additively, meaning that authorization is granted if any of the provided scopes are matched.

The : or namespace delimiter lets you create generic and specific permissions. user:email is more specific than user for instance.

The , or batch delimiter allows you to apply a scope to multiple resouces at the same namespace level. user:email,avatar is equivalent to asking for a scope of user:email user:avatar.

The * or wildcard is used to indicate permissiveness for a single namespace. For instance, user:* would grant access to user:email but not user:email:write.

The ** or global wildcard is used to indicate permissiveness for any number of namespaces. ** would grant access to everything, and user:**:write would grant access to any write permissions, even if deeply nested.

The more namespaces a scope has, the greater permission it authorizes. Each segment of a namespace is considered to be granted, so a scope of user:email grants both user and user:email scopes.

Usage

In simple terms, you will initialize an AuthScope with a string and query its authorization using the can? method:

require 'auth_scope'

scope = AuthScope.new("user:email apps:foo,bar:*")

scope.can? "user:email" # => true
scope.can? "user:write" # => false
scope.can? "apps:foo:write" # => true

You may also specify an array of authorization strings. This is treated no differently than space delimiting:

scope = AuthScope.new("user:email", "apps:foo,bar:*")

The any? method tests a set of potential authorizations to see if any match:

scope = AuthScope.new("admin")
scope.any? "user:email", "admin" # => true

The `all? method tests that each of a set of authorizations is a match:

scope = AuthScope.new("admin")
scope.all? "user:email", "admin" # => false

Object Scopes

It will often be useful for an object to be able to describe its own scope. AuthScope will call to_scope on passed-in arguments before checking them. For example:

class User
  def to_scope
    "user:#{id}"
  end
end

scope = AuthScope.new("user:123:write")
scope.can? user, "write" # => true
scope.can? another_user, "write" # => false

Contributing

  1. Fork it ( https://github.com/divshot/auth_scope/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request