Skip to content
A setup utility to help configure the Metacoda Plug-ins Batch Interface
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
ant
src
.gitattributes
.gitignore
LICENSE.txt
README.md
setup.bat
setup.properties
setup.sh
setup.xml

README.md

Metacoda Plug-ins Batch Interface Setup Utility

Intro

This repository provides a utility to help Metacoda customers and partners setup and use the Batch Interface for Metacoda® Security Plug-ins with SAS® software.

It can be used with Metacoda Plug-ins version 6.1 R1 onwards with SAS Software versions 9.2, 9.3, and 9.4.

The Metacoda Plug-ins Batch Interface is used to automate and schedule activities that you might otherwise do manually using Metacoda Plug-ins inside SAS Management Console. This can include:

  • Exporting HTML reports to document a SAS metadata security implementation (ACTs, ACEs, Users, Groups, Roles, Capabilities, Protected Objects, Logins, Internal Logins, Authentication Domains, External Identities)
  • Exporting simple CSV files for ACTs, ACEs, Users, Groups, Roles, Capabilities etc.
  • Exporting Metadata Security Test XML files to use for subsequent security testing
  • Running SAS metadata security implementation, effective permission, and recommended practice tests using the Metacoda Security Testing Framework
  • Populating SAS metadata users, groups, and roles by synchronizing with Microsoft Active Directory using the Metacoda Identity Sync Plug-in

This utility provides an Apache Ant driven setup script to generate site-specific sample scripts that you can use as-is, or as the basis for further customization. You modify some properties files to supply some site and environment specific information, such as SAS metadata server connection details and SMTP server details. The setup script uses those properties files to create tailored copies of the batch interface samples for your SAS environment. Those generated site-specific sample scripts can be moved elsewhere, if required, as they have no further dependency on this setup utility. This means, for example, you can download and run the setup utility on an internet connected machine, and then move the generated scripts onto servers that may have no, or limited, internet connectivity.

Usage

You will need to run this Metacoda Plug-ins Batch Interface Setup Utility on a machine where SAS Management Console has been installed, ideally one with access to the internet. If the machine does not have access to the internet then you can also manually download any required files yourself and place them into the site/downloads directory. In the notes below you will see where any manual downloads may be required.

The site/environment directory structure that is generated by this utility can either be used as-is, or moved onto a different target server where you want to run it. Once generated, the site/environment directory structure is completely stand-alone requiring only a Java Runtime Environment (JRE) to run it.

You can use the generated Metacoda Plug-ins Batch Interface scripts on any machine you like, including the SAS Metadata Server, SAS Mid Tier server, SAS administrator workstation, or even (rarely) a machine that has no SAS software installed. We usually recommend running it on a SAS Mid-Tier server so that the batch scripts can be scheduled, and any generated HTML reports made accessible via the SAS Web Server.

Getting Started

To get started, log onto the machine where you want to run the setup script, choose a target directory, and clone this repository:

ssh sas@sas94m5srv
cd /opt/sas94m6
git clone https://github.com/Metacoda/metacoda-plugins-batch-setup.git
# ... or: git clone git@github.com:Metacoda/metacoda-plugins-batch-setup.git

If you don't have a git client on the machine you can also download a zip file of the repository from GitHub.

Run the setup script without any parameters and it will print some environment info and some help:

cd /opt/sas94m6/metacoda-plugins-batch-setup
./setup.sh

... and for Windows platforms:

cd C:\metacoda-plugins-batch-setup
setup.bat

It will automatically use the system/configured Java Runtime Environment (JRE), so if you want to force the use of a specific JRE then set JAVA_HOME first e.g.

export JAVA_HOME=/opt/sas94m6/sashome/SASPrivateJavaRuntimeEnvironment/9.4/jre
./setup.sh

... and for Windows platforms:

set JAVA_HOME=C:\Program Files\SASHome\SASPrivateJavaRuntimeEnvironment\9.4\jre
setup.bat 

To create customized batch scripts for a SAS environment use the create-env action/target:

./setup.sh create-env

Configuration Properties

The first time you use create-env it will create the following files from templates:

  • site/global.properties
  • site/env-default.properties

... and then abort to allow you to make some required changes.

You can edit one, or both, of the properties files to supply details for your site and SAS environment, and then run the same command again. If you are only configuring it to work with a single SAS environment then you can put all of your settings in the global.properties file. You only need to use the env properties file if you are building for multiple SAS environments (see below for more info).

When editing global.properties, at a minimum, you will need to provide:

  • SAS Home directory location
  • SAS Private Java Runtime Environment (JRE) directory location
  • SAS Versioned Jar Repository (VJR) directory location
  • SAS Management Console directory location
  • SAS Metadata Server host name, port number, and logon details

You may also want to provide SMTP server details if you want the batch interface to be able to send email alerts. See the comments in global.properties for more info.

These are the core settings you will need to review (from a newly created global.properties):

site.global.sashome=/opt/sas94
site.global.jrehome=${site.global.sashome}/SASPrivateJavaRuntimeEnvironment/9.4/jre
site.global.vjrhome=${site.global.sashome}/SASVersionedJarRepository
site.global.mchome=${site.global.sashome}/SASManagementConsole/9.4
site.global.meta.host=localhost
site.global.meta.port=8561
site.global.meta.user=sasadm@saspw
site.global.meta.pass={sas002}ThePwEncodedPassword
site.global.idsync.user=metacodaIdSync
site.global.idsync.pass={sas002}ThePwEncodedPassword
site.global.idsync.logicalWorkspaceServer=SASApp - Logical Workspace Server

You will probably need to change site.global.sashome, site.global.meta.host and, of course, site.global.meta.pass. If you are going to use Metacoda Identity Sync in batch you will also need to change site.global.idsync.user, site.global.idsync.pass, and optionally site.global.idsync.logicalWorkspaceServer.

Metacoda Plug-ins JAR and License

Metacoda Plug-ins software itself is not included in this repository and so you will need to log into support.metacoda.com and download metacoda.plugins.jar placing it in the site/downloads directory.

At the same time save a copy of your metacoda-plugins-v6.lic license file in the site/downloads directory too. This is the license file provided to you by Metacoda when you requested an evaluation or commercial license.

SAS VJRExtract Utility

The setup script will also automatically download a required SAS VJRExtract utility from support.sas.com, save it in the site/downloads directory, and unpack it into the site/VJRExtract directory. This VJRExtract utility is used to extract the pre-requisite SAS JAR files needed to run the Metacoda Plug-ins Batch Interface with your SAS platform installation.

If you are running this setup script on a machine without internet access then you will need to manually download the SAS VJRExtract utility from support.sas.com and save it in the site/downloads directory.

You can download VJRExtract from SAS Usage Note 39911: Copying JAR files from the SAS Versioned Jar Repository to a directory

On the Downloads tab, click the vjrextract.zip link and save the file as fusion_39911_1_vjrextract.zip in the site/downloads directory (which was created the first time you ran setup.sh above).

Building Metacoda Plug-ins Batch Interface Scripts

Once you have the Metacoda Plug-ins JAR and license downloaded (as well as the SAS VJRExtract utility on a machine with no internet access), and updated global.properties with the details of your SAS environment, you can re-run the create-env action/target:

./setup.sh create-env

If all goes well, and you see no errors, then you will have a directory tree of tailored script and configuration files for the Metacoda Plug-ins Batch interface in the directory site/env-default (or another name if you specified an environment name on the command line).

This generated site/env-default can then be moved onto the target server if you are not running this setup script on the target server machine itself.

Running Metacoda Plug-ins Batch Interface Scripts

Once you have your site/env-default generated you can run all of the following sample scripts (none of which make any changes to SAS metadata as supplied):

cd /opt/sas94m6/metacoda-plugins-batch-setup/site/env-default
./run-batch-export-html.sh 
./run-batch-export-csv.sh 
./run-batch-export-sectest.sh
./run-batch-sectest.sh
./run-batch-idsync-ad.sh

... or if you built for a Windows environment:

cd C:\metacoda-plugins-batch-setup\site\env-default
run-batch-export-html.bat 
run-batch-export-csv.bat 
run-batch-export-sectest.bat
run-batch-sectest.bat
run-batch-idsync-ad.bat

The run-batch-export-html.sh/bat script generates a series of SAS Metadata Security HTML reports under the site/env-default/output/html directory.

The run-batch-export-csv.sh/bat script exports a series of simple SAS Metadata Security CSV files under the site/env-default/output/csv directory.

The run-batch-export-sectest.sh/bat script exports a series of Metadata Security Test XML files in the site/env-default/output/sectest directory. These XML files can be used for subsequent metadata security implementation testing of that SAS environment (or others). You may also decide to take those test XML files and edit them for more targeted testing.

The run-batch-sectest.sh/bat script will run a series of sample implementation and recommended practice Metadata Security Test XML files against the SAS environments. The test results will be written to the site/env-default/output/sectest-results directory. You should expect many test failures from these sample tests as the implementation tests may not match your SAS environment, you may not be following all of the recommended practices, and may need to configure additional test exclusions. However, these sample tests can be used as the basis for further customization to meet your own implementation and recommended practice metadata security test regime.

The run-batch-idsync-ad.sh/bat script provides a starting point for running Metacoda Identity Sync in batch using an Identity Sync Profile (.IDSP file) you have previously created and configured using the Metacoda Identity Sync plug-in inside SAS Management Console. As there are many site-specific configuration options for Identity Sync, this setup script does not attempt to support them - that is the job of the Identity Sync Profile Wizard in the interactive Identity Sync plug-in. This setup script just provides a skeleton framework for you to drop in your own IDSP, once you have one that is already working inside SAS Management Console and you now want to schedule.

Batch Identity Sync

There are 3 global/env properties that are specifically for the Identity Sync process:

site.global.idsync.user=metacodaIdSync
site.global.idsync.pass={sas002}ThePwEncodedPassword
site.global.idsync.logicalWorkspaceServer=SASApp - Logical Workspace Server

The first 2 are the SAS Metadata Server and Workspace Server login credentials for the Identity Sync service identity. The last one is the name of the logical SAS Workspace Server to use during Identity Sync processing.

The login credentials are distinct from the site.global.meta properties because you may want, or need, to run the Identity Sync process using a different service identity than the one you use for batch reporting and testing. In order to make changes to SAS identities, the user you specify with site.global.idsync.user or site.env.idsync.user needs to be at least a restricted user administrator (a direct or indirect member of the SAS Metadata Server: User Administration role, as members of the SAS Administrators group usually are). Furthermore, if your sync process needs to make changes to unrestricted users, or identities where access has been limited to unrestricted administrators, then site.global.idsync.user or site.env.idsync.user needs to be a member of the SAS Metadata Server: Unrestricted role. You may want to start running the process as a restricted user admin and switch to an unrestricted administrator only if required. We would also suggest you create a dedicated service identity in SAS to perform the identity sync process, and use an host service account, so that the SAS Workspace Server can be spawned using the same credentials.

After configuring those properties and running the setup script you will have a skeleton structure for running Identity Sync against AD in batch:

cd /opt/sas94m6/metacoda-plugins-batch-setup/site/env-default
./run-batch-idsync-ad.sh

... or if you built for a Windows environment:

cd C:\metacoda-plugins-batch-setup\site\env-default
run-batch-idsync-ad.bat

The run-batch-idsync-ad.sh/bat script is the one you will configure to run in your preferred scheduler. It will use the batch configuration specified in the site/env-default/batch-idsync-ad/idsync-ad.xml file which will in turn run the identity sync process using the site/env-default/batch-idsync-ad/idsync-ad.idsp file. This is the IDSP file that you need to replace with the one you created within SAS Management Console. Rename your IDSP file idsync-ad.idsp and save it in the site/env-default/batch-idsync-ad directory overwriting the sample one that is there.

You will want to review the IDSP, now it is on the server, to ensure that the values are correct in that context. Pay particular attention to the Options tag auditReportFile attribute. The value in your IDSP will probably be valid for your workstation but may not be valid for the server. Unless you have a specific location chosen, change it to "../output/idsync-ad/idsync-ad-audit.html". You may want to configure the SAS Web Server with an alias (preferably secured) to point to this directory so you can access the audit reports using a web browser.

We would strongly advise you set the Options tag applyChanges attribute to false in your IDSP until you have the Identity Sync process running correctly with the audit reports showing only expected changes. You can then change it to true so that changes to SAS metadata start flowing when you next run the run-batch-idsync-ad.sh script.

Working with Multiple SAS Environments

This Metacoda Plug-ins Batch Interface Setup Utility can also be used to create customized batch scripts for multiple SAS environments and so configuration information is split over a global properties file and one or more environment properties files. Each environment can have a name (e.g. lev1, lev2, etc) and if you don't specify a name (as above) it will use the name 'default'.

If you want to build for multiple environments then run the script multiple times, specifying a different environment name for each e.g.

./setup.sh create-env -Dsite.env=lev1
./setup.sh create-env -Dsite.env=lev2

... this will create initial properties files (from templates):

  • site/global.properties
  • site/env-lev1.properties
  • site/env-lev2.properties

... and then later generate customized batch configurations in the directories:

  • site/env-lev1
  • site/env-lev2

You can put any cross-environment settings, that are the same across all environments, in the global.properties and any environment-specific details in the env level properties files.

Uninstall

To uninstall, simply delete the directory into which you cloned this repository, remembering to backup any configuration files or scripts that you may need later.

This utility does not install any files outside of the directory into which you cloned this repository so there is nothing else to uninstall, other than any copies you may have manually made yourself.

Resources

You may find the following resources useful when reviewing this documentation and samples:

License

The setup scripts and samples contained in this repository are licensed under the terms of the Apache License 2.0. See LICENSE.txt for more information.

Metacoda Plug-ins, as required to run any batch scripts generated using this utility, is a commercial product from Metacoda, and must be separately licensed and obtained from Metacoda.

Trademarks

Metacoda® and all other Metacoda product or service names are registered trademarks or trademarks of Metacoda Group Pty Ltd in the USA and other countries.

SAS® and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration.

Other product and company names mentioned herein may be registered trademarks or trademarks of their respective owners.

You can’t perform that action at this time.