Skip to content

Latest commit

 

History

History
114 lines (91 loc) · 4.18 KB

README.md

File metadata and controls

114 lines (91 loc) · 4.18 KB
Raw

GateKeeper Roles-Based Access Control

NuGet Version NuGet

Roles-Based Access Control Library in C#

GateKeeper is a simple library for implementing roles-based access control to control access to resources by users given a specified operation type.

With GateKeeper, you can define users, roles, and permissions, then authorize access attempts to resources (by resource name and operation).

New in v2.0.0

  • Breaking changes and major refactor
  • Content sanitization on insert and authorization evaluation
  • Event handler for authorization decisions including evaluation metadata
  • Automatic cleanup of subordinate objects (for instance, deleting a user deletes any associated role maps)

Help, Feedback, and Disclaimer

First things first - do you need help or have feedback? File an issue or start a discussion! We would love to get your feedback to help make our software better. Also, there may be bugs or issues that we have yet to encounter!

Sample App

Refer to the GateKeeperConsole project for a working example. This project will initialize a database, and optionally, prepopulate it with a series of records allowing you to test functionality.

Sqlite and .NET Framework

You'll need to copy the runtimes directory into your application directory. Please refer to WatsonORM (see https://github.com/jchristn/watsonorm) Test.Sqlite project.

Enterprise Editions

If you wish to use GateKeeper in an enterprise application using your own database application, email me at joel dot christner at gmail dot com.

Getting Started

To get up and running with GateKeeper:

  1. Install the NuGet package
> Install-Package GateKeeper
  1. Add the appropriate using statements
using GateKeeper;
  1. Instantiate
RbacServer server = new RbacServer(); 
// or
RbacServer server = new RbacServer("MyDatabaseFilename.db");
  1. Create users
User user = new User("My first user");
server.Users.Add(user);
// users are entities that attempt to consume resources
  1. Create resources
Resource resource = new Resource("My first resource");
server.Resources.Add(resource);
// resources are entities that users attempt to consume
  1. Create roles
Role role = new Role("My first role");
server.Roles.Add(role);
// roles are entities to which permissions are mapped
  1. Create permissions
Permission perm = new Permission("My first permission", role, resource, "create", true);
// first parameter is the name of the permission
// second parameter is the role to which the permission should be assigned
// third parameter is the resource allowed or disallowed by the permission
// fourth parameter is the type of operation permitted or denied by this permission
// fifth parameter is whether or not the operation should be permitted
server.Permissions.Add(perm);
  1. Map users to roles
UserRole userRole = server.UserRoles.Add(user, role);
// this maps the user to the role defined in step 7
  1. Attempt an authorization!
bool authorized;

authorized = server.Authorize("My first user", "create", "My first resource");
// optionally, add metadata, which propagates to events
authorized = server.Authorize("My first user", "create", "My first resource", 42);
  1. Attach authorization event handler (optional)
server.AuthorizationEvent += MyEventHandler;

private static void MyEventHandler(object sender, AuthorizationEventArgs e)
{
  Console.WriteLine(e.Username + " attempted to " + e.Operation + " against " + e.Resource + ": " + e.Authorized);
}

Additional APIs

Each of the manager instances on RbacServer (Permissions, Resources, Roles, Users, UserRoles) have a series of APIs for managing the underlying data. These APIs include (not all are applicable to every manager):

  • Add
  • Remove
  • RemoveByName
  • All
  • GetFirstByName
  • ExistsByName