docs/sections/AAF_in_a_Nutshell.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4
   5 AAF in a Nutshell
   6 =========================
   7
   8 This is a quick overview of some of the core structures of AAF. A more detailed narrative description can be found at The New Person's Guide to AAF
   9
  10 Parts of AAF - Basic Terms
  11 -----------------------------
  12 A namespace is the container (sometimes called a "security domain" by other security systems) assigned to an application; for instance, "com.att.test"namespaces contain 1 or more roles
  13 roles contain permissions and users
  14
  15   #.    a role is where users and permissions meet; permissions are not granted directly to users, rather a perm is granted to a role and users are added to the role
  16   #.    a role contains 0 or more permissions
  17   #.    a role contains 0 or more users or APPID identities
  18   #.    note that role memberships have an expiration date.
  19
  20      -  The owner of the namespace must re-approve all role memberships periodically.
  21      -  All approval requests, role renewal reviews, credential expiration, etc, emails will go to the namespace owner.
  22      -  If the namespace owner doesn't act upon these emails, users/appid’s will lose their permissions. Applications will break.
  23      -  Restoring lost permissions is the responsibility of the namespace admins, not any AAF support tier.
  24
  25 Namespaces contain 1 or more permissions
  26   #.    other than the access permissions discussed below, AAF does not care about permissions
  27   #.    AAF does not interpret application-specific permissions; in other words, it's up to the applications developers to create a permission scheme.
  28
  29     -   the general usage pattern is that an application will ask for all permissions associated with a user
  30     -   locally, the application interprets what the presence or absence of a permissions means
  31
  32 By default, every namespace has 2 "access" permissions:
  33     #.  a read/write permission, for instance "org.onap.test.access \* \*"
  34     #.  a read only permission, for instance "org.onap.test.access \* read"
  35
  36 By default, every namespace has an admin role, for instance "org.onap.test.admin"
  37     #.  the admin role contains the read/write permission for the namespace
  38
  39        -  if you delete the admin role, or the read/write permission from the role, your admins will have no access to your namespace. This is bad.
  40
  41 see Documentation for Namespace Admins for commands related to namespaces, roles, permissions
  42
  43
  44 AppID Identity
  45 -----------------
  46 To use a AppID in AAF, the AppID must be associated with a namespace
  47   #.    The owner of the namespace MUST BE the sponsor of the AppID.
  48   #.     The owner of the namespace/appid is the ONLY PERSON who can add the AppID to the namespace.
  49   #.    Once added to a namespace, you will now have a AppID identity. For example, namespace=org.onap.test, AppID=m99999, the AppID identity will be m99999@test.onap.org
  50
  51       - note that the domain portion (the part after the "@") is the namespace name reversed
  52
  53 AppID Identities must always be lowercase. Use "m91266@test.onap.org", not "M91266@test.onap.com"
  54
  55 AppID Credentials (passwords)
  56 ---------------------------------
  57 Each AppID identity may have 1 or more credential records
  58  - each record will have its own expiration date
  59  - each record may or may not be associated with the same password
  60
  61 Once the owner of the namespace/AppID has created the initial AppID identity & password, any admin can add new credentials as long as she/he knows a current password.
  62
  63 Here are some scenarios to illustrate some points about  AAF's credentials:
  64 Scenario 1: an application already running in an Instance needs to do their yearly AppID password update
  65
  66  - The AppID identity already has a credential, but it is expiring soon
  67  - The application's support team can create a new credential at any time
  68      - must enter an existing password to create a new one; store your passwords in a secure manner.
  69      - this new record will have an expiration date 1 year out
  70  - the password in the record will be a different password; this means the application's config files need to change
  71  - With a new password in place, there is no tight coordination required when the application's config files are updated. The old password continues to work until its expiration date. The new password is in place and will work as soon as the configuration is changed.
  72
  73 Scenario 2:An AAF command to "extend" the current password. NOTE: extending a password is a temporary workaround; a new credential must be created as soon as possible.
  74  - this does not modiify the existing credential record
  75  - this creates a new credential record with an expiration date 5 days in the future
  76  - an admin of the namespace must now:
  77  - using the appropriate GUI link for the environment, go to the Password Management tab and create a new credential
  78  - if using cadi, digest the new password to get an encrypted password string
  79  - update cadi.properties
  80  - bounce application processes
  81  - if not using cadi,
  82  - update whatever config file is used to store the AppID identity's password
  83  - bounce application processes, if required to re-read config
  84  - to re-iterate: AAF never modifies an existing credential; AAF creates new credential records
  85