summaryrefslogtreecommitdiffstats
path: root/docs/AAF-API-Documentation/Connecting-to-AAF.rst
blob: d2112eee7d5f2aa9fbe4d605ab1ca8bf43f2585b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
=================
Connecting to AAF
=================

Methods to Connect
==================

- If you are a Servlet in a Container, use CADI Framework with AAF Plugin.  It's very easy, and includes BasicAuth for Services.
- Java Technologies
- Technologies using Servlet Filters
- DME2 (and other Servlet Containers) can use Servlet Filters
- Any WebApp can plug in CADI as a Servlet Filter
- Jetty can attach a Servlet Filter with Code, or as WebApp
- Tomcat 7 has a "Valve" plugin, which is similar and supported
- Use the AAFLur Code directly (shown)
- All Java Technologies utilize Configuration to set what Security elements are required
- example: Global Login can be turned on/off, AAF Client needs information to connect to AAF Service
- There are several specialty cases, which AAF can work with, including embedding all properties in a Web.xml, but the essentials needed are:
- CADI Jars
- cadi.properties file (configured the same for all technologies)
- Encrypt passwords with included CADI technology, so that there are no Clear Text Passwords in Config Files (ASPR)
- See CADI Deployment on how to perform this with several different technologies.
- AAF Restfully (see RESTFul APIS)

IMPORTANT: If Direct RESTFul API is used, then it is the Client's responsibility to Cache and avoid making an AAF Service Calls too often
Example: A Tool like Cassandra will ask for Authentication hundreds of times a second for the same identity during a transaction.  Calling the AAF Service for each would be slow for the client, and wasteful of Network and AAF Service Capacities.
Rogue Clients can and will be denied access to AAF.


J2EE (Servlet Filter) Method
============================

1.  Per J2EE design, the Filter will deny any unauthenticated HTTP/S call; the Servlet will not even be invoked.
a.  Therefore, the Servlet can depend on any transaction making it to their code set is Authenticated.
b.  Identity can be viewed based on the HttpServletRequest Object (request.getUserPrincipal() )
2.  Per J2EE design, AAF Filter overloads the HttpServletRequest for a String related to "Role".  (request.isUserInRole("...") )
a.  For AAF, do not put in "Role", but the three parts of requested "Permission", separated by "|", i.e.  "org.onap.aaf.myapp.myperm|myInstance|myAction".
3.  NOT REQUIRED: An added benefit, but not required, is a JASPI like interface, where you can add an Annotation to your Servlet.
a.  When used, no transaction will come into your code if the listed Permissions are not Granted to the Incoming Transaction.
b.  This might be helpful for covering separate Management Servlet implementations.



Servlet Code Snippet
=========================

  .. code:: bash

    public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
    HttpServletRequest request;
    try {
      request = (HttpServletRequest)req;
    } catch (ClassCastException e) {
        throw new ServletException("Only serving HTTP today",e);
    }

    // Note: CADI is OVERLOADING the concept of "isUserInRole".. You need to think "doesUserHavePermssion()"
    // Assume that you have CREATED and GRANTED An AAF Permission in YOUR Namespace
    // Example Permission:   "org.onap.aaf.myapp.myPerm * write"

    // Think in your head, "Does user have write permission on any instance of org.onap.aaf.myapp.myPerm
    if(request.isUserInRole("org.onap.aaf.myapp.myPerm|*|write")) {
        // *** Do something here that someone with "myPerm write" permissions is allowed to do ***
    } else {
        // *** Do something reasonable if user is denied, like an Error Message ***
    }

    }

Here is a working TestServlet, where you can play with different Permissions that you own on the URL, i.e.:
https://<your machine:port>/caditest/testme?PERM=org.onap.aaf.myapp.myPerm|*|write

Sample Servlet (Working example)
================================

  .. code:: java

    package org.onap.aaf.cadi.debug;
    import java.io.FileInputStream;
    import java.io.IOException;
    import java.net.InetAddress;
    import java.net.UnknownHostException;
    import java.util.HashMap;
    import java.util.Map;
    import java.util.Map.Entry;
    import java.util.Properties;
    import javax.servlet.Servlet;
    import javax.servlet.ServletConfig;
    import javax.servlet.ServletException;
    import javax.servlet.ServletRequest;
    import javax.servlet.ServletResponse;
    import javax.servlet.http.HttpServletRequest;
    import org.eclipse.jetty.server.Server;
    import org.eclipse.jetty.server.ServerConnector;
    import org.eclipse.jetty.server.handler.ContextHandler;
    import org.eclipse.jetty.servlet.FilterHolder;
    import org.eclipse.jetty.servlet.FilterMapping;
    import org.eclipse.jetty.servlet.ServletContextHandler;
    import org.eclipse.jetty.servlet.ServletHandler;
    import org.onap.aaf.cadi.filter.CadiFilter;
    import org.onap.aaf.cadi.filter.RolesAllowed;
    import org.onap.aaf.cadi.jetty.MiniJASPIWrap;

    public class CSPServletTest {
      public static void main(String[] args) {
        // Go ahead and print Test reports in cadi-core first
        Test.main(args);
        String hostname=null;
        try {
          hostname = InetAddress.getLocalHost().getHostName();
        } catch (UnknownHostException e) {
          e.printStackTrace();
          System.exit(1);
        }
        Properties props = new Properties();
        Map<String,String> map = new HashMap<String,String>();
        try {
          FileInputStream fis = new FileInputStream("run/cadi.properties");
          try {
            props.load(fis);
            String key,value;
            for( Entry<Object, Object> es  : props.entrySet()) {
              key = es.getKey().toString();
              value = es.getValue().toString();
              map.put(key,value);
              if(key.startsWith("AFT_") || key.startsWith("DME2")) {
                System.setProperty(key,value);
              }
            }
          } finally {
            fis.close();
          }
        } catch(IOException e) {
          System.err.println("Cannot load run/cadi.properties");
          System.exit(1);
        }
        String portStr = System.getProperty("port");
        int port = portStr==null?8080:Integer.parseInt(portStr);
        try {
          // Add ServletHolder(s) and Filter(s) to a ServletHandler
          ServletHandler shand = new ServletHandler();

          FilterHolder cfh = new FilterHolder(CadiFilter.class);
          cfh.setInitParameters(map);

          shand.addFilterWithMapping(cfh, "/*", FilterMapping.ALL);
          shand.addServletWithMapping(new MiniJASPIWrap(MyServlet.class),"/*");
          // call initialize after start

          ContextHandler ch = new ServletContextHandler();
          ch.setContextPath("/caditest");
          ch.setHandler(shand);
          for( Entry<Object,Object> es : props.entrySet()) {
            ch.getInitParams().put(es.getKey().toString(), es.getValue().toString());
          }
          //ch.setErrorHandler(new MyErrorHandler());

          // Create Server and Add Context Handler
          final Server server = new Server();
          ServerConnector http = new ServerConnector(server);
          http.setPort(port);
          server.addConnector(http);
          server.setHandler(ch);

          // Start
          server.start();
          shand.initialize();

          System.out.println("To test, put http://"+ hostname + ':' + port + "/caditest/testme in a browser or 'curl'");
          // if we were really a server, we'd block the main thread with this join...
          // server.join();
          // But... since we're a test service, we'll block on StdIn
          System.out.println("Press <Return> to end service...");
          System.in.read();
          server.stop();
          System.out.println("All done, have a good day!");
        } catch (Exception e) {
          e.printStackTrace();
          System.exit(1);
        }
      }
      @RolesAllowed({"org.onap.aaf.myapp.myPerm|myInstance|myAction"})
      public static class MyServlet implements Servlet {
        private ServletConfig servletConfig;

        public void init(ServletConfig config) throws ServletException {
          servletConfig = config;
        }

        public ServletConfig getServletConfig() {
          return servletConfig;
        }

        public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
          HttpServletRequest request;
          try {
            request = (HttpServletRequest)req;
          } catch (ClassCastException e) {
            throw new ServletException("Only serving HTTP today",e);
          }

          res.getOutputStream().print("<html><header><title>CSP Servlet Test</title></header><body><h1>You're good to go!</h1><pre>" +
              request.getUserPrincipal());

          String perm = request.getParameter("PERM");
          if(perm!=null)
            if(request.isUserInRole(perm)) {
              if(perm.indexOf('|')<0)
                res.getOutputStream().print("\nCongrats!, You are in Role " + perm);
                else
                res.getOutputStream().print("\nCongrats!, You have Permission " + perm);
            } else {
              if(perm.indexOf('|')<0)
                res.getOutputStream().print("\nSorry, you are NOT in Role " + perm);
                else
                res.getOutputStream().print("\nSorry, you do NOT have Permission " + perm);
            }

          res.getOutputStream().print("</pre></body></html>");

        }

        public String getServletInfo() {
          return "MyServlet";
        }

        public void destroy() {
        }
      }
    }

Java Direct (AAFLur) Method
===========================
The AAFLur is the exact component used within all the Plugins mentioned above.  It is written so that it can be called standalone as well, see the Example as follows
package org.onap.aaf.example;

  .. code:: bash

    import java.util.ArrayList;
    import java.util.List;
    import java.util.Properties;

    import org.onap.aaf.cadi.Access;
    import org.onap.aaf.cadi.Permission;
    import org.onap.aaf.cadi.aaf.v2_0.AAFAuthn;
    import org.onap.aaf.cadi.aaf.v2_0.AAFCon;
    import org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm;
    import org.onap.aaf.cadi.config.Config;
    import org.onap.aaf.cadi.lur.aaf.AAFPermission;
    import org.onap.aaf.cadi.lur.aaf.test.TestAccess;

    public class ExamplePerm2_0 {
      public static void main(String args[]) {
        // Normally, these should be set in environment.  Setting here for clarity
        Properties props = System.getProperties();
        props.setProperty("AFT_LATITUDE", "32.780140");
        props.setProperty("AFT_LONGITUDE", "-96.800451");
        props.setProperty("AFT_ENVIRONMENT", "AFTUAT");
        props.setProperty(Config.AAF_URL,
        "https://DME2RESOLVE/service=org.onap.aaf.authz.AuthorizationService/version=2.0/envContext=TEST/routeOffer=BAU_SE"
            );
        props.setProperty(Config.AAF_USER_EXPIRES,Integer.toString(5*60000));  // 5 minutes for found items to live in cache
        props.setProperty(Config.AAF_HIGH_COUNT,Integer.toString(400));    // Maximum number of items in Cache);
        props.setProperty(Config.CADI_KEYFILE,"keyfile"); //Note: Be sure to generate with java -jar <cadi_path>/lib/cadi-core*.jar keygen keyfile
    //    props.setProperty("DME2_EP_REGISTRY_CLASS","DME2FS");
    //    props.setProperty("AFT_DME2_EP_REGISTRY_FS_DIR","../../authz/dme2reg");


        // Link or reuse to your Logging mechanism
        Access myAccess = new TestAccess(); //

        //
        try {
          AAFCon<?> con = new AAFConDME2(myAccess);

          // AAFLur has pool of DME clients as needed, and Caches Client lookups
          AAFLurPerm aafLur = con.newLur();
          // Note: If you need both Authn and Authz construct the following:
          AAFAuthn<?> aafAuthn = con.newAuthn(aafLur);

          // Do not set Mech ID until after you construct AAFAuthn,
          // because we initiate  "401" info to determine the Realm of
          // of the service we're after.
          con.basicAuth("xxxx@aaf.abc.com", "XXXXXX");

          try {

            // Normally, you obtain Principal from Authentication System.
            // For J2EE, you can ask the HttpServletRequest for getUserPrincipal()
            // If you use CADI as Authenticator, it will get you these Principals from
            // CSP or BasicAuth mechanisms.
            String id = "xxxx@aaf.abc.com"; //"cluster_admin@gridcore.abc.com";

            // If Validate succeeds, you will get a Null, otherwise, you will a String for the reason.
            String ok = aafAuthn.validate(id, "XXXXXX");
            if(ok!=null)System.out.println(ok);

            ok = aafAuthn.validate(id, "wrongPass");
            if(ok!=null)System.out.println(ok);


            // AAF Style permissions are in the form
            // Type, Instance, Action
            AAFPermission perm = new AAFPermission("org.onap.aaf.grid.core.coh",":dev_cluster", "WRITE");

            // Now you can ask the LUR (Local Representative of the User Repository about Authorization
            // With CADI, in J2EE, you can call isUserInRole("org.onap.aaf.mygroup|mytype|write") on the Request Object
            // instead of creating your own LUR
            System.out.println("Does " + id + " have " + perm);
            if(aafLur.fish(id, perm)) {
              System.out.println("Yes, you have permission");
            } else {
              System.out.println("No, you don't have permission");
            }

            System.out.println("Does Bogus have " + perm);
            if(aafLur.fish("Bogus", perm)) {
              System.out.println("Yes, you have permission");
            } else {
              System.out.println("No, you don't have permission");
            }

            // Or you can all for all the Permissions available
            List<Permission> perms = new ArrayList<Permission>();

            aafLur.fishAll(id,perms);
            for(Permission prm : perms) {
              System.out.println(prm.getKey());
            }

            // It might be helpful in some cases to clear the User's identity from the Cache
            aafLur.remove(id);
          } finally {
            aafLur.destroy();
          }
        } catch (Exception e) {
          e.printStackTrace();
        }

      }
    }

There are two current AAF Lurs which you can utilize:
-  Org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm is the default, and will fish based on the Three-fold "Permission" standard in AAF
To run this code, you will need from a SWM deployment (org.onap.aaf.cadi:cadi, then soft link to jars needed):
-  cadi-core-<version>.jar
-  cadi-aaf-<version>-full.jar
or by Maven
<dependency>
<groupId>org.onap.aaf.cadi</groupId>
<artifactId>cadi-aaf</artifactId>
<version>THE_LATEST_VERSION</version>
<classifier>full</classifier>
</dependency>
If you need the Java Client definitions only,

   Also needed are the DME2 Client libraries:
-  dme2-<version>.jar
-  discovery-clt-<version>.jar