![\"FIWARE](\"https://nexus.lab.fiware.org/repository/raw/public/badges/chapters/security.svg\")
This tutorial introduces the administration of level 3 advanced authorization rules into Keyrock. The simple verb-resource based permissions are amended to use XACML and new XACML permissions added to the existing roles. The updated ruleset is automatically uploaded to Authzforce PDP, so that policy execution points such as the PEP proxy are able to apply the latest ruleset.
\nThe tutorial demonstrates examples of interactions using the Keyrock GUI, as\nwell cUrl commands used to access the REST\nAPIs of Keyrock and Authzforce
\nThe docker-compose files for this tutorial can be found on GitHub:
![\"GitHub\"](\"https://fiware.github.io/tutorials.Administrating-XACML/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 406: Administrating XACML
\n\n12.3 Central Terminal Area
\n\n
\n- Red or Yellow Zone
\n\n
\n- No private vehicle shall stop, wait, or park in the red or yellow zone.
\n- White Zone
\n\n
\n- No vehicle shall stop, wait, or park in the white zone unless actively\nengaged in the immediate loading or unloading of passengers\nand/or baggage.
\n— Los Angeles International Airport Rules and Regulations, Section 12 - Landside Motor Vehicle Operations
\n
Business rules change over time, and it is necessary to be able to amend access controls accordingly. The previous tutorial included a static XACML <PolicySet> loaded into Authzforce. This component offers advanced authorization (level 3) access control where every policy decision is calculated on the fly and new rules can be applied under new circumstances.\nThe details of the Authzforce Policy Decision Point (PDP) were discussed in the previous tutorial, suffice to say, the Authzforce PDP interprets rules according to the\nXACML standard and offers a means to adjudicate on any access request provided that sufficient information can be supplied.
For full flexibility, it must be possible to load, update and activate a new access control XACML <PolicySet> whenever necessary. In order to do, this Authzforce offers a simple REST Policy Adminstration Point (PAP), an alternative role-based PAP is available within Keyrock
eXtensible Access Control Markup Language (XACML) is a vendor neutral\ndeclarative access control policy language. It was created to promote common\naccess control terminology and interoperability. The architectural naming\nconventions for elements such as Policy Execution Point (PEP) and Policy\nDecision Point (PDP) come from the XACML specifications.
\nXACML policies are split into a hierarchy of three levels - <PolicySet>,\n<Policy> and <Rule>, the <PolicySet> is a collection of <Policy>\nelements each of which contain one or more <Rule> elements.
Each <Rule> within a <Policy> is evaluated as to whether it should grant\naccess to a resource - the overall <Policy> result is defined by the overall\nresult of all <Rule> elements processed in turn. Separate <Policy> results\nare then evaluated against each other using combining alogorthms define which\n<Policy> wins in case of conflict.
Further information can be found within the XACML standard
\nFor the first half of the tutorial, a simple two rule <PolicySet> will be administered using the Authzforce PAP. Thereafter the Keyrock GUI will be used to administer XACML rules within the existing tutorial application on an individual XACML <Rule> level. The policy decision request code within the PEP-Proxy may also need to be customized to enable the enforcement of complex XACML rules.
Within the Authzforce PAP all CRUD actions occur on the <PolicySet> level. It is therefore necessary to create a complete, valid XACML file before uploading it to the service. There is no GUI available to ensure the validity of the <PolicySet> prior to uploading the XACML.
Keyrock can create a valid XACML file based on available roles and permissions and pass this to Authzforce. Indeed Keyrock already does this whenever it combines with Authzforce as all its own basic authorization (level 2) permissions must be translated into advanced authorization (level 3) permissions before they can be adjudicated by Authzforce.
\nWithin Keyrock, each role corresponds to an XACML <Policy>, each permission within that role corresponds to an XACML <Rule>. There is a GUI available for uploading and amending the XACML for each <Rule> and all CRUD actions occur on the <Rule> level.
Provided care is taken when creating <Rule> you can use Keyrock to simplify the administration of XACML and create a valid <PolicySet> for Authzforce.
When using advanced authorization (level 3), a policy execution point sends the an authorization request to he relevant domain endpoint within Authzforce,\nproviding all of the information necessary for Authzforce to provide a\njudgement. Details of the interaction can be found in the previous tutorial.
\nThe full code to supply each request to Authzforce can be found within the\ntutorials'\nGit Repository
\nObviously the definition of \"all of the information necessary\" may change\nover time, applications must therefore be flexible enough to be able to modify the requests sent to ensure that sufficient information is passed.
\nTo keep things simple all components will be run using\nDocker. Docker is a container technology which\nallows to different components isolated into their respective environments.
\nDocker Compose is a tool for defining and running multi-container Docker\napplications. A\nYAML file\nis used configure the required services for the application. This means all\ncontainer services can be brought up in a single command. Docker Compose is\ninstalled by default as part of Docker for Windows and Docker for Mac, however\nLinux users will need to follow the instructions found\nhere
\nWe will start up our services using a simple bash script. Windows users should\ndownload cygwin to provide a command-line\nfunctionality similar to a Linux distribution on Windows.
\nThis application adds OAuth2-driven security into the existing Stock Management\nand Sensors-based application created in\nprevious tutorials by using\nthe data created in the first\nsecurity tutorial\nand reading it programmatically. It will make use of three FIWARE components -\nthe Orion Context Broker,the\nIoT Agent for UltraLight 2.0\nand integrates the use of the\nKeyrock Generic enabler. Usage\nof the Orion Context Broker is sufficient for an application to qualify as\n“Powered by FIWARE”.
\nBoth the Orion Context Broker and the IoT Agent rely on open source\nMongoDB technology to keep persistence of the\ninformation they hold. We will also be using the dummy IoT devices created in\nthe previous tutorial.\nKeyrock uses its own MySQL database.
\nTherefore the overall architecture will consist of the following elements:
\nThe FIWARE\nOrion Context Broker which\nwill receive requests using\nNGSI
\nThe FIWARE\nIoT Agent for UltraLight 2.0\nwhich will receive southbound requests using\nNGSI and convert\nthem to\nUltraLight 2.0\ncommands for the devices
\nFIWARE Keyrock offer a\ncomplement Identity Management System including:
\nFIWARE Authzforce is a XACML Server providing an interpretive Policy Decision Point (PDP)\naccess to the Orion and/or IoT Agent microservices
\nFIWARE Wilma is a PEP Proxy securing\naccess to the Orion microservices, it requests authorisation decisions from Authzforce
\nThe underlying MongoDB database :
\nA MySQL database :
\nThe Stock Management Frontend does the following:
\nA webserver acting as set of\ndummy IoT devices using\nthe\nUltraLight 2.0\nprotocol running over HTTP - access to certain resources is restricted.
\nSince all interactions between the elements are initiated by HTTP requests, the\nentities can be containerized and run from exposed ports.
\n![\"\"](\"https://fiware.github.io/tutorials.Administrating-XACML/img/architecture.png\")
The all container configuration values described in the YAML file\nhave been described in previous tutorials
\nTo start the installation, do the following:
\ngit clone git@github.com:Fiware/tutorials.Administrating-XACML.git\ncd tutorials.Administrating-XACML\n\n./services create\n\n\nNote The initial creation of Docker images can take up to three minutes
\n
Thereafter, all services can be initialized from the command-line by running the\nservices\nBash script provided within the repository:
\n./services start\n\n\nNote: If you want to clean up and start over again\nyou can do so with the following command:
\n./services stop\n
The following people at test.com legitimately have accounts within the\nApplication
The following people at example.com have signed up for accounts, but have no\nreason to be granted access
To apply an access control policy, it is necessary to be able to do the following:
\na) Create a consistent <PolicySet>\nb) Supply a Policy Execution Point (PEP) which provides necessary data
As will be seen, Keyrock is able help with the first point, and custom code within the PEP Proxy can help with the second. Authzforce itself does not offer a UI, and is not concerned with generation and management of XACML policies - it assumes that each <PolicySet> it receives has already been generated by another component.
Full-blown XACML editors are available, but the limited editor within Keyrock is usually sufficient for most access control scenarios.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Administrating XACML Rules","slug":"administrating-xacml-rules"},{"content":"Prerequisites","slug":"prerequisites"},{"content":"Architecture","slug":"architecture"},{"content":"Start Up","slug":"start-up"},{"content":"XACML Administration","slug":"xacml-administration"}],"owner":"513743","collectionId":"59ce8a5e-c01f-4d7b-964e-64dd67f2fce5","publishedId":"RznCrzo9","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF7059"},"publishDate":"2020-01-02T11:02:36.000Z"},"item":[{"name":"Authzforce PAP - Adminstrating XACML Policies","item":[{"name":"Creating a new Domain","id":"e8403c53-8bc0-4c10-83f1-e66b55aeabcf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/xml","type":"text"}],"body":{"mode":"raw","raw":"\nTo create a new domain in Authzforce, make a POST request to the\n/authzforce-ce/domains endpoint including a unique external-id within\nthe <domainProperties> element
The response includes a href in the <n2:link> element which holds the\ndomain-id used internally within Authzforce.
An empty PolicySet will be created for the new domain. By default all\naccess will be permitted.
To create a PolicySet for a given domain information in Authzforce, make a\nPOST request to the\n/authzforce-ce/domains/gQqnLOnIEeiBFQJCrBIBDA/pap/policies endpoint including the full set\nof XACML rules to upload.
For this initial Policy, the following rules will be enforced
\nThe response contains the internal id of the policy held within Authzforce and \nversion information about the PolicySet versions available.\nThe rules of the new PolicySet will not be applied until the PolicySet is activated.
To activate a PolicySet, make a PUT request to the\n/authzforce-ce/domains/{domain-id}/pap/pdp.properties endpoint including the policy-id\nto update within the <rootPolicyRefExpresion> attribute
The response returns information about the PolicySet applied.
To update a PolicySet for a given domain information in Authzforce, make a\nPOST request to the\n/authzforce-ce/domains/gQqnLOnIEeiBFQJCrBIBDA/pap/policies endpoint including the full set\nof XACML rules to upload. Note that the Version must be unique.
For the updated Policy, the previous rules will be reversed
\nThe response contains version information about the PolicySet versions available.\nThe rules of the new PolicySet will not be applied until the PolicySet is activated.
To update an active a PolicySet, make another PUT request to the\n/authzforce-ce/domains/{domain-id}/pap/pdp.properties endpoint including the policy-id\nto update within the <rootPolicyRefExpresion> attribute. The ruleset will be updated to\napply the latest uploaded version.
The response returns information about the PolicySet applied.
Authzforce can act as a Policy Administration Point (PAP), this means that PolicySets can be created and amended using API calls directly to Authzforce
\nHowever there is no GUI for creating or amending a <PolicySet>, and no generation tool. All CRUD actions occur on the <PolicySet> level.
To request a decision from Authzforce, make a POST request to the\ndomains/{domain-id}/pdp endpoint. In this case the user has the\nis requesting access to loading in the white zone.
The response for the request includes a <Decision> element to Permit or Deny access to the resource.
To request a decision from Authzforce, make a POST request to the\ndomains/{domain-id}/pdp endpoint. In this case the user has the\nis requesting access to loading in the red zone.
The response for the request includes a <Decision> element to Permit or Deny access to the resource.
At several points within this tutorial, a Policy Decision can be requested using Authzforce.
\nThe simple <PolicySet> used consists of two rules:
The updated policy switches the zones used.
\nTo request a decision from Authzforce, a structured request containing all\nrelevant information must be sent to the domains/{domain-id}/pdp endpoint. In\nthis case, the Body of the request must include sufficient information so that\nthe access request can be adjudicated.
Enter a username and password to enter the application. The default super-user has the values alice-the-admin@test.com and test.
The response header returns an X-Subject-token which identifies who has logged on the application.\nThis token is required in all subsequent requests to gain access
The /applications/tutorial-dckr-site-0000-xpresswebapp/permissions/{permission-id}} endpoint will return the permission\nlisted under that id. The X-Auth-token must be supplied in the headers.
The response returns the details of the requested permission, for a verb-resource permission, the xml element is null. This permission indicates that a user is permittted to make a POST request\nto the /door/unlock endpoint to unlock the main entrance.
The /applications/tutorial-dckr-site-0000-xpresswebapp/permissions/{permission-id}} endpoint will return the permission\nlisted under that id. The X-Auth-token must be supplied in the headers.
The response returns the details of the requested permission, for a XACML Rule permission, the xml element holds the details of the associated XACML <Rule>\nthe action and resource fields are null.
This is most easily be done in the GUI by pasting the rule into the appropriate\ntext box, however it can also be done programmatically.
\nTo log-in to the Keyrock GUI, enter the username and password on the log-in\npage http://localhost:3005/
![](\"https://fiware.github.io/tutorials.Administrating-XACML/img/login.png\")
Navigate to correct application, and click on the manage roles tab
\n![](\"https://fiware.github.io/tutorials.Administrating-XACML/img/manage-roles.png\")
Select a permission to edit
\n![](\"https://fiware.github.io/tutorials.Administrating-XACML/img/edit-permission.png\")
The HTTP Verb and Resource rule needs to be left blank, but the applicable XACML\n<Rule> elements need to be pasted within the Advanced XACML Rule textbox\nas shown:
![](\"https://fiware.github.io/tutorials.Administrating-XACML/img/permission.png\")
To amend the XACML rules governing a permission, make a PATCH request to the /applications/tutorial-dckr-site-0000-xpresswebapp/permissions/{permission-id}} endpoint. The body of the request must include three attributes - action and resource must both be set to \"\" and the xml attribute should hold the XACML text.
The response shows the details of the attributes which have been updated.
\n","urlObject":{"protocol":"http","path":["v1","applications","tutorial-dckr-site-0000-xpresswebapp","permissions","alrmbell-ring-24hr-xaml-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"fe09b929-10d0-48c9-b337-4b3b51aa6fd1"},{"name":"Delete Role-Permission Association","id":"80590be3-d424-42bf-9e2b-a005276889dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}],"body":{"mode":"raw","raw":""},"url":"http://localhost:3005/v1/applications/tutorial-dckr-site-0000-xpresswebapp/roles/security-role-0000-0000-000000000000/permissions/alrmbell-ring-24hr-xaml-000000000000","urlObject":{"protocol":"http","path":["v1","applications","tutorial-dckr-site-0000-xpresswebapp","roles","security-role-0000-0000-000000000000","permissions","alrmbell-ring-24hr-xaml-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"80590be3-d424-42bf-9e2b-a005276889dd"},{"name":"Create a Role-Permission Association","id":"ab410247-3e1e-4856-b6fb-5ad0eb6052ae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Auth-token","value":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}],"body":{"mode":"raw","raw":""},"url":"http://localhost:3005/v1/applications/tutorial-dckr-site-0000-xpresswebapp/roles/security-role-0000-0000-000000000000/permissions/alrmbell-ring-24hr-xaml-000000000000","urlObject":{"protocol":"http","path":["v1","applications","tutorial-dckr-site-0000-xpresswebapp","roles","security-role-0000-0000-000000000000","permissions","alrmbell-ring-24hr-xaml-000000000000"],"host":["localhost:3005"],"query":[],"variable":[]}},"response":[],"_postman_id":"ab410247-3e1e-4856-b6fb-5ad0eb6052ae"}],"id":"389c01fb-4d10-4ccd-8f42-601a1190cb2b","description":"Keyrock offers a role based access control identity management system. Typically every permission is only accessible to users within a given role. We have already seen how Verb-Resource rules can be set-up and enforced using the basic authorization (level 2) access control mechanism found within Keyrock, the data for defining an advanced permission can also be administed using the Keyrock GUI or via Keyrock REST API requests.
\nKeyrock permissions work on individual XACML <Rule> elements rather than a complete <PolicySet>. The <PolicySet> is generated by combining all the roles and permissions.
In a similar manner to the previous tutorial, two roles have been created, one\nfor store detectives and another for management users. A series of permissions have been set up for the supermarket application, the following XACML rules are applied:
\nAs you can see some of the new rules now have a time element to them and are no longer simple Verb-Resource rules.
\nFor most of the\nrules, the Policy Execution Point (i.e. the request to Authzforce and analysis of the result) is found within the tutorial code -
\nThe context broker data for the Store and IoT Devices is held in is secured behind the PEP Proxy. This means that only security staff are able to access the system outside of core hours.
\n\n\n","event":[{"listen":"prerequest","script":{"id":"7b40d496-0a0f-424d-a300-d7a4c7946cf7","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"121f1a38-45b2-4245-9fdc-97dfd34c1f5b","type":"text/javascript","exec":[""]}}],"_postman_id":"389c01fb-4d10-4ccd-8f42-601a1190cb2b"},{"name":"Authzforce PDP - Requesting Policy Decisions","item":[{"name":"Deny Access to a Resource","id":"b65eab2e-43b7-4a6c-b7a0-c4f154ef82d1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/xml","type":"text"}],"body":{"mode":"raw","raw":"\nNote within the Keyrock, only four resources have been secured using advanced authorization rules (level 3)
\n\n
\n- sending the ring bell command
\n- access to the price-change area
\n- access to the order-stock area
\n- PEP Proxy access to the context broker
\nFor contrast, one resource has been left as a simple VERB Resource permission (level 2)
\n\n
\n- sending the unlock door command
\n
To request a decision from Authzforce, make a POST request to the\ndomains/{domain-id}/pdp endpoint. In this case the user has the\nis requesting access to POST to the /ring/bell endpoint.
The response for the request includes a <Decision> element to Permit or Deny access to the resource.
If the time on the server is between 9 a.m. and 5 p.m. the access request will be denied.
\n","urlObject":{"protocol":"http","path":["authzforce-ce","domains","gQqnLOnIEeiBFQJCrBIBDA","pdp"],"host":["localhost:8080"],"query":[],"variable":[]}},"response":[],"_postman_id":"b65eab2e-43b7-4a6c-b7a0-c4f154ef82d1"},{"name":"Permit Access to a Resource","id":"41f54fda-41f9-43ea-93bd-308961465cea","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/xml","type":"text"}],"body":{"mode":"raw","raw":"\nAdditional Fields can be added to the policy decision request to improve the likelyhood of a Permit response.
In the example below, the emailaddress and subject:subject-id have been added to the body of the request\nwithin the subject-category:access-subject category.
With the new rule in place, the user charlie will be able to access the /bell/ring endpoint at all times of day.
To request a decision from Authzforce, a structured request containing all\nrelevant information must be sent to the domains/{domain-id}/pdp endpoint. In\nthis case, the Body of the request includes information such as the roles that\nthe User has, the application id that is being requested\n(tutorial-dckr-site-0000-xpresswebapp) and the HTTP verb and resource that are\nbeing requested ( a GET request on the /app/price-change URL). Obviously the\ninformation passed in the Body can be expanded as the rules become more complex.
The new policy for Charlie the security manager needs additional information to\nbe passed to Authzforce
\nProgrammatically, any Policy Execution Point consists of two parts, an OAuth\nrequest to Keyrock retrieves information about the user (such as the assigned\nroles) as well as the policy domain to be queried.
\nA second request is sent to the relevant domain endpoint within Authzforce,\nproviding all of the information necessary for Authzforce to provide a\njudgement. Authzforce responds with a permit or deny response, and the\ndecision whether to continue can be made thereafter.
\nThe user.username and user.email have been added to the list of fields\nto be sent to Authzforce
function authorizeAdvancedXACML(req, res, next, resource = req.url) {\n const keyrockUserUrl =\n \"http://keyrock/user?access_token=\" +\n req.session.access_token +\n \"&app_id=\" +\n clientId +\n \"&authzforce=true\";\n\n return oa\n .get(keyrockUserUrl)\n .then(response => {\n const user = JSON.parse(response);\n return azf.policyDomainRequest(\n user.app_azf_domain,\n user.roles,\n user.username,\n user.email,\n resource,\n req.method\n );\n })\n .then(authzforceResponse => {\n res.locals.authorized = authzforceResponse === \"Permit\";\n return next();\n })\n .catch(error => {\n debug(error);\n res.locals.authorized = false;\n return next();\n });\n}\nThe full code to supply each request to Authzforce can be found within the\ntutorials'\nGit Repository -\nthe supplied information has been expanded to include the username and email within the generated XACML request
const xml2js = require(\"xml2js\");\nconst request = require(\"request\");\n\nfunction policyDomainRequest(domain, roles, resource, action, username, email ) {\n let body =\n '<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n' +\n '<Request xmlns=\"urn:oasis:names:tc:xacml:3.0:core:schema:wd-17\" CombinedDecision=\"false\" ReturnPolicyIdList=\"false\">\\n';\n // Code to create the XML body for the request is omitted\n body = body + \"</Request>\";\n\n const options = {\n method: \"POST\",\n url: \"http://authzforceUrl/authzforce-ce/domains/\" + domain + \"/pdp\",\n headers: { \"Content-Type\": \"application/xml\" },\n body\n };\n\n return new Promise((resolve, reject) => {\n request(options, function(error, response, body) {\n let decision;\n xml2js.parseString(\n body,\n { tagNameProcessors: [xml2js.processors.stripPrefix] },\n function(err, jsonRes) {\n // The decision is found within the /Response/Result[0]/Decision[0] XPath\n decision = jsonRes.Response.Result[0].Decision[0];\n }\n );\n decision = String(decision);\n return error ? reject(error) : resolve(decision);\n });\n });\n}\nAfter successfully update the Authzforce <PolicySet> to include a special rule for Charlie, his rights will differ from other users in the security role
Detective1 works for Charlie and has the security role
\nhttp://localhost:3000, log in as detective1@test.com with the\npassword testhttp://localhost:3000 - access is\ndenied - This is a management only permissionhttp://localhost:3000/device/monitorCharlie has the security role
\nhttp://localhost:3000, log in as charlie-security@test.com with the\npassword testhttp://localhost:3000 - access is\ndenied - This is a management only permissionhttp://localhost:3000/device/monitorcharlie