= Maintenance of iPlanet ACIs = Original Author: Mark Anderson - 20081204 ''NOTE:'' All Documentation following is out of date. See: [[https://iam.alaska.edu/sunldap/wiki/Acis|Sun LDAP/Access Control ACIs]] for the current procedures to maintain iPlanet ACIs. == Steps to create ACIs == === 1. Determine Method for Creating ACI === You may find it easiest to create the ACI first from scratch in Test and then to enter it into the ACI workbook afterwards so that it can be documented there. Alternatively you can start with the workbook in step 2. === 2. Identify Current ACI Workbook === Identify the most recent ACI workbook in the Chinook\Dirsrvsptgp\ACIs\ folder, e.g. ACI_worksheet_20081105mpa. === 3. Open the ACI Workbook === Save it immediately as an ACI workbook suffixed with the current date. === 4. Add a Row for the ACI to the ACI Type Lookup Tabbed Page === The left-hand column of the row is a name for the ACI, chosen by you. The right-hand column is a very short description of the ACI. If you modify the ACI Attribs tabbed page later in this procedure, this description will appear beside each attribute exposed by the ACI when you enter that attribute's row on the page. ==== Naming New ACIs ==== The convention I am currently using is to name a new ACI after the application or resource account that prompted its creation (e.g. SHIBBOLETHREAD). This helps show that the purpose of the ACI is to support that particular application. If later the privileges of this application must be changed, the application-specific name will attract attention to the ACI as a candidate for the new privileges. If on the other hand the ACI is used for a second application or resource account, I change the ACI name to one which describes the ACI's characteristics (e.g. UASYSTEMIDREAD). This helps show that the ACI is shared by several applications and that changing it requires re-checking the needs of all those applications. Not all existing ACIs are named using this convention. ==== ACI Scope ==== At the start of the EDIR project, emphasis was placed on reusing ACIs to slow their proliferation. In general, I have not been able to realize this goal. An individual resource account typically has different needs than any other resource account. If an existing ACI meets most but not all of the needs of a new resource account, then it must be supplemented by another ad hoc ACI whose scope is very specialized and which probably cannot be reused. The addition of the ad hoc ACI also defeats the purpose of slowing the proliferation of ACIs. If, on the other hand, an existing ACI meets the needs of a new resource account and provides other access besides, then associating that ACI with that account violates the principle of least privilege. In general, then, expect to create a new ACI for each new resource account. ==== ACI Dependence ==== In the past, when creating a new ACI, I have first checked to see which of the desired attributes were already exposed to anonymous query and then constructed the new ACI using only the remaining attributes. In retrospect it seems to me it would be better to not assume that an attribute is going to remain visible to the public but rather to include all the desired attributes in the ACI. === 5. Determine Intended Permissions for ACI === If the new ACI is intended to allow "read", "compare", "search" and/or "write" -- that is, it is an ACI that exposes attributes -- then you will need to modify both the ACI Logic and the ACI Attribs tabbed pages. If the new ACI is intended to allow "add" and "delete", or is some other ACI that does not expose attributes, then you will need to modify only the ACI Logic tab. === 6. Modify ACI Tabbed Pages === ==== Modify the ACI Attribs tabbed page ==== If your planned ACI requires attribute modification, it does not matter where in this page you add your new row(s), since the page will be automatically re-sorted later by the macro which writes the LDIF. For each attribute that is to be exposed by the ACI, create a spreadsheet row consisting of: * ACI LABEL: The name of the ACI you are constructing, chosen by you in step 4. You will also use this name later, on the ACI Logic page. * OU1 and OU2: These always have the same value; the duplication is needed by the macro for some reason. The value is the branch of the LDAP directory that the ACI will inhabit and grant permissions upon (or enforce restrictions upon). It will be one of PEOPLE, RESOURCE, DEPARTMENTS, ROUTING. You will also use this value later on the ACI Logic page. * ACI TARGET ATTRIBUTE: An existing EDIR/AUTHSERV attribute that is to be exposed by the planned ACI. * EXISTS: This is always X. This X is purely a marker which later appears on the pivot table of the Pivot tabbed page. * ATTRIB TYPE and ACI TYPE: Do not fill in a constant value in these columns. Instead copy-and-paste the VLOOKUP() function invocations from a preexisting row's ATTRIB TYPE and ACI TYPE columns into the new row's ATTRIB TYPE and ACI TYPE columns. ==== Modify the ACI Logic tabbed page ==== It does not matter where in this page you add your new row, since the page will be automatically re-sorted later by the macro which writes the LDIF. In the new row, fill in: * ACI OU: The branch of the LDAP directory that the planned ACI will inhabit and grant permissions upon (or enforce restrictions upon). It will be one of PEOPLE, RESOURCE, DEPARTMENTS, ROUTING. You used this value earlier on the ACI Attribs page. * ACI LABEL: The name of the ACI you are constructing, chosen by you. You used this name earlier on the ACI Attribs page. * ACI Mode: "allow" or "deny", depending on whether the planned ACI grants access or blocks access. * ACI Permissions: the interrogation (search, read, compare) or update (add, delete, write) operations granted or blocked by the planned ACI. * ACI Bind Rule: regular expression which describes who the planned ACI applies to. Typically includes one or more of roledn e.g. ldap:///cn=fooRole,ou=resource,dc=alaska,dc=edu ip IP address from which LDAP operation originates userdn e.g. ldap:///anyone If you choose to use roledn, the cn (foorole in the example above) will be the same as the value of an EDIRROLE attribute. This EDIRROLE will later be assigned to the accounts who are targeted by the ACI. I have so far created a new role for each new ACI and have named it after the ACI. If you rename the ACI, there may be no point in renaming the corresponding role and changing the EDIRROLE values assigned to each of the affected accounts, expecially if the role name is usefully descriptive; it may be better to create a new descriptively-named role and EDIROLE value and link both roles to the ACI in this step. === 7. Invoke the macro which constructs the entire set of ACI creation commands === This macro is invoked from the ACI Attribs and ACI Logic tabbed pages: * SHIFT+CONTROL+L In the resulting dialog box, accept the default of ALL OUs and click OK. This will build the ACI creation commands in LDIF on the LDIF tabbed page. When the macro completes, save the workbook with all your changes. === 8. Transfer the ACI creation commands from the LDIF tabbed page === Transfer from the LDIF tabbed pageof the spreadsheet to a text file on a directory host. 1. On any "e" box, as UNIX user iplanet * cd /export/home/iplanet/local/ldap/schema/ACI * ls -ltr 1. Note the most recent ACI creation file in the directory. The name will be of the form user_update._ 1. If you introduce some problem into the directory with your new ACI, you will use this older ACI file to restore the directory to its previous state. 1. Open a new ACI file with your favorite text editor. Copy-and-paste the entire content of the LDIF tabbed page of the spreadsheet into the file. === 9. Add the new ACI to the Test directory === Accomplish this by dropping and recreating all ACIs in that instance. 1. apply_acisTest.ksh 1. apply_acisTest.ksh is in /export/home/iplanet/local/ldap/scripts, and writes standard output and standard error, respectively, to the files apply_acisTest.out and apply_acisTest.err in that directory. 1. After apply_acisTest.ksh completes, review its standard error in apply_acisTest.err. A single line like this is an expected, ignorable error: * ldap_modify: No such attribute Any other errors represent problems with the ACI file which must be corrected. If they cannot be resolved, roll back the changes you made by dropping and recreating all ACIs with the previous ACI file you identified in Step 4 above. N.B. The ignorable error is caused by the first command in the ACI file, which attempts to drop all ACIs in the root of the directory tree (dn: dc=Alaska,dc=edu). Normally there are no ACIs there. === 10. Make the ACI change visible to the EDIR and AUTHSERV gateways === Running the following two scripts on the "E" boxes (or at least on those "E" boxes serving EDIR/AUTHSERV, which are currently egegik and eklutna). make ACI changes visible to the gateways. The gateways cannot see the ACIs inside the LDAP server and so depend on the files updated by these scripts to find out what updateable fields they should show to users. These scripts will be run every morning via Appworx if you miss this step: * AS iPLANET: ~iplanet/local/ldap/scripts/static_list_maint.ksh Test * AS LDAPGW: ~ldapgw/local/scripts/static_list_maint.ksh Test === 11. Special Case === You defined the ACI on the ACI Logic tabbed page using a roledn in the ACI bind rule as follows: * ldap:///cn=fooRole,ou=resource,dc=alaska,dc=edu ==== Actions ==== 1. You will need to create an iPlanet role with that DN. This role that you create will include an EDIRrole name, chosen by you, which you can grant to a resource or people account. This is the mechanism that links the ACI you created to an account which will benefit from or be restricted by the ACI: the ACI names an iPlanet role, the iPlanet role names a EDIRrole, and the EDIRrole is an attribute of the account. 1. Create the entry for the role. The name you choose for the EDIRrole does not need to be the same name as the cn you already chose for the iPlanet role, but if the EDIRrole will only comprise one iPlanet role then it may be the simplest naming convention to follow. * dn: cn=,ou=resource,dc=alaska,dc=edu * objectclass: top * objectclass: LDAPsubentry * objectclass: nsRoleDefinition * objectclass: nsComplexRoleDefinition * objectclass: nsFilteredRoleDefinition * cn: * nsRoleFilter: (&(EDIRROLE=*)(EDIRrole= 1. Feed the LDIF above to the directory with ldap_add, e.g. ldap_addTest < myFile.ldif. * The role will replicate to all the other LDAP servers. Place the LDIF in ~iplanet/local/ldap/schema/ROLE/ on all the "E" hosts for possible future reference. 1. Now grant the EDIRrole to the people or resource account which you want to benefit from (or be restricted by) the ACI you created: * dn: uid=,ou=,dc=alaska,dc=edu * changetype: modify * add: EDIRrole * EDIRrole: 1. Feed the LDIF above to the directory with ldap_modify, e.g. ldap_modifyTest. === 12. Test the new ACI. === If it works correctly, promote the new ACI to Prep and Production in turn by repeating Step 5 with the apply_acisPrep.ksh and apply_acisProd.ksh scripts. If the ACI does not and cannot be made to work correctly, roll back the changes you made by dropping and recreating all ACIs with the previous ACI file you identified in Step 4 above. Note that defined the ACI on the ACI Logic tabbed page using a roledn in the ACI bind rule, you will need to create an EDIRrole and assign it to the === 13. Copy the ACI file you created to the other directory hosts === so that it will be available as the rollback ACI file for the next person who creates an ACI. ACIfile= for host in eklutna elias edgar egegik ; do # only if not the host you're working from if [[ "$host" != $(hostname) ]] ; then echo "#### $host ####" scp -p $ACIfile $host:/export/home/iplanet/local/ldap/schema/ACI/. fi done ########################################################[[br]] LEGACY CHANGE HISTORY - NOTE: All subsequent changes are recorded in TracWiki[[br]] ########################################################[[br]] 20090731 mpa Somehow managed to permanently enable macros, so removed the steps for enabling them each time workbook is opened. 20090707 mpa Added steps to - advise that ad hoc creation of ACI may be the best first step. - modify ACI Type Lookup tabbed page. - create entry for iPlanet role and EDIRrole. 20090210 mpa Added step to run static_list_maint.ksh scripts.