SAS User Management Customization - Windows

Install the User Management Customization archive (saswfs.zip) into the wfs-4.0.48 directory. (Click on the "Install" reference for this particular platform in the installation utility. The installation utility will unzip the archive to the chosen location). Once the archive has been unzipped, continue with the installation. From a command prompt positioned to this location (eg. c:\xythos\wfs-4.0.48), use the WFSInstaller command to complete the installation.

This examples assumes a SAS Metadata Server is running on machine example.org at port 8561 and the repository to be used is called "Foundation". This example also assumes that the SAS Metadata Server and Xythos WebDAV server are associated with the same authentication domain, DefaultAuth. This utility will also create a new install service command called saswfs_install_service.

The User Management Customization requires the use of the SAS Unrestricted user to be able to search for users by userid (as part of the Login associated with the Person). There might also be a requirement to use the SAS Trusted User in some scenarios (see Logins with passwords section in Defining User/Login Information in the Metadata Server)

User directories

For best performance, there should not be too many top-level directories in a Xythos WFS system. This means that if the root is being used as the base, you will want to create the user areas below this location in their own directory. You might want to do this whether the root is being used as a base or not. Note: This directory must be called "Users", if the client is to detect this location automatically.

During the installation below, answer the question about the path to the user area, as follows.
eg.
/sasdav/Usersrecommended if using a base path of /sasdav and want the users defined in in the Users directory below this point
/sasdavyou are using a base path of /sasdav and want the users defined at this location
/Usersrecommended if using the root as a base path and want the users in the Users directory below this point
[blank]you are using the root as a base path and want the users defined at this location [Not recommended]

In all cases make sure the client setting for the base path root matches the value assumed here. The examples above show base path roots of "/sasdav" and "/" - the base path root does not include the "Users" directory.

The installation utility (WFSInstaller2) will attempt to create the user path directory and assign access controls automatically. If this needs to be done manually for some reason, then use the Xythos WFS Admin GUI as follows -

So, both the base path root directory and the user path directory need to have read access (do not include inherit read) for "Users with accounts".

Installation

  1. Stop the Xythos service.
    net stop xythos
     
  2. Start the installation utility
    c:\xythos\wfs-4.0.48> WFSInstaller
    Enter the SAS Metadata Server host name > example.org
    Enter the SAS Metadata Server port > 8561
    Enter the SAS Metadata Server repository name > Foundation
    Enter the SAS Unrestricted User ID to connect to the SAS Metadata Server > sasadm
    Enter the password for SAS Unrestricted User sasadm > password1
    Enter the SAS Trusted User ID to connect to the SAS Metadata Server > sastrust
    Enter the password for SAS Trusted User sastrust > password2
    Enter the authentication domain for the SAS Metadata Server > DefaultAuth
    Enter the authentication domain for the Xythos WFS WebDAV Server > DefaultAuth
    Enter the path to the user area > /sasdav/Users
    Service debug on [Y/N]? > n

    Reading Xythos properties...
    Updating the Xythos install_service utility...
    Creating WFSInstaller2...
    Done.

     
  3. Now run the second installer(created in step 2 above).
    c:\xythos\wfs-4.0.48> WFSInstaller2
    User path /sasdav/Users created.
    HTTP_SESSION_LIFECYCLE_CLASS
    Current value: com.xythos.security.api.SessionManagerBase
    New value: com.sas.wfs.SASSessionManager
    USER_LIFECYCLE_CLASS
    Current value: com.xythos.security.DefaultPrincipalManager
    New value: com.sas.wfs.SASPrincipalManager
    Changes committed.
    Done. c:\xythos\wfs-4.0.48>

     
  4. Remove the old service definition, add the new definition and restart the Xythos service.
    c:\xythos\appserver-4.0.48\bin> remove_service
    c:\xythos\appserver-4.0.48\bin> saswfs_install_service
    c:\xythos\appserver-4.0.48\bin> net start xythos

If you are not running Xythos as a Windows service (i.e., running the startup command file), then you must set the CATALINA_OPTS environment variable to set the location of the saswfs properties file. For example

CATALINA_OPTS=-Dcom.sas.wfs.propertyfile.location=C:\Xythos\wfs-4.0.48\saswfs.properties

A section of startup.bat shows an example of setting this option

: catalina.bat resets both of these variables.
: They are only used here to call the correct catalina.bat.
set _CATALINA_HOME=%CATALINA_HOME%
set WFS_INSTALL=C:\xythos4.0.48.15
set CATALINA_HOME=%WFS_INSTALL%\appserver-4.0.48
set CATALINA_OPTS=-Dcom.sas.wfs.propertyfile.location=c:\xythos\wfs-4.0.48\saswfs.properties
...

Due to licensing restrictions, installation of the SAS User Management Customization will disable the Xythos WFS Web UI. Access to http://server:port/ from a Web browser will result in the following message if the user management extension is installed correctly - "The custom user model does not support this function". WebDAV clients and Windows Webfolders will still be able to access the server at http://server:port/.

Users defined in the SAS Metadata server will now be valid users for this WebDAV server.

Administration of the server is done using the Xythos WFS Admin GUI (http://server:port/xythosadmin). See Implementing Authentication and Authorization for the Xythos WFS WebDAV Server in the documentation for examples.

Defining User/Login Information in the Metadata Server

Certain user and login information must exist in the metadata server for the user management extension to work. How much information depends on how the client is connecting to the DAV server. There are two basic configurations - users defined with login information and users defined without login information (ie. host authentication).

Logins without passwords

The authentication mechanisms that do pass the user's password to the server allow one to use Login entries for host or trusted authentication, whether a password is specified in the metadata or not. An example of this is BASIC authentication (with or without using SSL) when the Metadata server and the WebDAV server are in the same authentication domain. If using BASIC authentication, then SSL is recommended.


Note: The user management extension sets the server to use BASIC authentication when the "Digest and Basic" option is set in the Administrator panels, so that clients can exploit the configuration described here. If one wants to use DIGEST authentication then choose the "Digest only" option instead. To return XythosWFS behaviour to the default (support both Basic and Digest), set com.sas.wfs.basic.only to false in the saswfs.properties file.

Logins with passwords

Some authentication mechanisms do not transfer the user password between the client and server. An example here is DIGEST authentication where a one way hash of the user's password is passed from the client to the server. For these authentication schemes, the password must be available on the server side and this is specified in the Login associated with the user in the metadata server. This needs to be done for all users that may be authenticated using these schemes, such as DIGEST authentication (with or without using SSL). In addition, even when using BASIC authentication, this method is used when setting the Metadata Server and the WebDAV server to be in different authentication domains.

In order for the User Management customization to obtain passwords from Logins defined in the SAS Metadata Server it is necessary to provide the credentials for the SAS Trusted User during installation. If this mode is not required then there is no need to provide the information for the SAS Trusted User.


Re-initializing Xythos

If there is a problem bringing up Xythos after these changes, one way of getting back to a working system is to re-initialize Xythos. This can be done by running the Xythos installation application. Choose [1] - Full Install and when prompted enter the same values as during the installation. Since this is initilializing an existing configuration, you will be prompted with the following:

This schema is already in use. Would you like to overwrite the existing objects in this schema Y/N? Warning: you should only choose Y (Yes) if this is a restart of a failed install. Yes should never be specified if this schema has already been used as it will result in the loss of all existing data in the schema. [N]:

Choose Y for both the xythos and files databases and then say No [N] to updating the application server (since this has already been done). Xythos should come up clean as a new installation. You will need to install the SAS Custom Extensions on top of the new initialized server.