Download: updateMetaDataFromFile.zip

Prerequisites

• Access Manager version must be 4.2 or higher.

• Central Metadata Repository XML file uploaded

• SPs or IDPs using metadata found in the Central Metadata Repository

Similar to this cool solution: Refreshing Metadata using REST API

But this solution does it using a Linux shell script, the new built-in ReST APIs and a metadata repository. The above existing cool solution required installing a jar file, but this new cool solution uses new built-in functionality.

NAM4.2 and previous versions have a Central Metadata Repository where an XML file can be uploaded and the Metadata in the file can be used to create Service Providers (SPs) and Identity Providers (IDPs) and supply the needed metadata for the SPs and IDPs. Reloading the Central Metadata Repository again will update the internal data so that if new SPs and IDPs are created, they will use the new Metadata from the reloaded repository. The already created SPs and IDPs that use the old repository metadata will not be updated to use the new metadata.

The "updateMetaDataFromFile.sh" script fixes the problem by updating each SP and IDP that use the metadata found in the XML metadata file and then causing the IDP Cluster Devices to reload the updated information from the XML metadata found at the URL where the Central Metadata Repository XML was retrieved.

This Bash (Linux Shell) script can be used in a scheduled cron timer to update the SPs and IDPs that use the metadata loaded from the URL so that the SPs and IDPs will be refreshed. In order to use the script in a scheduled timer, the lines that call for user input should probably be removed.

There are some default values that can be changed on lines 18, 20, and 21 or they can just be typed in each time the script is run. If the script were to be run as a scheduled process using cron or some other timer function, it would probably be best to remove the user input lines (60-67) from the script so that no interaction from the user is needed.


Figure 1: default values that should be customized

XMLURL is the URL where the metadata file is located
ADMINCONSOLE_DNS is the DNS name or IP Address of your admin console
ADMINCONSOLE_PORT is the port number of your admin console


Figure 2: User Input lines that should be removed for Cron

The script file generates a log file when it is run that includes the results of all of the ReST calls that were made. Checking the log file and the status of each ReST call will tell which of the SPs and IDPs metadata objects were updated. The log file is called "updateMetaDataFromFile.log"

WARNING: The script does force an update of the IDP Cluster, which will cause a service disruption so it should be run during the maintenance window.

Prerequisites before running the script.

The basic setup is to use a Central Metadata Repository XML file and upload it to NAM4.2. Then assign several service provider and identity providers to be defined using the uploaded Central Metadata Repository. Then the script can be run using the same XML file URL that was used to populate the Central Metadata in NAM. If any of the SPs and IDPs are using any of the Metadata repositories in the URL, those SPs and IDPs metadata will be updated to the new values. The script does not make any comparisons with the old metadata values to see if the metadata values have changed or not, all metadata values are updated.

The script also uses "XMLStarlet" command line tool to process XML documents. This tool must be installed through the Linux "Software Management" tool in order for the script to work. If you have problems running the script, make sure this RPM module is installed.

NOTE: running the script does not update/refresh the NAM4.2 Central Metadata associated with the XML file URL. If the Central Metadata is not updated or reloaded with the new changes, any newly created Service Providers and Identity Providers created from the central metadata will not have the correct metadata, but as soon as the script is run, the metadata will be corrected.

WARNING: The metadata file has a "validUntil" tag, but this script doesn't look at that date. If the XML file that is downloaded from the URL is not valid, the script does not care and the update will still happen to each SP and IDP that is using the metadata.

Running the script from the command line

I usually run the script as follows, passing the username and password in on the command line. The username must be an admin username. It cannot be a delegated admin user.

./updateMetaDataFromFile.sh -u cn=admin,o=novell -p novell

What the script does

The script has a new function for each of the ReST API calls. The main body of the script will do the following things:

1.	Get all of the IDPClusters
Uses the new ReST call to get the IDP Clusters
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/idpclusters
2.	For Each IDP Cluster, do the following
3.	Get the Service Provider List for the IDP Cluster
Uses the new ReST call to get the Service Provider list for the IDP Cluster
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/idpclusters/$CLUSTER_ID/serviceproviders
4.    For each SP in the list, do the following
5.      Get the EntityID for the SP
6.      Scan the MetaData XML for the matching EntityID
7.       If found, URL Encode the Metadata and update the IDP Metadata, write to the log file
	Uses the new ReST call to update the SP Metadata
	https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/idpclusters/$CLUSTER_ID/identityproviders/$SERVICE_ID/metadata
          If not found, write a "not found" message to the log file.
8.      Repeat for all SPs in the list
9.    Get the Identity Provider List for the IDP Cluster
Uses the new ReST call to get the Identity Provider list for the IDP Cluster
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/idpclusters/$CLUSTER_ID/identityproviders
10.   For each IDP in the list, do the following
11.     Get the EntityID for the IDP
12.     Scan the MetaData XML for the matching EntityID
13.       If found, URL Encode the Metadata and update the IDP Metadata, write to the log file
Uses the new ReST call to update the IDP Metadata
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/idpclusters/$CLUSTER_ID/identityproviders/$SERVICE_ID/metadata
          If not found, write a "not found" message to the log file.
14.     Repeat for all IDPs in the list
15.  If any SP or IDP metadata was updated, cause UPDATE ALL message to be sent to notify each IDP devices of the metadata change
	Uses the new ReST call to force the IDP Clusters to update local cached data
	https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/idpclusters/$CLUSTER_ID
16.  Loop to the next IDP Cluster

Success or failure found in the log file

View the log file "updateMetaDataFromFile.log" to see details about which service providers and identity providers were updated.

The ReST calls in the script use the enhanced trace logging provided by the Jersey Rest system. If developing your own ReST calls into the system, using the "X-Jersey-Tracing-Accept :whatever" and "X-Jersey-Tracing-Threshold:TRACE" headers can help diagnose path problems. You can follow the URL path matching to see success or where the path matching failed.

Additional scripts

The getStatistics.sh and getHealth.sh scripts can be run to view the statistics and health of the NAM system. Both of these scripts make a single call to the new Admin Console ReST APIs to retrieve data.

The getStatistics.sh will provide a list of different statistics in the NAM system. The admin console's admin username and password can be passed in on the command line as parameters. If they are not passed in, they can be filled in when prompted.

Example:
./getStatistics.sh -u cn=admin,o=novell -p novell

Uses the new ReST call to get the statistics
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/statistics

With the getHealth.sh script, you can get the health of the entire system, the health of the clusters, the health of the devices, and a very detailed list of health messages. The optional "expand" parameter is used as a query parameter to the ReST call to choose how much detail to show. The "expand" parameter is not passed in on the command line, but is a prompted parameter.

The admin console's admin username and password can be passed in on the command line as parameters. If they are not passed in, they can be filled in when prompted.

Example:
./getHealth.sh -u cn=admin,o=novell -p novell

Uses the new ReST call to get the health details
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/health

To get very detailed messages, use the "?expand=3" parameter when making the ReST call.
https://$ADMINCONSOLE_DNS:$ADMINCONSOLE_PORT/amsvc/v1/health?expand=3