Bulk loading is an automated approach to adding and maintaining user identities that complements the manual steps that you can perform within SAS® Management Console. Specifically, bulk loading refers to the importation and synchronization of users and groups into the SAS® Metadata Repository from external sources such as the following:
The bulk-loading process is explained in the following documents:
Depending on the source of your existing users and groups (Active Directory or LDAP, /etc/passwd, or other file), you can start the bulk-loading process with the following sample programs:
Note: Because the programs listed above are sample programs, you have to modify them to support your specific environment and requirements. See the "Importad.sas Example Program" section of this note for an example.
These programs provide the structure for the initial loading of users and groups into the SAS Metadata Repository. Maintenance, or synchronization, of users and groups with your site's master user and group list should be done via synchronization code. The synchronization process is also documented in "Appendix X: User Import Macros" in the SAS® 9.x Intelligence Platform: Security Administration Guide for your SAS release.
Be aware that these programs create the SAS metadata identities, but they do not set authorizations for those identities.
For information about a promotion technique for metadata identities, see Sample 42251, "Promotion of User and Group Metadata."
Because importad.sas is the most commonly used program to start the bulk-loading process, a detailed discussion is provided here. In addition, the program contains comments that help you identify areas that you need to modify. So, be sure to carefully review the comments in the program.
If your external source for person and group data is Microsoft Active Directory, SAS recommends that you use the importad.sas sample program. This program extracts entries, attributes, and attribute values from Active Directory. It does this by using Active Directory connection parameters and SAS CALL routines LDAPS_OPEN, LDAPS_SEARCH, LDAPS_ENTRY, LDAPS_ATTRNAME, LDAPS_ATTRVALUE, and so on.
You can also use importad.sas if you use an LDAP provider other than Microsoft Active Directory, such as OpenLDAP. However, since this program was written to support a Microsoft standard schema, you will have to make modifications to the %ldapextrpersons and %ldapextrgroups macros to support your LDAP schema.
The following describes specific locations in the program that most commonly need to be edited in order for the program to work with your data and/or provide the results that you want. You might also have to edit additional sections depending on your environment. Use the comments in the program for guidance.
Contents
SECTION 1: Setting the connection properties to your LDAP server
SECTION 3: Extracting/fetching users from your LDAP
SECTION 4: Extracting/fetching groups from your LDAP
Enabling TLS Encrypted Communication for LDAPS
SECTION 1
You should review SECTION 1 in the program and provide correct values to connect to your metadata server and Active Directory server. Use one of the following accounts for your METAUSER connection because this account is assured to have full Update permission to the metadata:
If you are connecting to LDAP over Transport Layer Security (TLS), then the assignment of %let ADPort should be a TLS-configured port on the LDAP server. The default secure port is 636, or if you are connecting to the Microsoft Active Directory Global Catalog it is 3269. You will also need to add an option to enable TLS encrypted communication between SAS and the LDAP server. Add the following statement after you set the LDAP connection macros.
Note that there are other ways to enable TLS mode. Please see Enabling TLS encrypted communication for LDAPS within this document.
The assignment of %let keyidvar= determines the value of the match key between the Active Directory entry and the Identity object in the metadata. The value should be unique and non-changing. SAS recommends using the Active Directory attribute employeeID or sAMAccountName. sAMAccountName is a reliable attribute. If you use employeeID, confirm that your organization uses it for the users that you want to load into the metadata. The distinguishedName attribute is less recommended since its value is likely to change, such as when the user moves to a different department represented in a different OrganizationUnit (OU) in Active Directory.
For the assignment of %let WindowsDomain=, consider the authentication mechanism for the SAS Metadata Server. If the user needs to provide a domain-qualified user ID, then set %let WindowsDomain=domain;. Otherwise, if the user needs to provide only their user ID, such as on a UNIX or Linux system using pluggable authentication module (PAM) to integrate with Active Directory, and then set %let WindowsDomain=;.
Create a directory for your Active Directory extract library, and specify this directory instead of the Work library. This directory enables permanent storage and evaluation of the tables in case you need to troubleshoot.
Also, be certain the library is empty prior to each run of the program. For example:
Then assign the two libraries of ADIR to these macro variables:
%let extractlibref=ADIR;
%let importlibref=ADIR;
SECTION 3
In SECTION 3, data is extracted from Active Directory by passing a FILTER (a search criterion) to Active Directory. Active Directory entries that match the condition of the filter are included in a recordset and returned to SAS.
In the DATA step beginning data &extractlibref..ldapusers, you should modify the assignment to FILTER to an appropriate filter value for your Active Directory. The program contains a series of filters to extract entries based on displayName. You might want to use another approach, such as to extract all members of a certain Active Directory group, or groups. Here is an example of querying for people who are in the specified groups:
If you are using more than one memberOf filter, as shown above, and a user is in more than one of those groups, the program creates duplicates of the user in the LDAPUSERS table. You need to remove the duplicates to prevent integrity constraint violations later in the program. Add the following comment and step directly after the RUN statement of the DATA step beginning data &extractlibref..ldapusers:
For more information, go to the Microsoft website for documentation about filters. A good reference is the TechNet article, "Active Directory: LDAP Syntax Filters."
Note: The LDAPS_SEARCH SAS Call routine in SAS 9.x does not support the use of matching rule object identifiers (OID) in the filter value. Using OIDs results in an error. The following is an example of using a matching rule OID in a filter value and the resulting error:
Within the LDAPEXTRPERSONS macro, the program subsets entries from Active Directory based on the existence of an employeeID attribute, with the following IF statement:
if employeeID NE "" then
output &extractlibref..ldapusers; /* output to ldapusers data set */
If your Active Directory does not use employeeID, then remove this condition or set the condition to another attribute that must be populated for a person entry. Be certain to keep the OUTPUT statement when you remove the IF condition. Here is an example:
output &extractlibref..ldapusers; /* output to ldapusers data set */
The form of the login written to metadata is based on this small section of code:
if sAMAccountName NE "" then do;
/* setup login values */
/* we need to prefix the login user ID with the domain ID */
if "&WindowsDomain" = "" then
userid = sAMAccountName ;
else
userid = "&WindowsDomain\" || sAMAccountName ;
password ="";
authdomkeyid = 'domkey' || compress(upcase("&MetadataAuthDomain"));
output &logintbl;
end;
This code creates logins in the form: domain\userid.
If you want your logins to be in the following form, user@UPNsuffix, then you must change the userid = assignment. Here is an example:
userid = strip(sAMAccountName) || "@&WindowsDomain" ;
The above example assumes that you have assigned the WindowsDomain macro variable (near the top of the program) to your UPNsuffix.
You rarely need to change the rest of SECTION 3.
SECTION 4
SECTION 4 is similar to SECTION 3, but it is dedicated to extracting group data. In the DATA step beginning data &extractlibref..ldapgrps, you should modify the assignment to FILTER to an appropriate filter value for your Active Directory. The program contains a series of filters to extract entries based on name. You will probably want to indicate specific groups by name. Here is an example:
The result of the extraction is a master table for users, a master table for groups, and a corresponding canonical set of master tables. For more information, see "Canonical Tables" in "Appendix: User Import Macros" in the SAS® 9.4 Intelligence Platform: Security Administration Guide.
The remainder of the program attempts to add these users, groups, and other data into the metadata. You typically do not need to modify anything else in the program.
Enabling TLS Encrypted Communication for LDAPS
To support a TLS encrypted communication between the SAS program and your LDAP server, you must enable TLS mode for the SAS session. SAS then communicates via LDAPS on the secure port. You can enable TLS mode for the SAS session in one of the following three ways:
options set=LDAP_TLSMODE 1;
-set LDAP_TLSMODE=1
Note that since OPT_REFERRALS_ON is being set in the LDAPS_SETOPTIONS routine that follows LDAPS_OPEN, the first assignment is redundant and therefore can be changed to set the TLS mode.
You must also make digital certificates available to the SAS session. For UNIX and z/OS systems, this is done via the SSLCALISTLOC SAS system option, which points to a trust list file that contains all certificates for all CAs that are to be trusted.
In SAS 9.4M1 and SAS 9.4M2, the default value of SSLCALISTLOC is set to SAS-configuration-directory/levn/certs/cacert.pem.
In SAS 9.4M3, the default value of SSLCALISTLOC is set to SASHome/SASSecurityCertificateFramework/1.1/cacerts/trustedcerts.pem.
If the trust list, or Windows certificates stores, does not contain all certificates required to make a TLS connection to the LDAP server, then you must update the existing trust list or certificate store. SAS offers basic instructions in "Installing and Configuring TLS and Certificates" in Encryption in SAS® 9.4.
Product Family | Product | System | SAS Release | |
Reported | Fixed* | |||
SAS System | SAS Integration Technologies | z/OS | 9.1 TS1M3 SP4 | |
Microsoft® Windows® for 64-Bit Itanium-based Systems | 9.1 TS1M3 SP4 | |||
Microsoft Windows Server 2003 Datacenter 64-bit Edition | 9.1 TS1M3 SP4 | |||
Microsoft Windows Server 2003 Enterprise 64-bit Edition | 9.1 TS1M3 SP4 | |||
Microsoft Windows XP 64-bit Edition | 9.1 TS1M3 SP4 | |||
Microsoft Windows 2000 Advanced Server | 9.1 TS1M3 SP4 | |||
Microsoft Windows 2000 Datacenter Server | 9.1 TS1M3 SP4 | |||
Microsoft Windows 2000 Server | 9.1 TS1M3 SP4 | |||
Microsoft Windows 2000 Professional | 9.1 TS1M3 SP4 | |||
Microsoft Windows NT Workstation | 9.1 TS1M3 SP4 | |||
Microsoft Windows Server 2003 Datacenter Edition | 9.1 TS1M3 SP4 | |||
Microsoft Windows Server 2003 Enterprise Edition | 9.1 TS1M3 SP4 | |||
Microsoft Windows Server 2003 Standard Edition | 9.1 TS1M3 SP4 | |||
Microsoft Windows XP Professional | 9.1 TS1M3 SP4 | |||
Windows Vista | 9.1 TS1M3 SP4 | |||
Windows Vista for x64 | 9.1 TS1M3 SP4 | |||
64-bit Enabled AIX | 9.1 TS1M3 SP4 | |||
64-bit Enabled HP-UX | 9.1 TS1M3 SP4 | |||
64-bit Enabled Solaris | 9.1 TS1M3 SP4 | |||
HP-UX IPF | 9.1 TS1M3 SP4 | |||
Linux | 9.1 TS1M3 SP4 | |||
Linux on Itanium | 9.1 TS1M3 SP4 | |||
OpenVMS Alpha | 9.1 TS1M3 SP4 | |||
Solaris for x64 | 9.1 TS1M3 SP4 | |||
Tru64 UNIX | 9.1 TS1M3 SP4 |
Type: | Usage Note |
Priority: |
Date Modified: | 2022-04-15 16:23:20 |
Date Created: | 2010-08-18 15:35:27 |