From 15f3969cb88ce5576da368708dad1903828148f0 Mon Sep 17 00:00:00 2001 From: Instrumental Date: Fri, 20 Jul 2018 11:32:41 -0500 Subject: Document AAF Installation Issue-ID: AAF-292 Change-Id: Ic02bf086454dcd0de306f9e6d9c334fd0f6b21e7 Signed-off-by: Instrumental --- docs/sections/installation/fromsource.rst | 190 ------------------ docs/sections/installation/install_from_source.rst | 218 +++++++++++++++++++++ docs/sections/installation/sample.rst | 190 ++++++++++++++++++ 3 files changed, 408 insertions(+), 190 deletions(-) delete mode 100644 docs/sections/installation/fromsource.rst create mode 100644 docs/sections/installation/install_from_source.rst create mode 100644 docs/sections/installation/sample.rst (limited to 'docs') diff --git a/docs/sections/installation/fromsource.rst b/docs/sections/installation/fromsource.rst deleted file mode 100644 index 19ac6221..00000000 --- a/docs/sections/installation/fromsource.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. - -AAF From Source Code -==================== - -Example Source Code -------------------- -Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java - -.. code-block:: 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 allAuthorization(Principal fqi) { - List pond = new ArrayList(); - 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=||" 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 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 diff --git a/docs/sections/installation/install_from_source.rst b/docs/sections/installation/install_from_source.rst new file mode 100644 index 00000000..4a4b03c5 --- /dev/null +++ b/docs/sections/installation/install_from_source.rst @@ -0,0 +1,218 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. + +Installing from Source Code +============================ + +*Note: this document assumes UNIX Bash Shell. Being AAF works in Windows, but you will have to create your own script/instruction conversions.* + +------------------ +Modes +------------------ + +AAF can be run in various ways + * Standalone (on your O/S) + * Docker (localized) + * Kubernetes + * ONAP Styles + * HEAT (Docker Container Based Initilization) + * OOM (a Helm Chart based Kubernetes Environment) + +------------------ +Prerequisites +------------------ + +You need the following tools to build and run AAF + * git + * maven + * Java (JDK 1.8+, openjdk is fine) + * Cassandra + * a separate installation is fine + * these instructions will start off with a Docker based Cassandra instance + * Machine - one of the following + * Standalone Java Processes - no additional running environments necessary + * docker - typically available via packages for O/S + * kubernetes - ditto + + +------------------ +Build from Source +------------------ +Choose the directory you wish to start in... This process will create an "authz" subdirectory:: + + $ mkdir -p ~/src + $ cd ~/src + +Use 'git' to 'clone' the master code:: + + $ git clone https://gerrit.onap.org/r/aaf/authz + +Change to that directory:: + + $ cd authz + +Use Maven to build:: + + << TODO, get ONAP Settings.xml>> + $ mvn install + +.. ----------------- +.. Standalone +.. ----------------- + +----------------- +Docker Mode +----------------- + +After you have successfully run maven, you will need a Cassandra. If you don't have one, here are instructions for a Docker Standalone Cassandra. For a *serious* endeavor, you need a multi-node Cassandra. + +From "authz":: + + $ cd auth/auth-cass/src/main/cql + $ vi config.dat + +=================== +Existing Cassandra +=================== + +AAF Casablanca has added a table. If you have an existing AAF Cassandra, do the following:: + + ### If Container Cassandra, add these steps, otherwise, skip + $ docker container cp init2_1.cql aaf_cass:/tmp + $ docker exec -it aaf_cass bash + (docker) $ cd /tmp + ### + $ cqlsh -f 'init2_1.cql' + +===================== +New Docker Cassandra +===================== + +Assuming you are in your src/authz directory:: + + $ cd auth/auth-cass/docker + $ sh dinstall.sh + +--------------------- +AAF Itself +--------------------- + +Assuming you are in your src/authz directory:: + + $ cd auth/docker + ### If you have not done so before (don't overwrite your work!) + $ cp d.props.init d.props + +You will need to edit and fill out the information in your d.props file. Here is info to help + +**Local Env info** - These are used to load the /etc/hosts file in the Containers, so AAF is available internally and externally + + =============== ============= + Variable Explanation + =============== ============= + HOSTNAME This must be the EXTERNAL FQDN of your host. Must be in DNS or /etc/hosts + HOST_IP This must be the EXTERNAL IP of your host. Must be accessible from "anywhere" + CASS_HOST If Docker Cass, this is the INTERNAL FQDN/IP. If external Cass, then DNS|/etc/hosts entry + aaf_env This shows up in GUI and certs, to differentiate environments + aaf_register_as As pre-set, it is the same external hostname. + cadi_latitude Use "https://bing.com/maps", if needed, to locate your current Global Coords + cadi_longitude ditto + =============== ============= + +============================== +"Bleeding Edge" Source install +============================== + +AAF can be built, and local Docker Images built with the following:: + + $ sh dbuild.sh + +Otherwise, just let it pull from Nexus + +============================== +Configure AAF Volume +============================== + +AAF uses a Persistent Volume to store data longer term, such as CADI configs, Organization info, etc, so that data is not lost when changing out a container. + +This volume is created automatically, as necessary, and linked into the container when starting. :: + + ## Be sure to have your 'd.props' file filled out before running. + $ sh aaf.sh + +============================== +Bootstrapping with Keystores +============================== + +Start the container in bash mode, so it stays up. :: + + $ bash aaf.sh bash + id@77777: + +In another shell, find out your Container name. :: + + $ docker container ls | grep aaf_config + +CD to directory with CA p12 files + + * org.osaaf.aaf.p12 + * org.osaaf.aaf.signer.p12 (if using Certman to sign certificates) + +Copy keystores for this AAF Env :: + + $ docker container cp -L org.osaaf.aaf.p12 aaf_agent_:/opt/app/osaaf/local + ### IF using local CA Signer + $ docker container cp -L org.osaaf.aaf.signer.p12 aaf_agent_:/opt/app/osaaf/local + +In Agent Window :: + + id@77777: agent encrypt cadi_keystore_password + ### IF using local CA Signer + id@77777: agent encrypt cm_ca.local + +Check to make sure all passwords are set :: + + id@77777: grep "enc:" *.props + +When good, exit from Container Shell and run AAF :: + + id@77777: exit + $ bash drun.sh + +Check the Container logs for correct Keystore passwords, other issues :: + + $ docker container logs aaf_ + +Watch logs :: + + $ sh aaf.sh taillog + +Notes: + +You can find an ONAP Root certificate, and pre-built trustores for ONAP Test systems at: + | authz/auth/sample/public/AAF_RootCA.cert + | authz/auth/sample/public/truststoreONAPall.jks + +Good Tests to run :: + + ## From "docker" dir + ## + ## assumes you have DNS or /etc/hosts entry for aaf-onap-test.osaaf.org + ## + $ curl --cacert ../sample/public/AAF_RootCA.cer -u demo@people.osaaf.org:demo123456! https://aaf-onap-test.osaaf.org:8100/authz/perms/user/demo@people.osaaf.org + $ openssl s_client -connect aaf-onap-test.osaaf.org:8100 + + + + + + + + + + + + + + diff --git a/docs/sections/installation/sample.rst b/docs/sections/installation/sample.rst new file mode 100644 index 00000000..19ac6221 --- /dev/null +++ b/docs/sections/installation/sample.rst @@ -0,0 +1,190 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright © 2017 AT&T Intellectual Property. All rights reserved. + +AAF From Source Code +==================== + +Example Source Code +------------------- +Note the FULL class is available in the authz repo, cadi_aaf/org/onap/aaf/client/sample/Sample.java + +.. code-block:: 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 allAuthorization(Principal fqi) { + List pond = new ArrayList(); + 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=||" 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 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 -- cgit 1.2.3-korg