In this document you can find the API used for ecommerce-RBAC project introduction. This is the recommended way to use this project for your applications. Within this document we use the following abbreviations:

1. {codeBase} - the url of the rest api endpoint (till context path).
   • Example: http://rbac.mydomain.com/rest/
2. {xxxxid} - where xxx is the component you want to address.
   • Example: userid, roleid, permissionid - Is the unique identifier of each addressed component.

In this REST api we map Create / Read / Update / Delete operations in the following way:

1. GET - retrieve information about entities
2. POST - create a new kind of entity
3. PUT - update an existing entity
4. DELETE - delete an existing entity.

There are some concerns like paging / sorting / filtering that are handled uniformly across multiple operations:

1. Paging: Solved by path parameters. Each resources set can be retrieved using a url like: {codeBase}/{resourceName}/{startRecord}/{pageSize}/
2. Sorting: Solved by sending two query params called sortCol and sortDir.
3. Filtering: This is done through query params which are mainly described by each operation that supports filtering.

Also we have a standard way of handling exceptions within this api:

1. 404 - When an entity does not exist this error code will be returned.
2. 401 - Whenever an unauthorized request is done this error code will be returned.
3. 403 - When a request is done to create an existing component this error code will be returned. Also whenever some integrity exception is raised this code will be returned.
4. 200 - Whenever a response is successful this status code is returned.
5. All other status codes should be considered unexpected exceptions by the client.

Each request must send the header "current-user" in the request. For some of the operations this will be simple ignore but most of the time is used for authorizing different operations.

This api accept only application/xml and application/json data representation. All other mime types specified for Content-Type and accept headers will be simply ignored.

1. GET - {codeBase}/users - Obtain a list of existing users currently defined.
2. GET - {codeBase}/users/[start_record]/[page_size]/
   • There is a hard limit for pageSize set to 100.
3. GET - {codeBase}/users/{userid} - Obtain information about a user.
4. GET - {codeBase}/users/{userid}/roles - Obtain all roles assigned to this user.
   • This function returns the set of roles assigned to a given user. The function is valid if and only if the user is a member of the USERS data set.
5. GET - {codeBase}/users/{userid}/permissions - Obtain all permissions assigned to this user.
   • This function returns the permissions a given user gets through his/her assigned roles. The function is valid if and only if the user is a member of the USERS data set.
6. GET - {codeBase}/users/{userid}/operations/{objectid} - Obtain all operations a specified user is allowed to execute on a specified object.
   • This function returns the set of operations a given user is permitted to perform on a given object, obtained either directly or through his/her assigned roles. The function is valid if and only if:
     • the user is a member of the USERS data set
     • the object is a member of the OBJS data set.
7. POST - {codeBase}/users/{userid} - Create a new user.
   • Request content: a json representation of user.
   • This command creates a new RBAC user. The command is valid only if the new user is not already a member of the USERS data set. The USER data set is updated. The new user does not own any session at the time of its creation.
   • A simple content request look like: {"user": {"id": 1}}
8. PUT - {codeBase}/users/{userid} - Update an existing user.
   • Request Content: a json representation of user.
9. DELETE - {codeBase}/users/{userid} - Delete an exiting user.
   • This command deletes an existing user from the RBAC database. The command is valid if and only if the user to be deleted is a member of the USERS data set. The USERS and UA data sets and the assigned_users function are updated. All sessions belonging to this user will be terminated immediately and deleted.
10. DELETE - {codeBase}/users/{userid}/roles - Remove the user from all roles he is currently assigned to.
    • This command does not actually exist in the official RBAC specification but it comes handy when we want to assign the user to a complete new set of roles.
11. DELETE - {codeBase}/users/{userId}/sessions - Stop all active sessions belonging to an user.

1. GET - {codeBase}/roles - Obtain a list of existing roles currently defined.
2. GET - {codeBase}/roles/byname/{roleName} - Obtain information about a specified role name.
3. GET - {codeBase}/roles/{roleid} - Obtain information about a role.
4. GET - {codeBase}/roles{roleid}/users - Obtain all users belonging to the specified role.
   • This function returns the set of users assigned to a given role. The function is valid if and only if the role is a member of the ROLES data set.
5. GET - {codeBase}/roles/{roleid}/permissions - Obtain all permissions belonging to the specified role.
   • This function returns the set of permissions (op, obj) granted to a given role. The function is valid if and only if the role is a member of the ROLES data set.
6. GET - {codeBase}/roles/{roleid}/operations/{objectid} - Obtain all operations that are allowed to be executed by the specified role on the specified object.
   • This function returns the set of operations a given role is permitted to perform on a given object. The function is valid only if:
     • the role is a member of the ROLES data set.
     • the object is a member of the OBJS data set.
7. POST - {codeBase}/roles - Create a new role.
   • Request content: a json representation of the role we want to create.
   • This command creates a new role. The command is valid if and only if the new role is not already a member of the ROLES data set. The ROLES data set and the functions assigned_users and assigned_permissions are updated. Initially, no user or permission is assigned to the new role.
8. PUT - {codeBase}/roles/{roleid} - Update an existing role.
   • Request content: a json representation of the role we want to update.
9. PUT - {codeBase}/roles/{roleId}/bulk/users - Assign a list of users to the specified role.
   • Content: json list of users we want to add to this role.
   • A content example can look like: {"identifiers-array": {"id": [1]}}
   • This command assigns a user to a role. The command is valid if and only if the user is a member of the USERS data dataset, the role is a member of the ROLES data set, and the user is not already assigned to the role. The data set UA and the function assigned_users are updated to reflect the assignment. Each user session will reflect the new roles immediately.
10. PUT - {codeBase}/roles/{roleId}/bulk/permissions - Assign a list of permissions to the specified role.
    • Content: json list of permissions we want to grant to this role.
    • This command grants a role the permission to perform an operation on an object to a role. The permission must be created before assigning it to the role (done by another operation of this API).
11. DELETE - {codeBase}/roles/{roleid} - Delete an exiting role.
    • This command deletes an existing role from the RBAC database. The command is valid if and only if the role to be deleted is a member of the ROLES data set. The role is immediately removed from any session in which it is present.
12. DELETE - {codeBase}/roles/{roleId}/bulk/users?userId=xxx&userId=.... - Removes a list of users from the specified role.
    • This command deletes the assignment of the user user to the role role. The command is valid if and only if the user is a member of the USERS data set, the role is a member of the ROLES data set, and the user is assigned to the role. The role will be inactivated immediately in all user sessions.
    • If no users are specified all users from this role are removed.
13. DELETE - {codeBase}/roles/{roleId}/bulk/permissions?permissionId=....&permissionId=.... - Removes a list of permissions from the specified role.
    • This command revokes the permission to perform an operation on an object from the set of permissions assigned to a role.
    • If no permissions are specified all permissions from this role are revoked.

1. GET - {codeBase}/objects/ - Obtain all security objects currently defined.
2. GET - {codeBase}/objects/[start_record]/[page_size]/?searchQuery=[string search] - Obtain a list of existing objects currently defined.
   • This operation support pagination of maximum 100 records.
   • In addition it allows developers to search by a given criteria (like comparison)
   • The objects are alphabetically ordered and retrieved.
3. GET - {codeBase}/objects/{objectid} - Obtain information about an object.
4. POST - {codeBase}/objects - Create a new object.
   • Request content: a json representation of the object we want to create.
   • It returns the newly created object identifier.
5. PUT - {codeBase}/objects/{objectid} - Update an existing object.
   • Request content: a json representation of the object we want to update.
6. DELETE - {codeBase}/objects/{objectid} - Delete an existing object.

1. GET - {codeBase}/operations - Obtain a list of existing operations currently defined.
2. GET - {codeBase}/operations/{operationid} - Obtain information about an operation.
3. POST - {codeBase}/operations - Create a new operation.
   • Request content: a json representation of the operation we want to create.
4. PUT - {codeBase}/operations/{operationid} - Update an existing operation.
   • Request content: a json representation of the operation we want to update.
5. DELETE - {codeBase}/objects/{operationid} - Delete an existing operation.

Only active flag applies to all GET request. If you set it to true only active sessions will be considered in each GET request. Sessions operations are 100% compliant with RBAC standard. This mean that DSD rules will be checked on all operations that involve session active roles change.

1. GET - {codeBase}/sessions/{userId}?onlyActive=[true|false] - Obtain a list of sessions for the specified user.
2. GET - {codeBase}/sessions/{sessionId}/roles?onlyActive=[true|false] - Retrieve a list of roles belonging to the current session.
   • This function returns the active roles associated with a session. The function is valid if and only if the session identifier is a member of the SESSIONS data set.
3. GET - {codeBase}/sessions/{sessionId}/permissions?onlyActive=[true|false] - Retrieve a list of permissions belonging to the current session.
   • This function returns the permissions of the session session, i.e., the permissions assigned to its active roles. The function is valid if and only if the session identifier is a member of the SESSIONS data set.
4. GET - {codeBase}/sessions/{sessionId}/permissions/{permissionId}?onlyActive=[true|false] - Check if a permission is enabled within the specified session.
   • This function returns a Boolean value meaning whether the subject of a given session is allowed or not to perform a given operation on a given object. The function is valid if and only if:
     • the session identifier is a member of the SESSIONS data set
     • the object is a member of the OBJS data set and the operation is a member of the OPS data set.
   • The permission must be assigned to at least one role that is currently activated within the specified session.
5. POST - {codeBase}/sessions/{userId}?activateRoles=[true | false]&remoteSession=[remoteSessionId] - Start a new session for the specified user. Keep in mind that remote session query param is not part of RBAC standard. We do this here because integration is one of the major goal of this project.
   • This function creates a new session with a given user as owner and an active role set. The function is valid if and only if:
   • the user is a member of the USERS data set
   • the active role set is a subset of the roles assigned to that user.
   • If activateRoles flag is set to true all non conflicted roles will be activated. By non conflicting roles we understand roles that don't have Static Separation of Duty violated or any matching Dynamic Separation of Duty. Also all inheritance roles will be activated as well with the same constraint: not to be in conflicting state. This feature is not specified by the RBAC standard but it is provided for performance.
6. PUT - {codeBase}/sessions/{sessionId}/roles/{roleId}?useInheritance=[true | false] - This method activates a role within the current session. Use inheritance is not part of the standard but gives a performance boost. Most of the time you will set this to true.
   • This function adds a role as an active role of a session whose owner is a given user. The function is valid if and only if:
     • the user is a member of the USERS data set
     • the role is a member of the ROLES data set
     • the session identifier is a member of the SESSIONS data set
     • the role is assigned to the user
     • the session is owned by that user.
7. DELETE - {codeBase}/sessions/{sessionId} - Stops a specified session.
   • This function deletes a given session. The function is valid if and only if the session identifier is a member of the SESSIONS data set. Here we are not 100% compliant with RBAC standard. RBAC standard defines this operation as requiring a sessionId and a session owner. Session owner is not explicitly specified in here because it will be determined from request headers.
8. DELETE - {codeBase}/sessions/{sessionId}/roles/{roleId} - This method removes the specified role from the current session.
   • This function deletes a role from the active role set of a session owned by a given user. The function is valid if and only if:
     • the user is a member of the USERS data set
     • session identifier is a member of the SESSIONS data set
     • the session is owned by the user
     • the role is an active role of that session.

1. GET - {codeBase}/permissions - Retrieve all permissions defined.
2. GET - {codeBase}/permissions/{permissionId} - Retrieve the specified permission.
3. GET - {codeBase}/permissions/{permissionId}/roles - Retrieve all roles that are granted to the specified permission identifier.
   • This is not a standard operation specified in RBAC documentation but it is extremely useful for security administration modules.
4. GET - {codeBase}/permissions/{permissionId}/operation - Retrieve the operation assigned to the specified permission.
5. GET - {codeBase}/permissions/{permissionId}/object - Retrieve the object assigned to the specified permission.
6. POST - {codeBase}/permissions/{operationId}/{objectId} - Creates a new permission that links operation to object.
   • Request content: json representation of a permission without operationId and objectId.
7. PUT - {codeBase}/permissions/{permissionId} - Update an existing permission. You can also change the referenced operation and object if you want.
8. DELETE {codeBase}/permissions/{permissionId} - Remove the specified permission from the system.
9. DELETE {codeBase}/permissions/{permissionId}/roles - Remove the specified permission from all roles who are currently granted to use it.

1. POST - {codeBase}/roles/inheritance/{roleid}/{childid} - Operation used to establish an inheritance relations between roleid and childid roles.
   • Roleid must not already inherits childid in order to avoid cycles.
2. DELETE - {codeBase}/roles/inheritance/{roleid}/{childid} - Operation used to delete the inheritance of childid from roleid. The inheritance hierarchy must be computed for all other nodes involved in the hierarchy graph.
3. POST - {codeBase}/roles/inheritance/{roleid}/ascendant/{ascendatid} - Operations used to add ascendantid role as a first level ascendant of roleid. In comparison to the RBAC standard, each role must be previously created.
4. POST - {codeBase}/roles/inheritance/{roleid}/descendant/{descendantid} - Operation used to add descendantid role as a first level descendant of roleid. In comparison to the RBAC standard, each role must be previously created.

1. GET - {codeBase}/dsd - Operation used to obtain all currently defined dynamic separation of duty rules.
2. GET - {codeBase}/dsd/{dsdId} - Operation used to obtain the specified dynamic separation of duty rule.
3. GET - {codeBase}/dsd/{dsdId}/roles - Operation used to obtain all roles for a specified dsd.
4. POST - {codeBase}/dsd/{dsdName}/{cardinality} - Operation used to create a new Dynamic Separatio n of Duty rule.
   • Content: json list representation of roles we want to include in this dsd.
   • This command creates a named DSD set of roles and sets an associated cardinality n. The DSD constraint stipulates that the DSD role set cannot contain n or more roles simultaneously active in the same session. The command is valid if and only if:
     • the name of the DSD set is not already in use
     • all the roles in the DSD set are members of the ROLES data set
     • n is a natural number greater than or equal to 2 and less than or equal to the cardinality of the DSD role set.
     • the DSD constraint for the new role set is satisfied.
5. POST - {codeBase}/dsd/{dsdId}/roles/ - Operation used to assign new roles to the current specified dsd.
   • Content: json list representation of roles we want to include within this dsd.
   • This command adds roles to a named DSD set of roles. The cardinality associated with the role set remains unchanged. The command is valid if and only if:
     • the DSD role set exist
     • the roles to be added are member of the ROLES data set but not of members of the DSD role set
     • the DSD constraint is satisfied after the addition of the roles to the DSD role set.
   • This operation is not part of the standard. Standard allows user to add one role member at a tim into a DSD.
6. PUT - {codeBase}/dsd/{dsdId} - Operation used to update a DSD attributes (name and cardinality).
   • Content: contains a json representation of DSD attributes.
   • This operation provided here is not part of the standard. In standard only the operation for changing cardinality is defined.
7. DELETE - {codeBase}/dsd/{dsdId}/roles?roleId=xxxx&roleId=... - Operation used to remove a role set from the specified dsd.
   • This command removes a role from a named DSD set of roles. The cardinality associated with the role set remains unchanged. The command is valid if and only if:
     • the DSD role set exists
     • the role to be removed is a member of the DSD role set, and
     • the cardinality associated with the DSD role set is less than the number of elements of the DSD role set.
     • Note that the DSD constraint should be satisfied after the removal of the role from the
   • This operation is not part of the standard. Only single role removal from a DSD is part of the standard. We provided it for performance.
8. DELETE - {codeBase}/dsd/{dsdId} - Operation used to remove a DSD.
   • This command deletes a DSD role set completely. The command is valid if and only if the DSD role set exists.

1. Do not expose this API publicly. It should always be hidden within your intranet.