* Experimental Software and Documentation *

Updating Passwords in Login Metadata

How the Password Update Utility Works

The SAS Metadata Server stores login metadata to establish a connecting user's identity or to authenticate to other servers. The first type of connection is referred to as an "in-bound login". The second is referred to as an "out-bound login". An in-bound login is a login that is used to determine your metadata identity when you connect to the metadata server. When an authenticated connection is established to the metadata server, the authorization facility queries the metadata server for a Login object that has a matching value in the User ID attribute. If a matching login cannot be found in the metadata, the requesting user is treated as a member of the PUBLIC user group. If a match is found, the server uses the identity object (Person or IdentityGroup) that owns the Login object as the primary identity on which authorization decisions are made. For more information on identity, logins and authentication, see the document on Authentication Overview. An out-bound login is a login that applications can retrieve from a SAS Metadata Server and send to other systems that need to verify a user's identity. Applications use out-bound logins to automate connections to other hosts, servers, and applications. A single login can function as an in-bound and an out-bound login. If a user changes a password on a system and if the login info associated with the system is registered as an out-bound login in the metadata server, then the associated login metadata must be updated on the metadata server, or it will not be able to authenticate to the other system.

SAS provides three tools for updating passwords in login metadata:

SMC
the SAS Personal Login Manager
This password update utility

The SMC is available on most SAS supported platforms and the SAS Personal Login Manager is available only on Windows. For more information, see the help for the products. The password update utility, setPW.jar, is available on a limited basis only. The remainder of this document describes the password update utility.

Installation and Setup

You will need to have java 1.4.1 or higher installed on your system in order to run the password update utility. In addition, you will need the SAS Java Metadata Interface installed.

Install the SAS Java Metadata Interface from the SAS Client-Side Components Volume 1 CD. On Windows XP, it will default to C:\Program Files\SAS\JavaMetadataInterface\9.1 \
Extract the contents of the downloaded file into a temporary directory.
For Windows, the downloaded file is 913passwdsync01wn.zip. Use WinZip to unzip the downloaded file, which will result in the following files being extracted to the temporary directory:
913passwdsync01\setPW.jar
913passwdsync01\setpw.htm

For UNIX, the downloaded file is 913passwdsync01ux.tar. Extract the contents of the downloaded file using the tar command, for example
$> tar -xf $HOME/913passwdsync01ux.tar

where $HOME is the location to where the tar file was downloaded.
The tar command will extract the following files to the directory from where the tar command is executed:
913passwdsync01/setPW.jar
913passwdsync01/setpw.htm
For simplicity, copy the setPW.jar into the directory where the SAS Java Metadata Interface is installed. On Windows XP, the default installation directory directory is C:\Program Files\SAS\JavaMetadataInterface\9.1\. For the time being, the setPW.jar file, javadoc for the class interface as well as this document may have been emailed or sent on CD.

How the Password Update Utility Works

The password update utility replaces the password that is associated with a user ID in a particular authentication domain. It does not extract updated passwords from the source password systems. Nor will it create a new login definition on the metadata server. If a matching user ID and AuthenticationDomain cannot be found on the metadata server, that particular update request will fail. The utility supports both a log file and an error file to capture information about failed requests.

In order for the utility to update the password on a login object, it must be connected to the metadata server as the owner of the login or as an unrestricted user. If you are connecting as an unrestricted user, you may want to use the -ownerName and -ownerType options which verify that the login is owned by the proper identity before updating the password.

Input Requirements

The utility requires that you specify a valid user ID, authentication domain, and a new password for each login to be updated. A user ID and authentication domain are valid if they match a user ID and authentication domain that have already been defined on the metadata server.

The input information can be submitted interactively or programmatically. The utility supports both a command-line interface and a Java class interface. The input information can be supplied in a file, via a pipe, or on the command line.

Input that is supplied in a file or via a pipe must be formatted as follows:

The user ID, authentication domain, and password for each login must be specified on one line, in "keyword=value" pairs that are separated by spaces.

The "keyword=value" pairs must specify a valid keyword. The supported keyword aliases are shown in Table 1.

Table 1. Keyword Aliases
Keyword	Supported Aliases
UserID	UID
AuthDom	AuthenticationDomain, AuthDomain,
Password	PWD, PW
OwnerName (optional)	Owner
OwnerType (optional)

All of the first three keyword pairs are required. If a login is not associated with an authentication domain, you must still include the AuthDom keyword=value pair, and specify an empty string ("") as the AuthDom value.
You may also optionally specify the owning identity's name and/or type. If the OwnerName option is specified and the value does not match the owing identity's name stored in the server, the specified login will not be updated. Similarly if the OwnerType option is specified and the value does not match the owing identity's Type stored in the server, the specified login will not be updated.
Keyword values that contain spaces must be enclosed in double-quotation marks.

The following is an example of a valid input file:

UserID="demotst1"        AuthDom="OracleAuth"  Password= "demotst1password"
UserID="domain\demotst2" AuthDom="DefaultAuth" Password= "demotst2password"
UserID="domain\demotst3" AuthDom="WindowsAuth" Password= "demotst3password" OwnerName="TestID 6" OwnerType=Person
UserID="demotst4"        AuthDom="UnixAuth"    Password= "demotst4password" OwnerName="TestID 4"
UserID="domain\demotst5" AuthDom="DefaultAuth" Password= "demotst5password" OwnerType="IdentityGroup"

Note that the utility is case-insensitive and that the input file can specify a combination of keyword aliases. That is, the utility makes no distinction between "Password", "PaSSword", and "PassWORD", or "AuthDomain" and "AuthDom". The values for the UserID, AuthDom, OwnerName, and OwnerType are also case-insensitive.

Command-Line Interface

The command-line interface supports the following syntax:

java -jar setPW.jar -metaServer "server_name" -metaPort "port_number" 
-metaUser "user_ID" -metaPass "password"  
[-options]

Arguments

-jar setPW.jar

invokes the password update utility.

-metaServer "server_name" -metaPort "port_number" -metaUser "user_ID" -metaPass "password" -metaRepository "repository_name"

specify metadata server connection parameters.

-metaServer host_name: is the host name or IP address of the computer that is hosting the metadata server.
-metaPort port_number: is the port number to which the metadata server is listening for requests.
-metaUser "user_ID": is the user ID of the account that will be used to update the passwords. This account must have access to all logins that will be updated by the tool on this invocation. This must be an unrestricted user if multiple logins owned by multiple people are being updated. Or, it may be an account that maps to the identity owning the logins. For more information about the unrestricted user server privilege, see "Server Administrative Privileges" in the SAS Metadata Server: Setup and Administration Guide.
-metaPass "password": is the connecting user's password.
-metaRepository "repository_name": is the name of the repository that contains the login metadata to be updated. This is optional. If no repository name is specified, it will default to "Foundation". Note: All logins should be created in a Foundation repository. So this option will generally not be needed.

-options

indicate whether input is to be supplied in a file, via a pipe, or on the command line, as well as preferences for log and error message handling.

-file "filename": specified with the name of a file that contains passwords change information. The contents of the file must meet the requirements described in "Input Requirements".
-verbose: enable verbose output such as server connecting/disconnecting information.
-noPrompt: indicates that input will come from a pipe. The login information in the pipe must meet the requirements described in "Input Requirements".
-userID "user_identifier": specifies the user ID of a login that is to be updated. When -userID is used, -authDom and -password must also be used, or setPW will exit with the usage messages.
-authDom "authentication_domain": specifies the authentication domain of the login identified in -userID. If a login does not have an associated authentication domain, use an empty string ("") for the -authDom value, or setPW will exit with the usage messages.
-password "password_value": specifies the new password for the login identified by -userID that is also in the authentication domain identified in -authDom.
-ownerName "name_value": specifies the name of the identity that owns the login. This is optional.

-ownerType "type_value"

specifies the type of the identity that owns the login, either "Person" or "IdentityGroup". This is optional.

-logFile "filename"

specifies the name of an optional log file. If -logFile is omitted, log messages go to standard output.
-errorFile "filename": specifies the name of an optional error file. If -errorFile is omitted, error messages are printed to standard error.

The following table summarizes the command argument(s) associated with each input method.

Input Methods and Corresponding Arguments
Input Method	Arguments
File	-File filename
Pipe	-noPrompt
Command line	-userID user-identifier -authDom authentication-domain -password password-value or -userID id_value -authDom authentication-domain, -password password-value, -ownerName name_value, -ownerType type_value

Examples

The following is an example of a command string that changes a password directly from the command-line:

java -jar setPW.jar -metaServer host_name -metaPort 8561 -metaUser "domain\testid" 
-metaPass "demopwd" -userID "userid1" -authDom "OracleAuth" -password "new_password"

The following is an example of a command string that changes a password directly from the command-line with

the -ownerName and -ownerType options:

java -jar setPW.jar -metaServer host_name -metaPort 8561 -metaUser "domain\testid" 
-metaPass "demopwd"  -userID "userid1" -authDom "OracleAuth" -password "new_password" -ownerName ="Test User" -ownerType="Person"

The following is an example of a command that submits input via a piped input file. This is the piped information:

@echo UserID="domain\demotst1" AuthDom="DefaultAuth" Password="demotst1password"
@echo UserID="demotst2"        AuthDom="Unix"        Password="demotst2password"
@echo UserID="domain\demotst3" AuthDom="WindowsAuth" Password="demotst3password" 
@echo UserID="demotst4"        AuthDom="OracleAuth"  Password="demotst4password" OwnerName=Person
@echo UserID="domain\demotst5" AuthDom="DefaultAuth" Password="demotst5password" OwnerName="DemoTest5" OwnerType=Person

This is the command:

java -jar setPW.jar -metaServer host_name -metaPort 8561 -metaUser "domain\testid" 
-metaPass "demopwd" -noprompt -verbose -logfile "logs\setpw-logfile.log" -errorfile "logs\setpw-errorfile.log"

The example also directs log information to a file named setpw-logfile.log and error information to a file named setpw-errorfile.log. Note that the logs directory must exist prior to running password update utility. The utility will not create the directory for you.

The following is an example of a command that submits input in a file named "password.txt" and directs log information to a file named setpw-logfile.log and error information to a file named setpw-errorfile.log. This is the content of password.txt:

UserID="demotst6"         AuthDom="OracleAuth"    Password="demotst6password"
UserID="demotst7"         AuthDom="OracleAuth"    Password="demotst7password"
UserID="Domain\demotst8"  AuthDom="DefaultAuth"   Password="demotst8password" OwnerType="IdentityGroup"
UserID="domain\demotst9"  AuthDom="WindowsAuth"   Password="demotst9password" OwnerName="Test9" OwnerType="Person"

This is the command:

java -jar setPW.jar -metaServer host_name -metaPort 8561 -metaUser "domain\testid" 
-metaPass "demopw" -file "password.txt" -logfile "logs\setpw-logfile.log" -errorfile "logs\setpw-errorfile.log"

Class Interface

The class com.sas.security.password.util.PasswordUpdater provides a java object interface to update passwords for the logins defined on the SAS Metadata Server. It provides a set of static methods that enable you to:

connect to a SAS Metadata Server
update specified user IDs and authentication domains with specified passwords
disconnect from the metadata server.

The java API documentation for the class com.sas.security.password.util.PasswordUpdater will be included with the software distribution.

The following steps describe what is required to connect to the metadataserver and update passwords.

First, connect to the metadata server using the connectToMetadataServer() method:

String serverName = "MyServer.sas.com";
String serverPort = "8561";
String serverUser = "TestID1";
String serverPass = "testpwd";
String reposName  = "Foundation";
try
{
   // We make our connection
   PasswordUpdater.connectToMetadataServer(serverName,
                                           serverPort, 
                                           serverUser, 
                                           serverPass,
                                           reposName);

}catch (MdException e)
{
    e.printStackTrace();
}

We now have a server connection. We are ready to use the class.

You can use the method updatePassword() to update passwords:

//the user ID of the login whose password is being changed
String userID        = "target_userid"; 
//the authentication domain of the login whose password is being changed
String authDom= "ORACLE";        
//the new password for the given login
String newPassword   = "new_password";  
try
{
 PasswordUpdater.updatePassword(userID, authDom, newPassword);

}catch (MdException e)
{
  e.printStackTrace();
}

or you may optionally specify the owning identity's name and type:

//the user ID of the login whose password is being changed
String userID        = "target_userid"; 
//the authentication domain of the login whose password is being changed
String authDomainName= "ORACLE";        
//the new password for the given login
String newPassword   = "new_password";

//the owning identity's name
String identityName   = "owner name";

//the owning identity's type
String identityType   = "Person";

try
{
 PasswordUpdater.updatePassword(userID, authDomainName, newPassword, identityName, identityType );

}catch (MdException e)
{
  e.printStackTrace();
}

Once you have updated all of your login objects, use the disconnect() method to disconnect from the server:
```
try
{
    PasswordUpdater.disconnect();

}catch (MdException e)
{
    e.printStackTrace();
}
```

Note: When updating passwords for domain-qualified user IDs, make sure the domain is included in the target login and is in the same forms as what is entered in the metadata .

Return Codes

The password update utility sets the following return codes:

0	indicates that the utility completed successfully.
8	indicates that the utility completed with errors.
32	indicates that the utility failed.