Access Rules and Access Control
The Sentinet Access Control System helps developers of business services and Sentinet users to address one of the most challenging security tasks: effective management of authorization rules and the subsequent access to business resources. The Sentinet Access Control System consists of design- and runtime components. Below is a high-level description of these components:
Access Rules Graphical Designer - user interface of the Sentinet Administrative Console that allows the Sentinet user to graphically design and configure flexible and complex authorization rules.
Access Control Assignments -- user interface elements of the Sentinet Administrative Console that allow Sentinet users to assign Access Rules to specific services and service resources.
Authorization Engine -- part of the Sentinet Node runtime engine that executes one or more access rules for each message received by the Node.
Access Rule Graphical Designer
The Sentinet Access Rule is an entity that consists of Access Rule Expressions connected with each other through logical conditions "Any" (logical OR), "And All" (logical AND), or "Not" (logical NOT). A single Access Rule defines the logic used to evaluate messages against a set of validation criteria. For example, an Access Rule may define the validation of user identities attached to a request message against specific Username/Password combination or combinations, against a Windows group(s) membership or against some other criteria. Effectively, an Access Rule can be interpreted as a single IF statement with conditional statements that always returns either "true" or "false".
Example of logical conditions:
IF “User identity is the specific username/password”
AND “now is a weekday with the current time inside the interval 9am to 6pm”
AND “user has sent so far less than 100 transactions per minute”
OR “User identity is the specific X.509”
AND “now is a weekend any time during the day”
AND “user has sent so far less than 1000 transactions per minute”
In its simplest interpretation, an Access Rule defines the logic and validation criteria that will ultimately grant or deny access to a business resource.
Sentinet treats Access Rules as independent software assets (or entities) that must be registered in the Sentinet Repository folders just as any other entity, like services, service versions or policies.
To design and register a new Access Rule:
Select the Repository folder (root or any sub-folder) or the Access Rules group element in the Repository tree and right- click on it. (You can also click the Add toolbar button with the dropdown menu options).
Select the Add->Access Rule menu option.
Provide an Access Rule name and optional description.
Use the Access Rule Designer tools to graphically design an Access Rule.
Use drag-and-drop to place Access Rule Expressions on the Design surface. Conditional Access Rule Expressions (like "Any", "And All" and "Not") can be dropped on top of other conditional expressions.
Sentinet provides built-in Access Rule Expressions listed in the table below.
| Expression | Type | Description |
|---|---|---|
| Any | Conditional | Logical OR condition |
| And All | Conditional | Logical AND condition |
| Not | Conditional | Logical NOT condition |
| Windows User | Identity | Specific username and domain identity(Domain can be empty for local machine accounts) |
| Windows Group | Identity | Specific Windows group and domain identity(domain can be empty for local machine groups) |
| Username/Password | Identity | Specific Username/Password |
| X.509 Certificate | Identity | Specific X.509 certificate identity. Public part of X.509 certificate must be uploaded using "Browse…" button |
| Url Validation | RESTful | Url template validation |
| HTTP Header Validation | RESTful | HTTP Header value validation |
| HTTP Method Validation | RESTful | HTTP Method validation |
| IP Address | Generic | IP Address restrictions |
| Date/Time | Generic | Date and Time schedule expression |
| Transactions Count | Generic | Maximum throughput. This Access Rule Expression implements Rate Limiting using the default, in-memory caching of the Sentinet Node(s). For details on how to configure Sentinet Node(s) with distributed and/or persistent cache of a third-party product or a custom caching solution, see Appendix C of this User Guide. Optional Counter Name property identifies unique counter of a virtual service which may be stored in a third-party or a custom caching system. If Counter Name is not assigned, a globally unique name will be used behind the scenes by the Sentinet Node. Counter Name may include Context Property name, for example 123<{MyContextProperty}>567. Time Interval property may be entered in the format which includes days, for example: 30.00:00:00 |
| Regular Expression | Generic | Regular expression applied to the message content |
| XPath | Generic | XPath expression that returns true or false. XPath expression can be used to provide access to resource based on the message content. Note : for virtual SOAP services XPath is applied to the entire SOAP message content. This is unlike XPath that is used in the Sentinet Pipeline, where XPath is applied to SOAP Body XML element's content when used with Message Body source. |
| JSON Path | This expression is similar to XPath expression by its purpose, except that it is applied to JSON strings (rather than XML) and uses JSON Path syntax described by this specification https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html. | |
| JSON Pointer | This expression is similar to XPath expression by its purpose, except that it is applied to JSON strings (rather than XML) and uses JSON Pointer syntax described by this specification https://tools.ietf.org/html/rfc6901. | |
| Claim | Generic | Claim expression. Claim value can be processed using a variety of conditions, as well as by Regular Expression or by XPath expression. Claim Type, Claim Value and optional Claim Issuer fields can be identified using Recorded Identity Claims. |
| Operation Name | Generic | Operation Name selector |
| Context Property | Generic | This expression allows to check the values of the Built-in Context Properties. |
| Everyone | Generic | Special Access Rule Expression that grants or denies access for all messages. An Everyone Access Expression cannot be combined with other expressions |
Sentinet Access Rule Expressions can be extended with Custom Access Rule Expressions (see Sentinet Extensibility chapter for generic description of the Sentinet extensibility features).
Each Custom Access Rule expression is a regular .NET component that implements the Nevatech.Vsb.Repository.Security.IMessageEvaluator interface defined in the Nevatech.Vsb.Repository.dll assembly.
Sentinet users use the Administrative Console to register and graphically configure Custom Access Rule Expressions. At runtime, the Sentinet Node executes Custom Access Rule Expressions. Sentinet Access Control extensibility features allow developers and Sentinet users to design and develop their own authorization logic. Custom authorization components can be configured from the Administrative Console and then remotely executed on the Sentinet Nodes. Sentinet Access Control decouples authorization logic implementations from business services' coding and deployment processes.
To add a Custom Access Rule Expression, navigate to Repository root tree item, select CONFIGURATION tab, then EXTENSIBILITY tab and click the [+ Add] above the Custom Access Rule Expressions table.
In the Add Custom Access Rule Expression dialog box, specify:
A friendly name for custom Access Rule Expression.
Assembly that contains custom Access Rule Expression component.
.NET class (Type) that implements custom Access Rule Expression by implementing Nevatech.Vsb.Repository.Security.IMessageEvaluator interface.
Mark a component as reusable if its code is thread-safe. The Sentinet Authorization Engine will create and use a single instance of this component every time it is required by a specific Access Rule that this custom Access Rule Expression is part of.
Optional default configuration of the custom Access Rule Expression.
Once a Custom Access Rule Expression is added to the Sentinet Configuration, the Access Rules Expressions toolbar will show it and custom Access Rule Expression can be used by the Access Rule Designer through regular drag-and-drop. Existing Custom Access Rule Expressions can be modified or removed from the same screen on which they were added.
For the custom component to execute at run-time, it must be deployed on the machine, where Sentinet Node is running. Deploying assembly with custom .NET code must follow standard .NET rules:
Assembly can be dropped in the bin folder of Sentinet Node web application (create bin folder if it is not there yet).
Alternatively, deploy custom assembly in .NET 4.0 Global Assembly Cache (GAC).
Internally, Sentinet Access Rules are described by XML documents. The Access Rule Graphical Designer user interface provides two tabs---Design and Source.
By switching from Design view to Source view, Sentinet users can review and modify Access Rule XML documents. This feature is particularly useful when an existing Access Rule must be used as a template to create a new rule. In this case, a Sentinet user can switch to Source view of the existing Access Rule, copy its XML source in the clipboard, paste it into a Source view of the new Rule definition, and then modify the new rule as needed.
Every Access Rule Expression in the Sentinet Access Rule Designer is given a default title that depends on the nature of the Access Rule Expression and its content. For example, the figure below shows 2 Access Rule Expressions with their respective default titles.
To improve readability of the Access Rules and simplify their management, Sentinet allows the assignment of a custom title to every Access Rule Expression. Select Access Rule Expression and double click anywhere on its title or click a "pencil" icon.
Access Rules Attachments
Access Rules also allow attachments of additional metadata and searching Access Rules by Keyword Tags and Description Tags.
Access Rule Groups
An Access Rule Group represents an ordered (or chained) list of other Access Rules and/or other Access Rule Groups. Access Rule Groups simplify management of the complex access rule scenarios where common set of access rules must be repeatedly applied to multiple virtual services, or a common set of access rules must be applied along with some other specific Access Rules.
Just like individual Access Rules, Access Rule Groups can be applied to the virtual services’ Access Control, and they can be used as a filter in Service Agreement scopes.
To design and register a new Access Rule Group:
- Select the Repository folder (root or any sub-folder) or the Access Rules group element in the Repository tree and right-click on it. (You can also click the Add toolbar button with the dropdown menu options).
- Select the Add->Access Rule Group menu option.
- Provide an Access Rule Group name and optional description.
- Use drag-and-drop to add members to the Access Rule Group, or use +Add button to add them through the Add Access Rule Group Member dialog box.
Access Rules and Access Rule Groups are always created under the same Access Rules tree element, but they have different icons to indicate their different nature.
Access Control Assignment
Once an Access Rule is designed and registered in the Sentinet Repository, it can be applied to secure virtual services, interfaces, operations or endpoints. The same Access Rule can be used to secure access to many different virtual services.
To enable Access Control for a virtual service, select a virtual service version and click the ACCESS CONTROL tab.
Select an Access Rule in the Repository tree and drag-and-drop it on the virtual service tree.
When a Sentinet user drags an Access Rule over the service tree, service tree elements are highlighted in bold, indicating the drop location. The highlighted drop location will determine the scope of Access Rule coverage. For example, an Access Rule may cover the whole service, a specific interface, a specific operation or only a specific endpoint. Once an Access Rule is dropped, it shows its scope in APPLIES TO column in the Access Rule grid along with the ultimate result of the Access Rule evaluation, Permit or Deny. It is possible to drag-and-drop the same or different Access Rules multiple times onto the service tree to create chained Access Control. Move up and Move down buttons can be used to change the position of selected Access Rule.
Access Control must be explicitly assigned to a virtual service, otherwise Sentinet will always generate an Access Denied SOAP fault or REST error message as a response to the client applications. If access control is meant to allow unconditional access to all callers, Sentinet users must assign an Access Rule that includes a single Everyone Access Rule Expression. Sentinet by default includes an Everyone Access Rule pre-registered in the Sentinet Repository in its root. Administrators can delete this rule, move it to a different folder, or create it as a new rule using Access Rules Designer.
The list of Access Control Rules assigned to a virtual service can be exported in Excel XML spreadsheet. Downloaded ServiceAccessRules.xml report file will be populated using Reports template file located by default in C:\Program Files\Nevatech\Sentinet\Repository\Reports folder.
Selecting service tree element highlights in bold font those Access Rules that fall in the scope of the selected tree element. Show Applicable Only check-mark filters these Access Rules by hiding all others Access Rules that are not applicable to the scope of the selected tree element.
Authorization Engine
Access Rules and their assignments are delivered to the remote Sentinet Node(s) where they are executed at runtime by the Sentinet Node Authorization Engine. The Sentinet Node Authorization Engine executes and evaluates chained Access Rules one after another and from top to bottom of the Access Rules chain. Each Access Rule is evaluated against the resulting true or false value.
If an Access Rule evaluation returns true then the entire evaluation process stops and the ultimate result of authorization will be the one assigned to the evaluated Access Rule (either Permit or Deny).
If an Access Rule evaluation returns false then the evaluation process continues down the chain to the next Access Rule.
If no Access Rule in the chain returns true, then the Sentinet Node will generate an Access Denied runtime SOAP Fault or REST error message as a response to the service consumer.
In the example of the Figure Chained Access Control above, a message sent to the Search operation will be first evaluated against Customer A access rule. If evaluation returns false, the message will be then evaluated against Customer C access rule.
At the same time, a message sent to operation SendAlert will be first evaluated against Customer B access rule and if it returns false, it will be then evaluated against Customer C access rule that covers entire service including SendAlert operation.
Because the order of Access Rules in the chain matter, they can be re-ordered by selecting Access Rule in the grid and using the Move Up or Move Down status bar buttons.
Tracing
Sentinet Authorization Engine execution can be enabled with tracing logs for each message sent through the virtual service allowing monitoring and troubleshooting of the Access Rule execution. Tracing can be enabled for the whole Virtual Service on its TRACING tab (see Tracing chapter on how to enable Access Rules Tracing). Monitoring of the recorded Access Rules trace logs is covered in the Access Rules Tracing chapter.