diff options
| -rw-r--r-- | tutorials/tutorial-xacml-application/src/main/docker/README.md | 415 |
1 files changed, 36 insertions, 379 deletions
diff --git a/tutorials/tutorial-xacml-application/src/main/docker/README.md b/tutorials/tutorial-xacml-application/src/main/docker/README.md index b715412a..05a87462 100644 --- a/tutorials/tutorial-xacml-application/src/main/docker/README.md +++ b/tutorials/tutorial-xacml-application/src/main/docker/README.md @@ -1,395 +1,52 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. +# Running Docker XACML Tutorial -.. _xacmltutorial-label: +## Building XACML Tutorial Docker Image -Policy XACML - Custom Application Tutorial -########################################## + 1. ```cd /policy-xacml-pdp/tutorials/tutorial-xacml-application``` + 2. ```mvn clean install -Dmaven.test.skip=true -DskipTests -DskipIntegrationTests -DskipUnitTests -Dcheckstyle.skip -P docker``` -.. toctree:: - :maxdepth: 3 +## Running the Tutorial (Automatically) +```./run-tutorial.sh``` -This tutorial shows how to build a XACML application for a Policy Type. Please be sure to clone the -policy repositories before going through the tutorial. See :ref:`policy-development-tools-label` for details. +## Running the Tutorial (Manually) +### Setting Up and Starting from policy/docker components -Design a Policy Type -******************** -Follow :ref:`TOSCA Policy Primer <tosca-label>` for more information. For the tutorial, we will use -this example Policy Type in which an ONAP PEP client would like to enforce an action **authorize** -for a *user* to execute a *permission* on an *entity*. `See here for latest Tutorial Policy Type <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-xacml-application/src/test/resources/tutorial-policy-type.yaml>`_. + 1. Clone ```https://git.onap.org/policy/docker/``` + 2. ```cd /docker/csit``` + 3. Run the following to set the containers location, project, branch, and version: + - ```export CONTAINER_LOCATION=nexus3.onap.org:10001/``` + - ```export PROJECT=pap``` + - ```export GERRIT_BRANCH=master``` + - ```get-branch.sh``` + - ```get-versions.sh``` + 4. Run ```docker image ls``` + - Take note of the REPOSITORY ```onap/policy/xacml-tutorial``` and its ```TAG``` + - This refers to the image from our mvn clean install from above + 5. Edit ```docker-compose-all.sh``` + - Replace xacml-pdp image with the format "REPOSITORY:TAG" as noted in Step 4 + - ex. image: ```onap/policy-xacml-tutorial:2.7.1-SNAPSHOT``` -.. literalinclude:: tutorial/tutorial-policy-type.yaml - :language: yaml - :caption: Example Tutorial Policy Type - :linenos: +### Running the Containers and Testing -We would expect then to be able to create the following policies to allow the demo user to Read/Write -an entity called foo, while the audit user can only read the entity called foo. Neither user has Delete -permission. `See here for latest Tutorial Policies <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-xacml-application/src/test/resources/tutorial-policies.yaml>`_. +Run ```docker-compose -f docker-compose-all.yml up xacml-pdp``` -.. literalinclude:: tutorial/tutorial-policies.yaml - :language: yaml - :caption: Example Policies Derived From Tutorial Policy Type - :linenos: -Design Decision Request and expected Decision Response -****************************************************** -For the PEP (Policy Enforcement Point) client applications that call the Decision API, you need -to design how the Decision API Request resource fields will be sent via the PEP. +## Verification Example Calls -.. literalinclude:: tutorial/tutorial-decision-request.json - :language: JSON - :caption: Example Decision Request - :linenos: +Verify that the components are accessible: -For simplicity, this tutorial expects only a *Permit* or *Deny* in the Decision Response. However, one could -customize the Decision Response object and send back whatever information is desired. + 1. ```curl -X POST http://0.0.0.0:3904/events/POLICY-PDP-PAP``` + - Should return JSON similar to this: ```{"serverTimeMs":0,"count":0}``` -.. literalinclude:: tutorial/tutorial-decision-response.json - :language: JSON - :caption: Example Decision Response - :linenos: + 2. ```curl -k -u 'healthcheck:zb!XztG34' 'https://0.0.0.0:6969/policy/pdpx/v1/healthcheck'``` + - Should return JSON similar to this: ```{"name":"Policy Xacml PDP","url":"self","healthy":true,"code":200,"message":"alive"}``` -Create A Maven Project -********************** -Use whatever tool or environment to create your application project. This tutorial assumes you use Maven to build it. + 3. ```curl -k -u 'healthcheck:zb!XztG34' 'https://0.0.0.0:6767/policy/api/v1/healthcheck'``` + - Should return JSON similar to this: ```{"name": "Policy API","url": "policy-api","healthy": true,"code": 200,"message": "alive"}``` -Add Dependencies Into Application pom.xml -***************************************** + 4. ```curl -k -u 'healthcheck:zb!XztG34' 'https://0.0.0.0:6868/policy/pap/v1/healthcheck'``` + - Should return JSON similar to this: ```{"name": "Policy PAP","url": "policy-pap","healthy": true,"code": 200,"message": "alive"}``` -Here we import the XACML PDP Application common dependency which has the interfaces we need to implement. In addition, -we are importing a testing dependency that has common code for producing a JUnit test. +## POSTMAN Collection -.. code-block:: java - :caption: pom.xml dependencies - - <dependency> - <groupId>org.onap.policy.xacml-pdp.applications</groupId> - <artifactId>common</artifactId> - <version>2.3.3</version> - </dependency> - <dependency> - <groupId>org.onap.policy.xacml-pdp</groupId> - <artifactId>xacml-test</artifactId> - <version>2.3.3</version> - <scope>test</scope> - </dependency> - -Create META-INF to expose Java Service -************************************** -The ONAP XACML PDP Engine will not be able to find the tutorial application unless it has -a property file located in src/main/resources/META-INF/services that contains a property file -declaring the class that implements the service. - -The name of the file must match **org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider** -and the contents of the file is one line **org.onap.policy.tutorial.tutorial.TutorialApplication**. - -.. code-block:: java - :caption: META-INF/services/org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider - - org.onap.policy.tutorial.tutorial.TutorialApplication - - -Create A Java Class That Extends **StdXacmlApplicationServiceProvider** -*********************************************************************** -You could implement **XacmlApplicationServiceProvider** if you wish, but -for simplicity if you just extend **StdXacmlApplicationServiceProvider** you -will get a lot of implementation done for your application up front. All -that needs to be implemented is providing a custom translator. - -.. code-block:: java - :caption: Custom Tutorial Application Service Provider - :emphasize-lines: 6 - - package org.onap.policy.tutorial.tutorial; - - import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator; - import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider; - - public class TutorialApplication extends StdXacmlApplicationServiceProvider { - - @Override - protected ToscaPolicyTranslator getTranslator(String type) { - // TODO Auto-generated method stub - return null; - } - - } - -Override Methods for Tutorial -***************************** -Override these methods to differentiate Tutorial from other applications so that the XACML PDP -Engine can determine how to route policy types and policies to the application. - -.. code-block:: java - :caption: Custom Tutorial Application Service Provider - - package org.onap.policy.tutorial.tutorial; - - import java.util.Arrays; - import java.util.List; - - import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicyTypeIdentifier; - import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator; - import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider; - - public class TutorialApplication extends StdXacmlApplicationServiceProvider { - - private final ToscaPolicyTypeIdentifier supportedPolicyType = new ToscaPolicyTypeIdentifier(); - - @Override - public String applicationName() { - return "tutorial"; - } - - @Override - public List<String> actionDecisionsSupported() { - return Arrays.asList("authorize"); - } - - @Override - public synchronized List<ToscaPolicyTypeIdentifier> supportedPolicyTypes() { - return Arrays.asList(supportedPolicyType); - } - - @Override - public boolean canSupportPolicyType(ToscaPolicyTypeIdentifier policyTypeId) { - return supportedPolicyType.equals(policyTypeId); - } - - @Override - protected ToscaPolicyTranslator getTranslator(String type) { - // TODO Auto-generated method stub - return null; - } - - } - -Create A Translation Class that extends the ToscaPolicyTranslator Class -*********************************************************************** -Please be sure to review the existing translators in the policy/xacml-pdp repo to see if they could -be re-used for your policy type. For the tutorial, we will create our own translator. - -The custom translator is not only responsible for translating Policies derived from the Tutorial -Policy Type, but also for translating Decision API Requests/Responses to/from the appropriate XACML -requests/response objects the XACML engine understands. - -.. code-block:: java - :caption: Custom Tutorial Translator Class - - package org.onap.policy.tutorial.tutorial; - - import org.onap.policy.models.decisions.concepts.DecisionRequest; - import org.onap.policy.models.decisions.concepts.DecisionResponse; - import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicy; - import org.onap.policy.pdp.xacml.application.common.ToscaPolicyConversionException; - import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator; - - import com.att.research.xacml.api.Request; - import com.att.research.xacml.api.Response; - - import oasis.names.tc.xacml._3_0.core.schema.wd_17.PolicyType; - - public class TutorialTranslator implements ToscaPolicyTranslator { - - public PolicyType convertPolicy(ToscaPolicy toscaPolicy) throws ToscaPolicyConversionException { - // TODO Auto-generated method stub - return null; - } - - public Request convertRequest(DecisionRequest request) { - // TODO Auto-generated method stub - return null; - } - - public DecisionResponse convertResponse(Response xacmlResponse) { - // TODO Auto-generated method stub - return null; - } - - } - -Implement the TutorialTranslator Methods -**************************************** -This is the part where knowledge of the XACML OASIS 3.0 specification is required. Please refer to -that specification on the many ways to design a XACML Policy. - -For the tutorial, we will build code that translates the TOSCA Policy into one XACML Policy that matches -on the user and action. It will then have one or more rules for each entity and permission combination. The -default combining algorithm for the XACML Rules are to "Deny Unless Permit". - -`See the tutorial example for details on how the translator is implemented <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-xacml-application/src/main/java/org/onap/policy/tutorial/tutorial/TutorialTranslator.java>`_. Note that in the Tutorial Translator, it also shows how a developer could extend the translator to return or act upon obligations, advice and attributes. - -.. Note:: - There are many ways to build the policy based on the attributes. How to do so is a matter of experience and - fine tuning using the many options for combining algorithms, target and/or condition matching and the rich set of - functions available. - -Use the TutorialTranslator in the TutorialApplication -***************************************************** -Be sure to go back to the TutorialApplication and create an instance of the translator to return to the -StdXacmlApplicationServiceProvider. The StdXacmlApplicationServiceProvider uses the translator to convert -a policy when a new policy is deployed to the ONAP XACML PDP Engine. `See the Tutorial Application Example <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-xacml-application/src/main/java/org/onap/policy/tutorial/tutorial/TutorialApplication.java>`_. - -.. code-block:: java - :caption: Final TutorialApplication Class - :linenos: - :emphasize-lines: 38 - - package org.onap.policy.tutorial.tutorial; - - import java.util.Arrays; - import java.util.List; - import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicyTypeIdentifier; - import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator; - import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider; - - public class TutorialApplication extends StdXacmlApplicationServiceProvider { - - private final ToscaPolicyTypeIdentifier supportedPolicyType = - new ToscaPolicyTypeIdentifier("onap.policies.Authorization", "1.0.0"); - private final TutorialTranslator translator = new TutorialTranslator(); - - @Override - public String applicationName() { - return "tutorial"; - } - - @Override - public List<String> actionDecisionsSupported() { - return Arrays.asList("authorize"); - } - - @Override - public synchronized List<ToscaPolicyTypeIdentifier> supportedPolicyTypes() { - return Arrays.asList(supportedPolicyType); - } - - @Override - public boolean canSupportPolicyType(ToscaPolicyTypeIdentifier policyTypeId) { - return supportedPolicyType.equals(policyTypeId); - } - - @Override - protected ToscaPolicyTranslator getTranslator(String type) { - return translator; - } - - } - -Create a XACML Request from ONAP Decision Request -************************************************* -The easiest way to do this is to use the annotations feature from XACML PDP library to create an example XACML -request. Then create an instance and simply populate it from an incoming ONAP Decision Request. - -.. code-block:: java - :caption: Final TutorialApplication Class - - import com.att.research.xacml.std.annotations.XACMLAction; - import com.att.research.xacml.std.annotations.XACMLRequest; - import com.att.research.xacml.std.annotations.XACMLResource; - import com.att.research.xacml.std.annotations.XACMLSubject; - import java.util.Map; - import java.util.Map.Entry; - import lombok.Getter; - import lombok.Setter; - import lombok.ToString; - import org.onap.policy.models.decisions.concepts.DecisionRequest; - - @Getter - @Setter - @ToString - @XACMLRequest(ReturnPolicyIdList = true) - public class TutorialRequest { - @XACMLSubject(includeInResults = true) - private String onapName; - - @XACMLSubject(attributeId = "urn:org:onap:onap-component", includeInResults = true) - private String onapComponent; - - @XACMLSubject(attributeId = "urn:org:onap:onap-instance", includeInResults = true) - private String onapInstance; - - @XACMLAction() - private String action; - - @XACMLResource(attributeId = "urn:org:onap:tutorial-user", includeInResults = true) - private String user; - - @XACMLResource(attributeId = "urn:org:onap:tutorial-entity", includeInResults = true) - private String entity; - - @XACMLResource(attributeId = "urn:org:onap:tutorial-permission", includeInResults = true) - private String permission; - - /** - * createRequest. - * - * @param decisionRequest Incoming - * @return TutorialRequest object - */ - public static TutorialRequest createRequest(DecisionRequest decisionRequest) { - // - // Create our object - // - TutorialRequest request = new TutorialRequest(); - // - // Add the subject attributes - // - request.onapName = decisionRequest.getOnapName(); - request.onapComponent = decisionRequest.getOnapComponent(); - request.onapInstance = decisionRequest.getOnapInstance(); - // - // Add the action attribute - // - request.action = decisionRequest.getAction(); - // - // Add the resource attributes - // - Map<String, Object> resources = decisionRequest.getResource(); - for (Entry<String, Object> entrySet : resources.entrySet()) { - if ("user".equals(entrySet.getKey())) { - request.user = entrySet.getValue().toString(); - } - if ("entity".equals(entrySet.getKey())) { - request.entity = entrySet.getValue().toString(); - } - if ("permission".equals(entrySet.getKey())) { - request.permission = entrySet.getValue().toString(); - } - } - - return request; - } - } - -`See the Tutorial Request <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-xacml-application/src/main/java/org/onap/policy/tutorial/tutorial/TutorialRequest.java>`_ - -Create a JUnit and use the TestUtils.java class in xacml-test dependency -************************************************************************ -Be sure to create a JUnit that will test your translator and application code. You can utilize a TestUtils.java -class from the policy/xamcl-pdp repo's xacml-test submodule to use some utility methods for building the JUnit test. - -Build the code and run the JUnit test. Its easiest to run it via a terminal command line using maven commands. - -.. code-block:: bash - :caption: Running Maven Commands - :linenos: - - > mvn clean install - - -Download Tutorial Application Example -************************************* - -If you clone the XACML-PDP repo, the tutorial is included for local testing without building your own. - -`Tutorial code located in xacml-pdp repo <https://github.com/onap/policy-xacml-pdp/tree/master/tutorials/tutorial-xacml-application>`_ - -There are instructions on the repo to run the Policy Framework components locally and test the tutorial out using Docker. - -`Docker Instructions <https://github.com/onap/policy-xacml-pdp/tree/master/tutorials/tutorial-xacml-application/src/main/docker>`_ - -In addition, there is a POSTMAN collection available for setting up and running tests against a -running instance of ONAP Policy Components (api, pap, dmaap-simulator, tutorial-xacml-pdp). - -`POSTMAN collection for testing <https://github.com/onap/policy-xacml-pdp/blob/master/tutorials/tutorial-xacml-application/postman/PolicyApplicationTutorial.postman_collection.json>`_ +You can find the collection under ```/policy-xacml-pdp/tutorials-tutorial-xacml-application/postman/``` |