Programming in Python using the py-fortress RBAC APIs

py-fortress implements standards-based RBAC in Python. There have been numerous postings lately here about it.

Prerequisites

Very soon we’ll have a release of py-fortress that works with just the file system. This is to lower complexity of testing and developing with this package. In the meantime, an LDAP server has to be running on the network, so follow the instructions in the quickstart below to use a Docker container, if you don’t already have one installed.

0. Prepare your python module for usage by importing:
from pyfortress import (
    # model
    User,
    Role,
    Perm,
    PermObj,
    # apis:
    review_mgr, 
    admin_mgr, 
    access_mgr,
    #exception handling:
    FortressError,
    global_ids
)

Access Mgr APIs – Create Session, Check Access, Session Perms

These are used to check the policies at runtime. For example, to authenticate is create_session and authorization is check_access here.

  1. Now test signing on the RBAC way:
    def test_create_session(self):
        """
        create session
        """
        print('test_create_session')
        
        try:
            session = access_mgr.create_session(User(uid='foo1', password='secret'), False)
            if not session:
                print('test_create_session fail')
                self.fail('test_create_session fail')
            else:
                print('test_create_session pass')
                pass                        
        except FortressError as e:
            self.fail('test_create_session failed, exception=' + e.msg)

    The session will then be held on to by the client for subsequent calls like check_access and session_perms

  2. Here’s how to check a single permission:
    def test_check_access(self):
        """
        create session and check perm
        """
        print('test_check_access')
        
        try:
            session = ... obtained earlier
            result = access_mgr.check_access(session, Perm(obj_name='ShoppingCart', op_name='add'))
            if not result:
                print('test_check_access fail')
                self.fail('test_check_access fail')
            else:
                print('test_check_access pass')
                pass                        
        except FortressError as e:
            self.fail('test_check_access failed, exception=' + e.msg)
  3. Retrieve all of the permissions as a list:
    def test_session_perms(self):
        """
        create session and get perms for user
        """
        print('test_check_access')
        
        try:
            session = ... obtained earlier
            perms = access_mgr.session_perms(session)
            if not perms:
                print('test_session_perms failed')
                self.fail('test_session_perms failed')
            
            for perm in perms:
                print_perm(perm, 'session_perms: ')
            pass                        
        except FortressError as e:
            self.fail('test_session_perms failed, exception=' + e.msg)

Admin and Review APIs – Create, Read, Update, Delete

These are for programs that manage and search the data. For example admin guis, conversion programs, reporting apps.

  1. Add a user:
    def test_add_user(self):
        """
        Add a basic user
        """
        print('test_add_user')
        
        try:
            admin_mgr.add_user(User(uid='foo1', password='secret'))
            print('test_add_user success')                        
        except FortressError as e:
            self.fail('test_add_user failed, exception=' + e.msg)
  2. Add a role:
    def test_add_role(self):
        """
        Add a basic role
        """
        print('test_add_role')        
        try:
            admin_mgr.add_role(Role(name='Customer'))
            print('test_add_role success')                        
        except FortressError as e:
            self.fail('test_add_role failed, exception=' + e.msg)
  3. Add an object:
    def test_add_obj(self):
        """
        Add a basic perm object
        """
        print('test_add_obj')
        
        try:
            admin_mgr.add_object(PermObj(obj_name='ShoppingCart'))
            print('test_add_obj success')                        
        except FortressError as e:
            self.fail('test_add_obj failed, exception=' + e.msg)
  4. Add a perm:
    def test_add_perm(self):
        """
        Add a basic perm
        """
        print('test_add_perm')
        
        try:
            admin_mgr.add_perm(Perm(obj_name='ShoppingCart', op_name='add'))
            print('test_add_perm success')                        
        except FortressError as e:
            self.fail('test_add_perm failed, exception=' + e.msg)
  5. Assign a user:
    def test_assign_user(self):
        """
        Assign a user to a role
        """
        print('test_assign_user')
        
        try:
            admin_mgr.assign(User(uid='foo1'), Role(name='Customer'))
            print('test_assign_user success')                        
        except FortressError as e:
            self.fail('test_assign_user failed, exception=' + e.msg)
  6. Grant a permission:
    def test_grant_perm(self):
        """
        Grant a permission to a role
        """
        print('test_grant_perm')
        
        try:
            admin_mgr.grant(Perm(obj_name='ShoppingCart', op_name='add'), Role(name="Customer"))
            print('test_grant_perm success')                        
        except FortressError as e:
            self.fail('test_grant_perm failed, exception=' + e.msg)

 

7. Read a user:

def test_read_user(self):
    """
    Read a user that was created earlier. Expects a unique uid that points to an existing user.
    """
    print_test_name()
    try:
        out_user = review_mgr.read_user(User(uid='foo1'))
        print_user(out_user)
    except FortressError as e:            
        print_exception(e)
        self.fail()

thows exception if user is not present

8. Search for users with a matching uid:

def test_search_users(self):
    """
    Search for users that match the characters passed into with wildcard appended.  Will return zero or more records, one for each user in result set.
    """
    print_test_name()
    try:
        users = review_mgr.find_users(User(uid='foo*'))
        for user in users:
            print_user(user)
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type user

9. Search for users assigned a role:

def test_assigned_users(self):
    """
    Search for users that are assigned a particular role.  Will return zero or more records, one for each user in result set.
    """
    print_test_name()
    try:
        uids = review_mgr.assigned_users(Role(name='Customer'))
        for uid in uids:
            print_test_msg('uid=' + uid)
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type string contain the user id

10. Search for users who have a permission:

def test_perm_users(self):
    """
    Search for users that have been authorized a particular permission.  Will return zero or more records, of type user, one for each user authorized that particular perm.
    """
    print_test_name()
    try:
        users = review_mgr.perm_users(Perm(obj_name='ShoppingCart', op_name='add'))
        for user in users:
            print_user(user)
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type user

11. Read a role:

def test_read_role(self):
    """
    The read role expects the role name to point to an existing entry and will throw an exception if not found or other error occurs.
    """
    print_test_name()        
    try:
        out_role = review_mgr.read_role(Role(name='Customer'))
        print_role(out_role)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a single entity of type role

12. Search for roles matching a particular name:

def test_search_roles(self):
    """
    Search for roles that match the characters passed into with wildcard appended.  Will return zero or more records, one for each user in result set.
    """
    print_test_name()        
    try:
        roles = review_mgr.find_roles(Role(name='Customer*'))
        for role in roles:
            print_role(role)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type role

13. Search for roles assigned to a user:

def test_assigned_roles(self):
    """
    Return the list of roles that have been assigned a particular user.  Will return zero or more records, of type constraint, one for each role assigned to user.
    """
    print_test_name()        
    try:
        constraints = review_mgr.assigned_roles(User(uid='foo1'))
        for constraint in constraints:
            print_test_msg('role name=' + constraint.name)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type role_constraint

14. Search for roles who have granted a particular permission:

def test_perm_roles(self):
    """
    Return the list of roles that have granted a particular perm.  Will return zero or more records, containing the role names, one for each role assigned to permission.
    """
    print_test_name()        
    try:
        names = review_mgr.perm_roles(Perm(obj_name='ShoppingCart', op_name='add'))
        for name in names:
            print_test_msg('role name=' + name)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of strings containing the role names

15. Read an object:

def test_read_obj(self):
    """
    The ob_name is the only required attribute on a fortress object. Will throw an exception if not found.
    """
    print_test_name()        
    try:
        out_obj = review_mgr.read_object(PermObj(obj_name='ShoppingCart'))
        print_obj(out_obj)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

return a single entity of type object

16. Search for objects matching obj_name field:

def test_search_objs(self):
    """
    Search for ojects that match the characters passed into with wildcard appended.  Will return zero or more records, one for each user in result set.
    """
    print_test_name()        
    try:
        objs = review_mgr.find_objects(PermObj(obj_name='ShoppingCart*'))
        for obj in objs:
            print_obj(obj)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type object

17. Read a permission entry:

def test_read_perm(self):
    """
    Permissions require obj_name and op_name, obj_id is optional.  This will throw an exception if not found.
    """
    print_test_name()        
    try:
        out_perm = review_mgr.read_perm(Perm(obj_name='ShoppingCart', op_name='add'))
        print_perm(out_perm)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a single entity of type permission

18, Search for perms:

def test_search_perms(self):
    """
    Search for perms that match the characters passed into with wildcard appended.  Will return zero or more records, one for each user in result set.
    """
    print_test_name()        
    try:
        perms = review_mgr.find_perms(Perm(obj_name='ShoppingCart*', op_name='*'))
        for perm in perms:
            print_perm(perm)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type perm

19. Search for perms by role:

def test_role_perms(self):
    """
    Search for perms that have been granted to a particular role.  Will return zero or more records, of type permission, one for each grant.
    """
    print_test_name()        
    try:
        perms = review_mgr.role_perms(Role(name='Customer'))
        for perm in perms:
            print_perm(perm)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type permission

20. Search for perms by user:

def test_user_perms(self):
    """
    Search for perms that have been authorized to a particular user based on their role assignments.  Will return zero or more records, of type permission, one for each perm authorized for user.
    """
    print_test_name()        
    try:
        perms = review_mgr.user_perms(User(uid='foo1'))
        for perm in perms:
            print_perm(perm)                        
    except FortressError as e:
        print_exception(e)
        self.fail()

returns a list of type permission

END

Testing the py-fortress RBAC0 System

The Command Line Interpreter (CLI) may be used to drive the RBAC System APIs,  to test, verify and understand a particular RBAC policy.

This document also resides here: README-CLI-AUTH

Prerequisites

Sample RBAC0 Policy

  • This tutorial covers the basics, RBAC Core: Many-to-many relationships between users, roles and perms and selective role activations.
  • py-fortress adds to the mix one non-standard feature: constraint validations on user and role entity activation.
  • The simple policy includes constraints being setup on user and role. Later we’ll demo a role timing out of the session.

Users

uid timeout begin_time end_time
chorowitz 30min

Roles

name timeout begin_time end_time
account-mgr 30min
auditor 5min

constraints are optional and include time, date, day and lock date validations

User-to-Role Assignments

user account-mgr auditor
chorowitz true true

Permissions

obj_name op_name
page456 edit
page456 remove
page456 read

Role-to-Permissions

role page456.edit page456.remove page456.read
account-mgr true true false
auditor false false true

 Getting Started

The syntax for testing py-fortress system commands:

clitest operation --arg1 --arg2 ... 

Where clitest executes a package script that maps to this module:

pyfortress.test.cli_test_auth

The operation is (pick one)

  •  auth => access_mgr.create_session
  • check => access_mgr.check_access
  • roles => access_mgr.session_roles
  • perms => access_mgr.session_perms
  • add => access_mgr.add_active_role
  • drop => access_mgr.drop_active_role
  • show => displays contents of session to stdout

Where operations => functions here: access_mgr.py

The args are ‘–‘ + attribute name + attribute value

  • –uid and –password from user.py
  • –obj_name, –op_name and –obj_id from perm.py
  • –role used for the role name

Command Usage Tips

  • The description of the commands, i.e. required and optional arguments, can be inferred via the api doc inline to the access_mgr module.
  • This program ‘pickles’ (serializes) the RBAC session to a file called sess.pickle, and places in the executable folder.  This simulates an RBAC runtime to test these commands.
  • Call the auth operation first, subsequent ops will use and refresh the session.
  • Constraints on user and roles are enforced. For example, if user has timeout constraint of 30 (minutes), and the delay between ops for existing session exceeds, it will be deactivated.

___________________________________________________________________________________

Setup an RBAC Policy Using admin_mgr CLI

To setup RBAC test data, we’ll be using another utility that was introduced here: README-CLI.md.

From the py-fortress/test folder, enter the following commands:

1. user add – chorowitz

$ cli user add --uid chorowitz --password 'secret' --timeout 30

user chorowitz has a 30 minute inactivity timeout

2. role add – account-mgr

$ cli role add --name 'account-mgr'

3. role add – auditor

$ cli role add --name 'auditor' --timeout 5

role auditor has a 5 minute inactivity timeout, more later about this…

4. user assign – chorowitz  to role account-mgr

$ cli user assign --uid 'chorowitz' --role 'account-mgr'

5. user assign – chorowitz to role auditor

$ cli user assign --uid 'chorowitz' --role 'auditor'

6. object add – page456

$ cli object add --obj_name page456

7. perm add – page456.read

$ cli perm add --obj_name page456 --op_name read

8. perm add – page456.edit

$ cli perm add --obj_name page456 --op_name edit

9. perm add – page456.remove

$ cli perm add --obj_name page456 --op_name remove

10. perm grant – page456.edit to role account-mgr

$ cli perm grant --obj_name page456 --op_name edit --role account-mgr

11. perm grant – page456.remove to role account-mgr

$ cli perm grant --obj_name page456 --op_name remove --role account-mgr

12. perm grant – page456.read  to role auditor

$ cli perm grant --obj_name page456 --op_name read --role auditor

________________________________________________________________________________

Perform cli_test_auth.py access_mgr Commands

From the py-fortress/test folder, enter the following commands:

1. auth – access_mgr.create_session – authenticate, activate roles:

 $ clitest auth --uid 'chorowitz' --password 'secret'
 uid=chorowitz
 auth
 success

Now the session has been pickled in on file system in current directory.

2. show – output user session contents to stdout:

$ clitest show
show
session
    is_authenticated: True
    user: 
    last_access: 
user
    cn: chorowitz
    constraint: 
    system: []
    roles: ['account-mgr', 'auditor']
    dn: uid=chorowitz,ou=People,dc=example,dc=com
    uid: chorowitz
    internal_id: 552c1a24-5087-4458-98f1-8c60167a8b7c
    reset: []
    sn: chorowitz

    User Constraint:
        name: chorowitz
        raw: chorowitz$30$$$$$$$
        timeout: 30
    User-Role Constraint[1]:
        name: account-mgr
        raw: account-mgr$0$$$$$$$
    User-Role Constraint[2]:
        name: auditor
        raw: auditor$5$$$$$$$
        timeout: 5
success

Displays the contents of session to stdout.

3. check – access_mgr.check_access – perm page456.read:

$ clitest check --obj_name page456 --op_name read
op_name=read
obj_name=page456
check
success

The user has auditor activated so unless timeout validation failed this will succeed.

4. check – access_mgr.check_access – perm page456.edit:

$ clitest check --obj_name page456 --op_name edit
op_name=edit
obj_name=page456
check
success

The user has account-mgr activated and this will succeed.

5. check – access_mgr.check_access – perm page456.remove:

$ clitest check --obj_name page456 --op_name remove
op_name=remove
obj_name=page456
check
success

The user has account-mgr activated and this will succeed.

6. get – access_mgr.session_perms:

$ clitest perms
perms
page456.read:0
  abstract_name: page456.read
  roles: ['auditor']
  internal_id: d6887434-050c-48d8-85b0-7c803c9fcf07
  obj_name: page456
  op_name: read
page456.edit:1
  abstract_name: page456.edit
  roles: ['account-mgr']
  internal_id: 02189535-4b39-4058-8daf-af0e09b0d235
  obj_name: page456
  op_name: edit
page456.remove:2
  abstract_name: page456.remove
  roles: ['account-mgr']
  internal_id: 10dea5d1-ff1d-4c3d-90c8-edeb4c7bb05b
  obj_name: page456
  op_name: remove
success

Display all perms allowed for activated roles to stdout confirms that user indeed can read, edit and remove from Page456.

7. drop – access_mgr.drop_active_role – auditor:

$ clitest drop --role auditor
drop
role=auditor
success

RBAC distinguishes between roles assigned or activated and privileges can be altered in the midst of a session.

8. roles – access_mgr.session_roles

$ clitest roles
roles
account-mgr:0
  raw: account-mgr$30$$$20180101$none$$$1234567
  end_date: none
  name: account-mgr
  timeout: 30
success

Notice the audit role is no longer active.

9. check – access_mgr.check_access – perm page456.read (again):

$ clitest check --obj_name page456 --op_name read
op_name=read
obj_name=page456
check
failed

The auditor role was deactivated so even though it’s assigned, user cannot perform as one.

10. add – access_mgr.add_active_role – auditor:

$ clitest add --role auditor
add
role=auditor
success

Now the user should be allowed to resume audit activities.

11. roles – access_mgr.session_roles:

$ clitest roles
roles
account-mgr:0
  raw: account-mgr$30$$$20180101$none$$$1234567
  end_date: none
  name: account-mgr
  timeout: 30
auditor:1
  raw: auditor$5$$$20180101$none$$$1234567
  timeout: 5
  name: auditor
  begin_lock_date: success
success

Notice the audit role has been activated once again.

12. check – access_mgr.check_access – perm page456.read (for the 3rd time):

$ clitest check --obj_name page456 --op_name read
op_name=read
obj_name=page456
check
success

The auditor role activated once again so user can do auditor things again.

13. Wait 5 minutes before performing the next step.

Allow enough time for auditor role timeout to occur before moving to the next step. Now, if you run the roles command, the auditor role will once again be missing.  This behavior is controlled by the ‘timeout’ attribute on either a user or role constraint.

14. check – access_mgr.check_access – perm page456.read:

$ clitest check --obj_name page456 --op_name read
op_name=read
obj_name=page456
check
failed

Because the auditor role has timeout constraint set to 5 (minutes), it was deactivated automatically from the session.

END

What Are Temporal Constraints?

Defined

Ability to control when an entity activation occurs based on time and date criteria.  Temporal constraints are typically applied during User and Role activation as part of an authentication or authorization check.

What Are They For?

Can be used to limit when a User may log onto or activate a particular Role within a security domain.  Follows the principle of least privilege as it ensures access rights are only granted when appropriate.

How Do They Work?

There may be policies to control what dates, times, and days of week a User may access a particular area of the system and in what Role.  Can also be used to enforce a lockout period when the User is inactive or otherwise away for an extended period of time.

Apache Fortress Temporal Constraints

Fortress allows constraints to be applied onto both User and Role entities.  There are rules that fire during an activation event (any policy enforcement API call):

  1. Can the entity be active on this Date?
  2. Is the entity within a lockout period?
  3. Has the entity exceeded a particular inactive period?
  4. Can the entity be used at this time?
  5. Can the entity be used on this day?
  6. Are there mutual exclusion constraints that prevent activating this entity?  (Roles Only)

These temporal constraint rules are pluggable and may be added, overridden or removed.

What are Password Policies?

Defined

A set of rules surrounding the content, quality and lifecycle of a password.

What Are They For?

Helps to safeguard the integrity of password values within a particular security domain.  With moves toward Multi-Factor Authentication (MFA) and other biometric authentication measures one can make the argument that the password’s days are numbered.  Nevertheless they remain in use widely today and will continue for the foreseeable future.

How Do They Work?

Define a set of rules to be enforced during a password lifecycle event.  An example of a lifecycle event is authentication, password change and password expiration.  There are a few standards that govern how systems should behave in this area.

IETF Password Policies

Apache Fortress adheres to IETF Password Policy Draft.  While this draft was never formally adopted it has traction within the various directory implementations and remains the de facto standard today.

Password Policy Enforcement

Password enforcement options include:

  1. A configurable limit on failed authentication attempts.
  2. A counter to track the number of failed authentication attempts.
  3. A time frame in which the limit of consecutive failed authentication attempts must happen before action is taken.
  4. The action to be taken when the limit is reached. The action will either be nothing, or the account will be locked.
  5. An amount of time the account is locked (if it is to be locked) This can be indefinite.
  6. Password expiration.
  7. Expiration warning
  8. Grace authentications
  9. Password history
  10. Password minimum age
  11. Password minimum length
  12. Password Change after Reset
  13. Safe Modification of Password
  14. Password Policy for LDAP Directories