Resource-Centric Authorization Service

Since V8.7, DirX Access incorporates a new authorization engine known as the Resource-Centric Authorization Service (RCAS). The need for this service has come naturally from the development of the environment in which the new versions of DirX Access could be deployed: namely, IoT. The computing systems are becoming more and more distributed and the ownership of the digital resources follows this trend. A good example of this is the emerging UMA 2.0 standard. Ownership was formerly centralized under the control of knowledgeable system administrators who set up the system-wide policies; now it is shifting to the domain of system users, who demand a fast and simple configuration mechanism to protect their respective digital resources (blog articles, pictures, data from a smart watch, and so on).

RCAS can fulfill the authorization decision-making for this new scenario. RCAS is suitable for systems with resource owners who are predominantly users, systems with a high number of protected resources (for example, the IoT environment), and systems where the policy rules for respective resources are often changed.

Here are the basic principles on which RCAS is built:

  • A resource is anything assigned with an identifier that the relevant resource server understands. The identifier used by RCAS must be unique within a scope of the resource server. The semantics of the resource are opaque to RCAS.

  • A single authorization policy is defined with respect to a single resource and a single action on this resource.

  • RCAS does not limit the originator of the policies. By default, this may be any system user, but the rules according to which the originator is determined may be much more complicated (leading to, for example, a group of users being the originator, or any user with given role).

  • The types of authorization policies (further discussed as evaluation models) are not limited and RCAS is easily extensible with a new type of evaluation model.

  • RCAS is self-applicable when dealing with resource and policy management, that is, the policies themselves and their management are, to some extent, perceived (hence, protected) as resources. For this, operational actions are predefined for each resource.

Resource Ownership and Registration

Before we proceed any further, we need to understand the concept of resource ownership which is tightly bound to the resource registration process. It is the configuration of the resource registration action that determines which entity is perceived as the resource owner of the newly registered resource.

A request for registering a new resource must naturally contain the resource identifier together with the requestor-defined initial authorization policies. It must also contain an identifier of a resource called a registration point. The registration point can be any resource that has the action with the identifier resource:management:action:execute defined. (The UMA 2.0 policy management API supplies the registration point internally. See the “Policy management API” section to for information about the parameters that must be supplied during the registration process.) During the resource registration, the authorization policies set for the resource:management:action:execute action at the registration point (called registration policies) are evaluated against the request context (which contains the requestor identity and other relevant context data) and the authorization policies requested for the new resource. The evaluation consists of two phases:

  • All of the alternative registration policies are evaluated against the request context until one is found that satisfies the context.

  • The found policy contains rules that specify the authorization policies that are allowed to be requested and the policies that are enforced to be present (if necessary, they are automatically generated and added to the original requested ones). For more information, see the “Update Evaluation Model” section.

As a result, the requested authorization policies are updated and this updated version is stored as the current authorization policies. The enforcement phase determines the initial resource ownership of the newly registered resource.

Let’s look at how the resource ownership is defined in RCAS. The resource owner of a resource is any requestor that can satisfy the authorization policies defined for action resource:management:action:update on the same resource. To ensure that the resource owner is always defined, the enforcement rules are defined in the registration policies. From this premise, we cant refine our previous statement about the resource ownership determination process during the resource registration as follows:

  • The initial resource owner is any requestor that can satisfy the authorization policies defined (and optionally automatically generated) by the enforcement rule contained in the registration policies (and possibly additional policies supplied during the registration request).

According to the definition, the resource owner may change (which is natural, as, for example, it can be bound to a single employee account and the employee may leave the company and his rights must be taken over). Or, there might be multiple resource owners. It is even possible to have resource owner defined as a member of a group, or use other types of evaluation models.

Example: The registration point has a single policy (registration policy) that enables any employee to register a resource. This policy contains an enforcement rule specifying that the OAuth “sub” claim of the current subject will be written into the resource:management:action:update policies. Alice wants to register a new resource with initial policies that allow Bob to perform the read action on it. Alice employs the registration point that, in addition to the requested policy, automatically generates the resource ownership policy. In the future, Alice will be recognized as a resource owner according to the value of her OAuth “sub” claim.

As mentioned previously, the UMA 2.0 policy management API does not contain the registration point parameter. The registration point itself is automatically generated on the creation of each new OAuth Server configuration object and can be subsequently regenerated in the default settings using the “Request OAuth registration point reset” field on the OAuth Server configuration page in DirX Access Manager. The default policies of the registration point enable anyone to register a new resource defining any actions except for resource:management:action:execute (which means that registration of a new registration point is not permitted). It sets up the resource ownership to be determined according to the OAuth “sub” claim of the registration requestor. In the next section, we discuss who can manage the registration point policies. The policies are managed in the same way as policies of any other resource (see the “Policy Management” section).

RCAS follows the original DirX Access administrator policies that are also used for XACML-based authorization service. The DirX Access properties file (dirxaccess.properties) contains the property administration.role.attribute.value which determines the user account role that is entitled with administrator rights. RCAS uses the same property in exactly the same way.

In the UMA 2.0 use of RCAS, when reading all resources managed by a single resource owner, an optimization algorithm is employed. If this algorithm were not used, the listing operation would require loading the policies of all registered resources and evaluating their rules. For deployments with a limited number of resources, this is achievable, however, taking into account a typical installation with truly distributed resource ownership, the performance would decrease rapidly. The algorithm, however, imposes certain limitations on the possible resource ownership determining policies. In particular, the resource ownership must be determined by an unchangeable attribute(s) comparable by a strict equality action. These attributes can be username, OAuth “sub” claim, e-mail, or other attributes. Any other resource ownership policies cause the resources not to be listed in the overall view of resource owner’s resources in UMA 2.0.

As the default resource ownership policy for OAuth Server supporting UMA 2.0, the OAuth “sub” claim is chosen. For more information, see the “OAuth 2.0 Token Introspection” section.

At this point, it is important to stress the true meaning of resource ownership. In the UMA 2.0 environment, the resource owners have truly exclusive rights to their resources. This model is sometimes unexpected by the authorization server administrators, who are used to being able to alter any configuration or policy. While this approach is not the pure one, it still can be demanded in some cases. Here are the reasons for introducing multiple resource owners of a single resource during the registration:

  • Resource ownership is only temporary

  • The resource owner’s account is removed and a new one is created

  • A break-glass situation occurs

Policy Management

As mentioned in previous sections, RCAS resources and policy management are self-applicable. By this, we mean that there are policies evaluated by RCAS to determine whether the policies themselves can be managed (updated, read, or deleted). In the previous section, we have shown that the registration policies (defined on resource:management:action:execute action of a registration point resource) are applied when a new resource is registered. After the registration, the new resource’s policies are self-contained: they also contain the operational policies necessary to define who can manage the resource’s policies. These polices include:

  • resource:management:action:update, which determines who can update the policies of this resource. It also determines who the resource owner is. When the resource owner updates the resource policies, it is a complete update of all policies bound to the resource - the state of policies after the update action corresponds to the policies provided during the update. The only exceptions are the filtering and enforcing.

  • resource:management:action:read, which determines who can read the policies of this resource. If a requester has no resource:management:action:read right, but has the resource:management:action:update right, the resource is not shown in her owned resources list because she cannot read it. However, due to the possibility to manage this resource, she can update the policies to be able to read it. From this reason, typically, the enforcement policy is set to the same value for both of these actions.

  • resource:management:action:delete, which determines who can unregister the given resource.

The operational policies are strictly internal, which means that they should be opaque to the resource server. For example, if the resource server provides a read operation on its resources, this action is represented by a different identifier than the operational one. The operational policies are managed in exactly the same way as any other policies bound to a resource.

The algorithm for filtering the allowed policies deserves a further description. To understand it, however, you must first read through the “Policies Configuration” section to become familiar with the concepts given here.

The policies that are requested for a resource during the registration or update are filtered in two ways: the rule templates are checked for the read rights, and the requested actions are filtered:

  • The rule template policy of each configured rule used in the requested policies is examined: the resource:management:action:read action is evaluated with respect to the requestor. If the right to this action is not granted, the whole conjunction of which the configured rule is a member is removed from the policy set.

  • The update evaluation model rule is examined to find the allowed actions. If any action is not allowed according to this rule present, it is removed. For more details, see the “Update Evaluation Model” section.

Action Specifics

The action identifiers in the RCAS (hence, the registered UMA scope identifiers) mustn’t start with “!” and end with “*”, as these characters have special meanings in the RCAS policies evaluation.

There is one more operational action in addition to the ones already listed: resource:action:empty. RCAS can assign the policies only to a tuple resource-action. However, UMA 2.0 also knows the use case when the policies are assigned to a resource only (empty scopes). RCAS translates such a request coming from UMA 2.0 into a request for the given resource and resource:action:empty action. This identifier also enables configuring policies for the “empty scopes” request.

Policies Configuration

The RCAS evaluation process is based on the request context that contains the information about the requestor and is evaluated against the relevant policies. These policies are identified by the tuple resource-action. There are independently-defined policies for each tuple. The assignment of these policies to the tuples is represented by the policy assignments configuration object. The configuration of the policies themselves consists of three configuration objects: rule configuration, rule template, and evaluation model.

Policies Configuration Elements
Figure 1. Policies Configuration Elements

The evaluation model represents a type of the policy being applied (access control list, XACML, RBA, …). It is the combination of the definition of the evaluation process and the definition of the policy language on which it operates. The policy language definition is further represented by rule templates and rule configurations. For example: The evaluation model to compare any attribute persisted for a user account to the attributes bound to an active user session of the requestor. The comparison method can be selected from the following operation set: equality, greater/less than, match to regular expression.

The rule template is a configuration that specifies the evaluation process of an evaluation model. The evaluation process is controlled by certain parameters. However, not all parameters should be set up by the resource owner during the registration or update. Some of them should be preset to reflect the actual deployment specifics. This might be achieved via the rule templates. Typically, the management of rule templates is restricted to the administrators only. The administrators create the rule templates and set up the rights of the requestors to use them (resource:management:action:read). There might be multiple rule templates for a single evaluation model. For example: A deployment stores e-mail and company branch identifier attributes for each user account. Rule templates for the evaluation model from the previous example can be used to make these attributes accessible. The parameters of the rule template are set to “attribute: e-mail” and “comparison operation: equality”, “attribute: company branch identifier” and “comparison operation: equality”. The rule templates can then be read as: “Is the requestor’s e-mail equal to e-mail configured via rule configuration?”, "`Is the requestor’s branch equal to the branch configured via rule configuration?`"

The rule configuration is an object that finalizes the configuration so that it can be directly used in the authorization evaluation process. Contrary to the previous policy configuration object types, rule configuration is defined by the resource owner directly when passing the resource policies during the registration/update process. The rule configuration is always relevant to a single rule template that determines its structure and semantics. For example: If a resource owner wants to grant a “download” right to her friend with the “__bob@acme.com” e-mail address, she includes the rule configuration with the identifier of the first rule template from the previous example and sets up the correct e-mail address. The rule configuration then reads: “Is the requestor’s e-mail equal to bob@acme.com?“

The policy assignments configuration represents the assignments of the rule configurations to respective actions for the given resource. For each defined action, there is a structure that defines the policies. The structure is formed as a set of sets and represents a disjunctive normal form (DNF); that is, it is a set of alternatively applicable policy sets. If any of the inner sets is true, the whole policy is true. The inner set is true if all its elements are true. The inner set elements are the rule configurations.

As typical for sets, no element is duplicated. For the sets in the policy assignments DNF, a stricter rule is applied: if there is a conjunction that gives permission to a set of requestors that is a subset of requestors that are given permission by another conjunction from the same DNF, the former conjunction is removed.

Rule Templates

Rule templates are specific compared to the other policy configuration objects. They are themselves resources recognized by the RCAS; that is, there are policy assignments for each rule template. There is a RESTful API for managing the rule templates that is described in the “Policy Management API” section. The rule template as a resource belongs to an internal server called the rule templates resource server. To manage this resource server through the policy management API for a given OAuth Server, the client metadata list contains client metadata with the identifier as_res_rt{oauth_server_id} representing the resource server. The oauth_server_id is the value of the OAuth Server identifier which reflects the fact the rule templates are managed for each OAuth Server individually. To enable to manage the rule templates of given OAuth Server, the administrator must configure the OAuth client metadata with the aforementioned identifier and assign them to the relevant OAuth Server.

Policies Import/Export

According to the UMA 2.0 specification, the resource owner gives a strict permission to protect given resources by a given authorization server. This permission is not transferable; as a result, another authorization server should never have any knowledge of the defined policies.

Currently, DirX Access provides no means for the import/export operations of the policy configuration objects.

Policy Management API

The policy management API consists of two RESTful API endpoints: policy management and rule template management. These endpoints comply with the OData specification. Their description can be found at {endpoint_address}/$metadata.

The respective endpoint addresses are:

  • {issuer}/rt/RuleTemplates – rule templates management

  • {issuer}/rt/RuleTemplateDescriptions – descriptions of rule templates

  • {issuer}/users/PolicyAssignments – policy assignments management

  • {issuer}/users/RuleDescriptions – rule configuration descriptions

Be aware that Policy and Rule template management URL syntax might be in collision with Resource exclusion on designated PEP protecting the OAuth endpoint.
E.g., we have {issuer}/rt/RuleTemplateDescriptions resource which requires authorized access, but to designated PEP we at some point configured Resource exclusion, specifically parameter Resource paths ending with and assigned it a value Descriptions. This way we coincidentally allowed unauthorized access through PEP.

More information about Resource exclusion can be found also here Plain Web PEP

The API enables the resource servers to include the policy management calls directly into their user interface. This design speeds up the interaction between the otherwise necessary interaction between the resource owner and the authorization server. For example, instead of clicking a “protect” button, which registers a new resource and subsequently redirects the resource owner to the policy management user interface provided by the authorization server where the resource owner sets up the policies, the resource server can directly provide the “publish” button, which registers the resource and subsequently sets up the policies to publish the resource (all with one click by the resource owner). This kind of management is enabled when the request is accompanied by the PAT token witnessing the presence of the resource server. Generally, requests accompanied by the PAT token enable management of the resources that belong to the respective resource server.

The resource owner can accompany the request with the PAT issued to the internal resource server as_res which enables management of all the resource owner’s resources. The deployment should provide a custom implementation of a user interface on top of the as_res resource server to which the resource owner is redirected after the new resource registration.

Both rule templates and rule configurations contain a string attribute that contains a JSON structure with parameters relevant to the corresponding evaluation model. This attribute is called “config” and is opaque from the API’s point of view. The rule configuration description endpoint provides the resource owner (or dedicated client application implementing the user interface on top of the API) with the description of the syntax of the “config” attribute. The provided information is requestor-dependent, as the presented descriptions represent the protected resources (rule templates). This means that two system users with different capabilities may see different descriptions when requesting the management of the same specific rule configuration. The endpoint of rule template descriptions prints the structure and possible content of the respective configuration attributes of all rule templates. The endpoint of rule configuration descriptions prints the structure and possible content of respective configuration attributes of all rule configurations (based on the existing rule templates).

We use the JavaScript Object Notation (JSON) schema (http://json-schema.org/ ) to represent the descriptions. This choice enables determining the configuration object structure as well as including possible predefined values or referencing an external resource for retrieving such values (which may again be subject to the authorization).

Using the JSON schema enables the authorization server clients to easily implement a user interface on top of the RESTful API. There are a vast number of open-source libraries providing conversion between a JSON schema and user interface; for example, an automatically generated HTML form.

Supported Evaluation Models

DirX Access currently supports the following evaluation models: update, attribute-based, and enforce.

Update Evaluation Model

The update evaluation model represents policies applied during processing of the resource:management:action:execute and resource:management:action:update. Each alternative conjunction in the policies set up for these actions must contain exactly one update rule configuration (if this is not requested by the resource owner, then it is automatically generated).

The purpose of the update evaluation model is to filter out the actions that are not allowed to be used by the registration/update requestor. The rule configuration of this evaluation model contains the attribute “allowed” that is of type set of strings. Each string represents a single rule applicable on the action identifier. The algorithm is as follows:

For each string out of the “allowed” set:

  • If it starts with “!”, disallow any action identifiers matched by the rest of the string,

  • Else allow any action identifiers matched by the rest of the string (with the exception of the explicitly disallowed),

  • If it ends with “*”, any action that starts with a prefix that is equal to the string (without the “!” and “*”) matches

Else the action matches if the string string comparison yields true.

To prevent the requestors that can manage the policies from rewriting the rights of other requestors, the update rule configuration contains the “conjEditor” and “conjEditorWt” attributes. The “conjEditor” attribute contains a whole disjunctive normal form of policies that determine who can manage the conjunction of which the update rule configuration is part. To understand the “conjEditorWt” attribute, we must describe the process of updating the policies. Any policy requested during update to be included in the policies currently stored must be approved by an existing update rule configuration (the “allowed” attribute). To pass the state of manageability from parent policy to its children registration/update actions, if the “conjEditorWt” is true, the value of “conjEditor” attribute of the original update rule configuration is added to the “conjEditor” of the new update rule configuration. This operation specifies that any requestor that is able to manage the original update rule configuration can also manage the new one.

The rule template of the update rule evaluation model must be configured with appropriate policies to be employable by the requestors. The rule template as such does not contain any structure in its “config” attribute.

Enforce Evaluation Model

The enforce evaluation model represents the establisher of the resource ownership. When contained in a conjunction that is applicable on a requested policies and a request context, the resulting policies are enriched with a newly generated policies according to the enforce rule configuration. There can be multiple enforce rule configurations in a single conjunction to enforce multiple initial policies (for example, multiple resource owners).

The rule configuration contains following attributes:

  • ruleTemplateId – the identifier of the rule template that determines which rule configuration will be generated. The rule template completely determines which part of the request context is transcribed into the rule configuration. For example, the rule template that determines the persisted mail attribute causes the request context to be introspected to find the corresponding persisted-mail attribute and use it for the generated rule configuration. If the attribute necessary to construct the new rule configuration is not found in the request context, the whole enforce rule is not applicable and yields FORBIDDEN state.

  • actions – the set of action identifiers to which the generated rule configuration will be written. Each rule configuration is added to the set of alternative conjunctions as a separate conjunction.

The rule template of the enforce rule evaluation model must be configured with appropriate policies to be employable by the requestors. The rule template as such does not contain any structure in its “config” attribute.

Attribute-based Evaluation Model

The attribute-based evaluation model represents an extended version of the access control list policy type. Using this model, the resource owner can set up a simple policies based, for example, on a list of allowed e-mails, an allowed organizational unit, or other items.

The rule template contains the following attributes:

  • evaluableClass – the class that determines the origin of the attributes. The current options include:

    • AccessTokenContext – the attributes bound to the OAuth access token (if present during the requesting) with identifiers as defined by the Token Introspection specification;

    • AttributeContext – the attributes persisted for the user account of the requesting entity;

    • KerberosClaimContext – the attributes bound to the Kerberos ticket (if used for authentication of the requesting entity): “realm”, “name”, “name_type”;

    • OAuthClaimContext – other OAuth parameters bound to the context: “access_token”, “refresh_token”, “scopes”, “valid_until”, “claims”, “client_id”;

    • SessionContext – the proprietary DirX Access session-relevant parameters: “ssid” - session identifier, “fqn” – a persisted fully qualified name of the requesting entity;

  • attributeId – one of the attribute identifiers listed in the previous point to a selected evaluableClass

  • evaluationMethodId – one of the following:

    • “o” - strict string comparison; at least one of the configured values must match (OR operation)

    • “a” - strict string comparison; all of the listed configured values must match (AND operation)

    • “ro” - regular expression matching; at least one of the configured values must match (OR operation)

    • “ra” - regular expression matching; all of the listed configured values must match (AND operation)

The rule configuration has a single attribute “values” which is a set of all possible values compared to the values from the request context.

Example: The administrator sets up the rule template as follows: evaluableClass=AttributeContext, attributeId=mail, evaluationMethodId=o This resource owner can subsequently employ this rule template to define a rule configuration that contains a set of all allowed e-mails whose owners will be granted a permission.

SSO Service Evaluation Model

The SSO service evaluation model is intended for delegation of the evaluation to SSO service where any access control system (RBAC or ABAC) can be applied based on Policy Decision Point (PDP) reference in Policy Enforcement Point (PEP).

The rule configuration contains following attributes:

  • pepId – the identifier of the PEP that will be used for the evaluation

  • resourceId - the resource container simplifying the resource matching during the evaluation

The rule template as such does not contain any structure in its “config” attribute.

Example 1: Resource owner can define the rule configuration based on SSO service rule template that delegates evaluation to RBAC. The resource owner registers their RCAS resource in the standard way, as described above, and creates a policy assignments (authorization policies) to the registered resource in form of DNF and a desired scope. The pepId=<any_PEP_with_empty_authority> SSO service evaluation rule configuration is part of the DNF. For successful evaluation of the rule, it is supposed to create RBAC resource with a path that corresponds with the registered RCAS resource (resource_server:resource_id) and assign the resource to respective RBAC authorization rule, policy and role. In the final XACML request, the desired scope is placed to the XACML Action element, but it is not needed to configure and assign a corresponding RBAC action also to authorization rule. The available scopes are filtered at the side of RCAS according the policy assignments of the evaluated resource.

Example 2: The resource owner can use the pepId=<any_PEP_with_empty_authority>, resourceId=<any_resource_container_name> SSO service evaluation rule to define a resource container. The resource container is pretty standard RBAC resource with a custom resource path string that is used to match several registered resources. It means that several registered RCAS resources can refer to the one resource container assigned within RBAC system. For successful evaluation, it is supposed to create RBAC resource with a path that corresponds with the resourceId and assign the RBAC resource to respective RBAC authorization rule, policy and role.

Performance

The RCAS implementation is currently designed to follow the scalability requirement that ensures that it can be used in an IoT environment. The only obstacle from the design point of view is the listing of owned resource operation. This obstacle is overcome by introducing the resource ownership limitations listed in the “Resource Ownership” section.

The implementation itself is currently built on an LDAP repository with the addition of configurable caching. The administrator needs to be aware of the limitations of the LDAP repository (for example, slow write operation). The implementation has been tested with the conclusion that it does not add any substantial limitations on top of the LDAP limitations, even for a growing number of resources and policy configuration objects.