diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/sections/configuration/client.rst | 181 | ||||
| -rw-r--r-- | docs/sections/configuration/service.rst | 352 |
2 files changed, 351 insertions, 182 deletions
diff --git a/docs/sections/configuration/client.rst b/docs/sections/configuration/client.rst index 31106b88..4b8fe205 100644 --- a/docs/sections/configuration/client.rst +++ b/docs/sections/configuration/client.rst @@ -29,183 +29,4 @@ For Beijing, full TLS is expected among all components. AAF provides the "Certi Example Source Code ------------------- -Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java - -.. code:: java - -/** - * ============LICENSE_START==================================================== - * org.onap.aaf - * =========================================================================== - * Copyright (c) 2018 AT&T Intellectual Property. All rights reserved. - * =========================================================================== - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * ============LICENSE_END==================================================== - * - */ - -package org.onap.aaf.client.sample; - -import java.io.IOException; -import java.security.Principal; -import java.util.ArrayList; -import java.util.List; - -import org.onap.aaf.cadi.Access; -import org.onap.aaf.cadi.CadiException; -import org.onap.aaf.cadi.LocatorException; -import org.onap.aaf.cadi.Permission; -import org.onap.aaf.cadi.PropAccess; -import org.onap.aaf.cadi.aaf.AAFPermission; -import org.onap.aaf.cadi.aaf.v2_0.AAFAuthn; -import org.onap.aaf.cadi.aaf.v2_0.AAFConHttp; -import org.onap.aaf.cadi.aaf.v2_0.AAFLurPerm; -import org.onap.aaf.cadi.principal.UnAuthPrincipal; -import org.onap.aaf.cadi.util.Split; -import org.onap.aaf.misc.env.APIException; - -public class Sample { - private static Sample singleton; - final private AAFConHttp aafcon; - final private AAFLurPerm aafLur; - final private AAFAuthn<?> aafAuthn; - - /** - * This method is to emphasize the importance of not creating the AAFObjects over and over again. - * @return - */ - public static Sample singleton() { - return singleton; - } - - public Sample(Access myAccess) throws APIException, CadiException, LocatorException { - aafcon = new AAFConHttp(myAccess); - aafLur = aafcon.newLur(); - aafAuthn = aafcon.newAuthn(aafLur); - } - - /** - * Checking credentials outside of HTTP/S presents fewer options initially. There is not, for instance, - * the option of using 2-way TLS HTTP/S. - * - * However, Password Checks are still useful, and, if the Client Certificate could be obtained in other ways, the - * Interface can be expanded in the future to include Certificates. - * @throws CadiException - * @throws IOException - */ - public Principal checkUserPass(String fqi, String pass) throws IOException, CadiException { - String ok = aafAuthn.validate(fqi, pass); - if(ok==null) { - System.out.println("Success!"); - /* - UnAuthPrincipal means that it is not coming from the official Authorization chain. - This is useful for Security Plugins which don't use Principal as the tie between - Authentication and Authorization - - You can also use this if you want to check Authorization without actually Authenticating, as may - be the case with certain Onboarding Tooling. - */ - return new UnAuthPrincipal(fqi); - } else { - System.out.printf("Failure: %s\n",ok); - return null; - } - - - } - - /** - * An example of looking for One Permission within all the permissions user has. CADI does cache these, - * so the call is not expensive. - * - * Note: If you are using "J2EE" (Servlets), CADI ties this function to the method: - * HttpServletRequest.isUserInRole(String user) - * - * The J2EE user can expect that his servlet will NOT be called without a Validated Principal, and that - * "isUserInRole()" will validate if the user has the Permission designated. - * - */ - public boolean oneAuthorization(Principal fqi, Permission p) { - return aafLur.fish(fqi, p); - } - - public List<Permission> allAuthorization(Principal fqi) { - List<Permission> pond = new ArrayList<Permission>(); - aafLur.fishAll(fqi, pond); - return pond; - } - - - public static void main(String[] args) { - // Note: you can pick up Properties from Command line as well as VM Properties - // Code "user_fqi=... user_pass=..." (where user_pass can be encrypted) in the command line for this sample. - // Also code "perm=<perm type>|<instance>|<action>" to test a specific Permission - PropAccess myAccess = new PropAccess(args); - try { - /* - * NOTE: Do NOT CREATE new aafcon, aafLur and aafAuthn each transaction. They are built to be - * reused! - * - * This is why this code demonstrates "Sample" as a singleton. - */ - singleton = new Sample(myAccess); - String user = myAccess.getProperty("user_fqi"); - String pass= myAccess.getProperty("user_pass"); - - if(user==null || pass==null) { - System.err.println("This Sample class requires properties user_fqi and user_pass"); - } else { - pass = myAccess.decrypt(pass, false); // Note, with "false", decryption will only happen if starts with "enc:" - // See the CODE for Java Methods used - Principal fqi = Sample.singleton().checkUserPass(user,pass); - - if(fqi==null) { - System.out.println("OK, normally, you would cease processing for an " - + "unauthenticated user, but for the purpose of Sample, we'll keep going.\n"); - fqi=new UnAuthPrincipal(user); - } - - // AGAIN, NOTE: If your client fails Authentication, the right behavior 99.9% - // of the time is to drop the transaction. We continue for sample only. - - // note, default String for perm - String permS = myAccess.getProperty("perm","org.osaaf.aaf.access|*|read"); - String[] permA = Split.splitTrim('|', permS); - if(permA.length>2) { - final Permission perm = new AAFPermission(permA[0],permA[1],permA[2]); - // See the CODE for Java Methods used - if(singleton().oneAuthorization(fqi, perm)) { - System.out.printf("Success: %s has %s\n",fqi.getName(),permS); - } else { - System.out.printf("%s does NOT have %s\n",fqi.getName(),permS); - } - } - - - // Another form, you can get ALL permissions in a list - // See the CODE for Java Methods used - List<Permission> permL = singleton().allAuthorization(fqi); - if(permL.size()==0) { - System.out.printf("User %s has no Permissions THAT THE CALLER CAN SEE",fqi.getName()); - } else { - System.out.print("Success:\n"); - for(Permission p : permL) { - System.out.printf("\t%s has %s\n",fqi.getName(),p.getKey()); - } - } - } - } catch (APIException | CadiException | LocatorException | IOException e) { - e.printStackTrace(); - } - } -}
\ No newline at end of file +Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java
\ No newline at end of file diff --git a/docs/sections/configuration/service.rst b/docs/sections/configuration/service.rst index 7cbbb748..ae5d0305 100644 --- a/docs/sections/configuration/service.rst +++ b/docs/sections/configuration/service.rst @@ -1,5 +1,353 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -Service Configuration -===================== +Service Configuration - 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 +========================= + +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) +================================ +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; + +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>aaf-cadi-aaf</artifactId> +<version>THE_LATEST_VERSION</version> +<classifier>full</classifier> +</dependency> + + |