1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
3 .. _xacmltutorial-label:
5 Policy XACML - Custom Application Tutorial
6 ##########################################
11 This tutorial shows how to build a XACML application for a Policy Type. Please be sure to clone the
12 policy repositories before going through the tutorial. See :ref:`policy-development-tools-label` for details.
17 Follow :ref:`TOSCA Policy Primer <tosca-label>` for more information. For the tutorial, we will use
18 this example Policy Type in which an ONAP PEP client would like to enforce an action **authorize**
19 for a *user* to execute a *permission* on an *entity*.
21 .. literalinclude:: tutorial/app/src/test/resources/tutorial-policy-type.yaml
23 :caption: Example Tutorial Policy Type
26 We would expect then to be able to create the following policies to allow the demo user to Read/Write
27 an entity called foo, while the audit user can only read the entity called foo. Neither user has Delete
30 .. literalinclude:: tutorial/app/src/test/resources/tutorial-policies.yaml
32 :caption: Example Policies Derived From Tutorial Policy Type
35 Design Decision Request and expected Decision Response
36 ******************************************************
37 For the PEP (Policy Enforcement Point) client applications that call the Decision API, you need
38 to design how the Decision API Request resource fields will be sent via the PEP.
40 .. literalinclude:: tutorial/app/src/test/resources/tutorial-decision-request.json
42 :caption: Example Decision Request
45 For simplicity, this tutorial expects only a *Permit* or *Deny* in the Decision Response. However, one could
46 customize the Decision Response object and send back whatever information is desired.
48 .. literalinclude:: tutorial/tutorial-decision-response.json
50 :caption: Example Decision Response
53 Create A Maven Project
54 **********************
55 This part of the tutorial assumes you understand how to use Eclipse to create a Maven
56 project. Please follow any examples for the Eclipse installation you have to create
57 an empty application. For the tutorial, use groupId *org.onap.policy.tutorial* and artifactId
58 *tutorial*. If you wish to go directly to the source code, please see the
59 :ref:`Download Tutorial Application Example` below to download it.
61 .. image:: tutorial/images/eclipse-create-maven.png
63 .. image:: tutorial/images/eclipse-maven-project.png
65 Be sure to import the policy/xacml-pdp project into Eclipse.
67 .. image:: tutorial/images/eclipse-import.png
69 Add Dependencies Into Application pom.xml
70 *****************************************
72 Here we import the XACML PDP Application common dependency which has the interfaces we need to implement. In addition,
73 we are importing a testing dependency that has common code for producing a JUnit test.
76 :caption: pom.xml dependencies
79 <groupId>org.onap.policy.xacml-pdp.applications</groupId>
80 <artifactId>common</artifactId>
81 <version>2.2.2</version>
84 <groupId>org.onap.policy.xacml-pdp</groupId>
85 <artifactId>xacml-test</artifactId>
86 <version>2.2.2</version>
90 Create META-INF to expose Java Service
91 **************************************
92 The ONAP XACML PDP Engine will not be able to find the tutorial application unless it has
93 a property file located in src/main/resources/META-INF/services that contains a property file
94 declaring the class that implements the service.
96 The name of the file must match **org.onap.policy.pdp.xacml.application.common.XacmlApplicationServiceProvider**
97 and the contents of the file is one line **org.onap.policy.tutorial.tutorial.TutorialApplication**.
99 .. image:: tutorial/images/eclipse-meta-inf.png
101 Create A Java Class That Extends **StdXacmlApplicationServiceProvider**
102 ***********************************************************************
103 You could implement **XacmlApplicationServiceProvider** if you wish, but
104 for simplicity if you just extend **StdXacmlApplicationServiceProvider** you
105 will get a lot of implementation done for your application up front. All
106 that needs to be implemented is providing a custom translator.
108 .. image:: tutorial/images/eclipse-inherit-app.png
111 :caption: Custom Tutorial Application Service Provider
114 package org.onap.policy.tutorial.tutorial;
116 import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator;
117 import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider;
119 public class TutorialApplication extends StdXacmlApplicationServiceProvider {
122 protected ToscaPolicyTranslator getTranslator(String type) {
123 // TODO Auto-generated method stub
129 Override Methods for Tutorial
130 *****************************
131 Override these methods to differentiate Tutorial from other applications so that the XACML PDP
132 Engine can determine how to route policy types and policies to the application.
135 :caption: Custom Tutorial Application Service Provider
137 package org.onap.policy.tutorial.tutorial;
139 import java.util.Arrays;
140 import java.util.List;
142 import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicyTypeIdentifier;
143 import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator;
144 import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider;
146 public class TutorialApplication extends StdXacmlApplicationServiceProvider {
148 private final ToscaPolicyTypeIdentifier supportedPolicyType = new ToscaPolicyTypeIdentifier();
151 public String applicationName() {
156 public List<String> actionDecisionsSupported() {
157 return Arrays.asList("authorize");
161 public synchronized List<ToscaPolicyTypeIdentifier> supportedPolicyTypes() {
162 return Arrays.asList(supportedPolicyType);
166 public boolean canSupportPolicyType(ToscaPolicyTypeIdentifier policyTypeId) {
167 return supportedPolicyType.equals(policyTypeId);
171 protected ToscaPolicyTranslator getTranslator(String type) {
172 // TODO Auto-generated method stub
178 Create A Translation Class that extends the ToscaPolicyTranslator Class
179 ***********************************************************************
180 Please be sure to review the existing translators in the policy/xacml-pdp repo to see if they could
181 be re-used for your policy type. For the tutorial, we will create our own translator.
183 The custom translator is not only responsible for translating Policies derived from the Tutorial
184 Policy Type, but also for translating Decision API Requests/Responses to/from the appropriate XACML
185 requests/response objects the XACML engine understands.
188 :caption: Custom Tutorial Translator Class
190 package org.onap.policy.tutorial.tutorial;
192 import org.onap.policy.models.decisions.concepts.DecisionRequest;
193 import org.onap.policy.models.decisions.concepts.DecisionResponse;
194 import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicy;
195 import org.onap.policy.pdp.xacml.application.common.ToscaPolicyConversionException;
196 import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator;
198 import com.att.research.xacml.api.Request;
199 import com.att.research.xacml.api.Response;
201 import oasis.names.tc.xacml._3_0.core.schema.wd_17.PolicyType;
203 public class TutorialTranslator implements ToscaPolicyTranslator {
205 public PolicyType convertPolicy(ToscaPolicy toscaPolicy) throws ToscaPolicyConversionException {
206 // TODO Auto-generated method stub
210 public Request convertRequest(DecisionRequest request) {
211 // TODO Auto-generated method stub
215 public DecisionResponse convertResponse(Response xacmlResponse) {
216 // TODO Auto-generated method stub
222 Implement the TutorialTranslator Methods
223 ****************************************
224 This is the part where knowledge of the XACML OASIS 3.0 specification is required. Please refer to
225 that specification on the many ways to design a XACML Policy.
227 For the tutorial, we will build code that translates the TOSCA Policy into one XACML Policy that matches
228 on the user and action. It will then have one or more rules for each entity and permission combination. The
229 default combining algorithm for the XACML Rules are to "Deny Unless Permit".
232 There are many ways to build the policy based on the attributes. How to do so is a matter of experience and
233 fine tuning using the many options for combining algorithms, target and/or condition matching and the rich set of
236 Here is one implementation example:
238 .. literalinclude:: tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialTranslator.java
239 :caption: Example Translator Implementation
242 Use the TutorialTranslator in the TutorialApplication
243 *****************************************************
244 Be sure to go back to the TutorialApplication and create an instance of the translator to return to the
245 StdXacmlApplicationServiceProvider. The StdXacmlApplicationServiceProvider uses the translator to convert
246 a policy when a new policy is deployed to the ONAP XACML PDP Engine.
249 :caption: Final TutorialApplication Class
253 package org.onap.policy.tutorial.tutorial;
255 import java.util.Arrays;
256 import java.util.List;
258 import org.onap.policy.models.tosca.authorative.concepts.ToscaPolicyTypeIdentifier;
259 import org.onap.policy.pdp.xacml.application.common.ToscaPolicyTranslator;
260 import org.onap.policy.pdp.xacml.application.common.std.StdXacmlApplicationServiceProvider;
262 public class TutorialApplication extends StdXacmlApplicationServiceProvider {
264 private final ToscaPolicyTypeIdentifier supportedPolicyType = new ToscaPolicyTypeIdentifier();
265 private final TutorialTranslator translator = new TutorialTranslator();
268 public String applicationName() {
273 public List<String> actionDecisionsSupported() {
274 return Arrays.asList("authorize");
278 public synchronized List<ToscaPolicyTypeIdentifier> supportedPolicyTypes() {
279 return Arrays.asList(supportedPolicyType);
283 public boolean canSupportPolicyType(ToscaPolicyTypeIdentifier policyTypeId) {
284 return supportedPolicyType.equals(policyTypeId);
288 protected ToscaPolicyTranslator getTranslator(String type) {
294 Create a XACML Request from ONAP Decision Request
295 *************************************************
296 The easiest way to do this is to use the annotations feature from XACML PDP library to create an example XACML
297 request. Then create an instance and simply populate it from an incoming ONAP Decision Request.
299 .. image: tutorial/images/eclipse-create-request.png
301 .. literalinclude:: tutorial/app/src/main/java/org/onap/policy/tutorial/tutorial/TutorialRequest.java
302 :caption: Example Decision Request to Decision Response Implementation
306 Create xacml.properties for the XACML PDP engine to use
307 *******************************************************
308 In the applications *src/test/resources* directory, create a xacml.properties file that will be used by the embedded
309 XACML PDP Engine when loading.
311 .. literalinclude:: tutorial/app/src/test/resources/xacml.properties
312 :caption: Example xacml.properties file
314 :emphasize-lines: 20, 25
316 Create a JUnit and use the TestUtils.java class in xacml-test dependency
317 ************************************************************************
318 Using Eclipse, create a JUnit and be sure to add a setup() method stub. Here you will be utilizing a TestUtils.java
319 class from the policy/xamcl-pdp repo's xacml-test submodule to use some utility methods for building the JUnit test.
321 .. image: tutorial/images/eclipse-junit-create.png
323 Copy the TOSCA Policy Type :download:`link <tutorial/app/src/test/resources/tutorial-policy-type.yaml>` and the TOSCA Policies :download:`link <tutorial/app/src/test/resources/tutorial-policies.yaml>`
324 into the src/test/resources directory.
326 We will create a temporary folder which is used by the **StdXacmlApplicationServiceProvider** to store working copies of policies as they are loaded
327 into the application.
329 .. literalinclude:: tutorial/app/src/test/java/org/onap/policy/tutorial/tutorial/TutorialApplicationTest.java
330 :caption: Example Translator Implementation
333 Run the JUnit test. Its easiest to run it via a terminal command line using maven commands.
337 :caption: Running Maven Commands
342 Building Docker Image
343 *********************
344 Once you have created enough JUnit tests that test the TutorialTranslator.java and TutorialRequest.java classes, you are ready to now make your
345 application build a docker image that incorporates your application with the XACML PDP Engine. The XACML PDP Engine
346 must be able to *find* your Java.Service in the classpath. This is easy to do, just create a jar file for your application
347 and copy into the same directory used to startup the XACML PDP.
349 Here is a Dockerfile as an example:
351 .. literalinclude:: tutorial/app/src/main/docker/Dockerfile
355 Download Tutorial Application Example
356 *************************************
358 If you don't wish to use Eclipse, or go through the steps outlined above. The tutorial is
359 available for download:
361 :download:`Download tutorial tar <tutorial/tutorial.tar>`
363 After you tar xf tutorial.jar, you can import it into Eclipse or your favorite editor. Or simply
364 use a terminal command line to build, test and run the tutorial.
366 In addition, there is a POSTMAN collection available for setting up and running tests against a
367 running instance of ONAP Policy Components (api, pap, dmaap-simulator, tutorial-xacml-pdp).
369 :download:`Download tutorial POSTMAN Collection <tutorial/PolicyApplicationTutorial.postman_collection.json>`