How to Configure Integrated Windows Authentication

Overview of Configuring IWA

Note: These instructions are for configuring Integrated Windows authentication (IWA) from SAS desktop applications to the metadata server and the workspace server. Before you configure IWA, verify that this is an appropriate choice in your environment. See Integrated Windows Authentication.
Configuration of IWA for desktop applications can involve three distinct locations:
  • Client participation in IWA is determined by a setting in each client-side connection profile. If IWA isn't selected by a client, IWA isn't used for that client.
  • Server participation in IWA is affected by invocation commands. For example, the metadata server can't use IWA if that server's start command includes the option -nosspi.
  • For metadata-aware connections to a workspace server, participation in IWA is also affected by settings in that server's metadata definition.

Instructions for Configuring IWA

  1. If the metadata server or workspace server runs on UNIX, complete the UNIX prerequisite tasks. Before you can use IWA for a SAS server that runs on a UNIX host, you must prepare and configure the UNIX environment. For example:
    • You must acquire, install, and configure the required third-party software. In the initial release of SAS 9.3, the only supported implementation of IWA on UNIX requires Quest Authentication Services 4.0.1.23 (or later).
    • The UNIX host must join the Active Directory domain and be represented in Active Directory as a computer object.
    • You must create a service account and corresponding keytab file. Participating SAS processes on UNIX must be able to read the keytab file. The keytab file should not be generally available.
    • You must set certain environment variables.
    These prerequisite tasks should be performed during the installation and initial configuration phases of your deployment. Some of the implementation details differ by UNIX host. For these reasons, detailed instructions for preparing your UNIX host to support IWA are in a separate document. See the chapter "Configuring Integrated Windows Authentication" in Configuration Guide for SAS Foundation for UNIX Environments at http://support.sas.com/documentation/installcenter .
  2. Verify an IWA connection to the metadata server.
    1. Open a client-side connection profile in a Windows desktop application.
    2. Select the check box that enables Integrated Windows authentication.
    3. If the connection fails, verify the following:
      • The metadata server's start-up command includes -sspi.
      • The advanced IWA settings in your client-side connection profile are Negotiate for the security package, blank (no value) for the service principal name, and Kerberos,NTLM for the security package list.
      • Your metadata user definition includes a login that contains your user ID in the correct format. See Logins for Users Who Participate in IWA.
      • You are using a Windows desktop client (the SAS implementation of IWA is not for Web applications).
      • If the metadata server runs on UNIX, the prerequisite steps have been successfully completed (see step 1 above).
    4. After the connection succeeds, examine the metadata server log to confirm that an IWA connection was used. If a credential-based connection occurred, make sure that your password is not cached in the client application.
  3. Configure the workspace server’s metadata definition for IWA, and verify an IWA connection to that server.
    Tip
    If you use IWA for the metadata server, there are no cached credentials from an initial logon. For this reason, it is a good idea to configure IWA for the standard workspace server also, if possible (IWA is not supported on z/OS).
    1. On the Plug-ins tab in SAS Management Console, expand Server Manager and the application server icon (for example, SASApp). Right-click the logical server icon (for example, SASApp - Logical Workspace Server) and select Properties.
    2. On the Options tab, select the Host radio button (IWA is a form of host authentication).
      • Select the Negotiate security package.
      • Leave the Security package list as Kerberos,NTLM.
      • Leave the Service principal name blank. In a standard configuration, clients expect (and know how to compose) the default SPN. Entering a value here (or on the client side) overrides this default process.
    3. Log on to SAS Management Console using IWA. Right-click the Logical Workspace Server and select Validate.
    4. If the connection fails, verify the following:
      • The object spawner's start-up command includes -sspi.
      • Your metadata user definition includes a login that contains your user ID in the correct format. See Logins for Users Who Participate in IWA.
      • If the workspace server runs on UNIX, the prerequisite steps have been successfully completed (see step 1 above).
    5. After the connection succeeds, examine the object spawner log to verify that the connection to the workspace server was made using IWA. If the spawner log indicates that credential-based authentication occurred (instead of IWA), the user's context includes credentials for the workspace server's host. Make sure that the user does not have a cached or stored password for the workspace server’s authentication domain.
      Note: Even if IWA is configured, any available cached or stored credentials are preferentially used.
  4. If the workspace server is on Windows and needs to access Windows network resources (such as UNC pathnames or IWA connections to databases):
    • Edit the Security package list so that only Kerberos is specified.
    • In Active Directory, make the object spawner account trusted for delegation. See Windows Privileges.
  5. Notify users that they can select the IWA check box when they log on to desktop applications such as SAS Information Map Studio, SAS Data Integration Studio, SAS OLAP Cube Studio, SAS Management Console, and SAS Enterprise Guide. In general, users shouldn't make changes to the advanced IWA settings in their client-side connection profiles.
Tip
If your SAS servers use DNS aliases, you must manually register those aliases (as both SAS/DNSalias and SAS/DNSalias.fully.qualified) in order to support Kerberos-based IWA connections. See Using Custom SPNs.

See Also

Checking the Status of Servers in SAS Intelligence Platform: System Administration Guide
Default Locations for Server Logs in SAS Intelligence Platform: System Administration Guide
Spawner Invocation Options in SAS Intelligence Platform: Application Server Administration Guide

Logins for Users Who Participate in IWA

If you choose to configure IWA, make sure that user metadata definitions include logins with properly formatted user IDs. The format of the stored user IDs must match the format in which authenticated user IDs are returned to the target server. Failure to meet this requirement causes the user to have only the generic PUBLIC identity (which, by default, can’t even log on to most applications).
In the standard configuration, the appropriate format varies as follows:
  • If the target server is on Windows, the authenticated user ID is returned in qualified format, so the stored user ID should be qualified (for example, WIN\joe or fred.smith@company.com).
  • If the target server is on UNIX, the authenticated user ID is returned in short format (it is not qualified), so the stored user ID should not be qualified (for example, joe or fred.smith).
If you need to align formats, use the SASUSEKERBNAME environment variable. For example, you might use this environment variable in either of the following circumstances:
  • The metadata server is on Windows, the workspace server is on UNIX, both are using IWA, and you don’t want to store two logins for each user.
  • You need to distinguish between two different users, in two different Kerberos realms, who happen to have the same sAMAccountName name (for example, joe@US.COMPANY.COM and joe@EMEA.COMPANY.COM).
See Windows User ID Formats.

Forcing Kerberos (Windows-Only)

If you choose to use the SAS implementation of Integrated Windows authentication (IWA), and you need to ensure that the Kerberos protocol is always used, complete the following instructions. These instructions assume that you have already fully configured IWA.
Note: You can't use Windows local accounts with this configuration, because those accounts can't use Kerberos.
  1. Specify -secpackagelist "Kerberos" in your equivalent of the following locations:
    • SAS\Config\Lev1\SASMeta\MetadataServer\sasv9_usermods.cfg (for the metadata server)
    • SAS\Config\Lev1\SASApp\OLAPServer\sasv9_usermods.cfg (if you need to support direct IWA connections to an OLAP server on Windows)
    • SAS\Config\Lev1\ObjectSpawner\ObjectSpawner.bat (if the object spawner is on Windows). If the spawner runs as a service, complete these steps:
      1. From the Windows Start menu, select Programsthen selectSASthen selectSAS Configurationthen select<Level>then selectObject Spawner – Stop.
      2. From the object spawner's configuration directory, enter the following:
        ObjectSpawner.bat -remove
      3. Add the -secpackagelist "Kerberos" setting to the Set CMD_OPTIONS= line of ObjectSpawner.bat. Also, make sure that the -sspi setting is present.
      4. To reinstall the spawner service, enter the following:
        ObjectSpawner.bat -install
  2. Make sure that the workspace server’s metadata definition includes only Kerberos in the Security package list field. This setting is located in SAS Management Console, on the Plug-ins tab, under Server Manager. The setting is on the Options tab of the logical workspace server definition.
    Note: If the workspace server is on Windows and accesses network resources (such as UNC pathnames or IWA connections to databases), you must also mark the account under which the spawner runs as trusted for delegation. See Windows Privileges.
  3. Restart the metadata server.
Tip
In general, it is not necessary to also change the default IWA setting in client-side connection profiles. If a server accepts only Kerberos, then clients with the default setting of Negotiate (and both Kerberos and NTLM in the security package list) use Kerberos. However, in some circumstances, the client's Windows system chooses to initiate communication using NTLM and is unable to comply with the server requirement by switching to Kerberos. For example, if the client and server are on the same machine, the client chooses NTLM. In these circumstances, you must adjust the client-side settings to specify only Kerberos.
Tip
It is not necessary to force use of Kerberos on UNIX, because IWA on UNIX supports only the Kerberos protocol.

Using Custom SPNs

Note: The most common reason for using a custom SPN is to support SAS servers that use DNS aliases. If your SAS servers are configured using DNS aliases, you must manually register those aliases (as both SAS/DNSalias and SAS/DNSalias.fully.qualified) in order to support Kerberos-based IWA connections.
If you need to use a service principal name (SPN) that differs from the standard generated SPN, review the following information.
In a standard configuration on Windows, SAS servers automatically register their SPN as SAS/machine (for example, SAS/machineA.na.company.com). Clients can construct the default SPN (because they know the format and machine name), so you don't have to explicitly provide the SPN.
If you need to use a custom SPN on Windows:
  1. Use the Microsoft tool setspn. For example: setspn -A customValue myServer. This code registers customValue as the SPN for all servers that run as services under the Local System account on a machine that is named myServer. You must be a Windows domain administrator in order to use the setspn command.
  2. Make sure that all client-side connection profiles and the logical workspace server definition (if applicable) specify the new customValue in the SPN field.
On UNIX, the SPN that is used must be listed in the keytab file. In addition to running setspn to set a custom SPN, and making sure that client connection profiles use that custom SPN, you must generate a new keytab file that includes the new SPN. See the chapter "Configuring Integrated Windows Authentication" in Configuration Guide for SAS Foundation for UNIX Environments at http://support.sas.com/documentation/installcenter .

About IWA to the OLAP Server

In the standard configuration, the OLAP server supports IWA for direct connections (for example, from an open OLAP client that uses an OLE DB Provider for OLAP). This support is similar to the metadata server’s support of IWA for direct connections from SAS desktop clients. In both cases, client-side connection information must request that IWA is used.
Note: In the platform, most connections to the OLAP server are metadata-aware, not direct (the client first connects to the metadata server and then connects to the OLAP server, rather than initially connecting to the OLAP server). Metadata-aware connections to the OLAP server use SAS token authentication (they do not use IWA).

About IWA from Web Applications

The SAS implementation of IWA is for desktop applications only. Web applications (such as SAS Web Report Studio) can use IWA if they are configured for Web authentication and the Web application server supports IWA. See the instructions for your Web application server at support.sas.com/resources/thirdpartysupport.

Reference: Supported Protocols for IWA

IWA requires agreement between client and server about which security protocol to use when exchanging authentication packets. The following table provides details:
Integrated Windows Authentication Settings
Server Setting
Associated Requirements
Negotiate security package
  • The client must select the Negotiate security package.
  • The server must have a security package list. By default, servers have a security package list that offers the Kerberos and NTLM protocols.
  • At least one of the protocols in the server's security package list must be offered by the client.
  • At least one of the protocols that are offered by both parties must actually be supported by both parties. The NTLM protocol is not supported on UNIX.
  • The Kerberos protocol can be used only if the client knows the server's SPN, as explained in the following row.
Kerberos security package
  • The client must select the Kerberos security package.
  • Both client and server must actually support the Kerberos protocol.
  • The client must know the server's service principal name (SPN). In a standard configuration, this is transparent. Clients expect (and know how to construct) a default SPN in the format SAS/machine (for example, SAS/machineA.na.company.com), so you don't have to explicitly provide the SPN.
    Note: For a server on UNIX, the machine value must be specified as a fully qualified domain name (FQDN). For a server on Windows, you can instead specify the machine’s NetBIOS name, but the FQDN is preferred (because a NetBIOS name is not guaranteed to be unique).
NTLM security package
  • The client must select the NTLM security package.
  • Both client and server must actually support the NTLM protocol. The NTLM protocol is not supported on UNIX.