How to Configure Integrated Windows Authentication

Overview

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 is not selected by a client, IWA is not used for that client.
  • Server participation in IWA is affected by invocation commands. For example, to use IWA, the metadata server and object spawner start commands must include the option -sspi.
    Note: This is the default on Windows and UNIX
  • For metadata-aware connections to a workspace server, participation in IWA is also affected by settings in that server's metadata definition.

Instructions

  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 software. For the first maintenance release for SAS 9.4, the only supported implementation of IWA on UNIX requires Quest Authentication Services (QAS) 4.0.1.23 or later. For the second maintenance release for SAS 9.4 on Linux systems and the fourth maintenance release for SAS 9.4 on Solaris systems, any shared library (including QAS) that implements the GSSAPI with Kerberos 5 extensions can be used. If QAS is present on the host, SAS attempts to load its libraries before attempting to load others to retain legacy behavior.
      Note: In a single deployment, do not use Quest with other shared libraries.
    • You must create a service account and corresponding keytab file. Participating SAS processes on UNIX must be able to read the keytab file. A keytab file is functionally equivalent to a user's password and should be secured in the same way. The keytab file should be owned by the user and group that is accessing it, and it should have the least permissive access mask (preferably 0600).
    • 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. If the metadata server is clustered and runs on Windows, or if your SAS servers are configured using DNS aliases, manually register SPNs. See Manual Registration.
  3. Verify an IWA connection to the metadata server.
    1. In a client-side connection profile, select the check box that enables Integrated Windows authentication and then attempt to connect.
      Tip
      For example, in the Connection Profile dialog box in SAS Management Console, click Edit. On the Connection Information page of the Edit Connection Profile wizard, select the Use Integrated Windows authentication (single sign-on) check box.
    2. 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 User Logins.
      • You are using a Windows desktop client (the SAS implementation of IWA is not for web applications or UNIX clients).
      • If the metadata server runs on UNIX, the prerequisite steps have been successfully completed. (See step 1 above.)
    3. 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.
      Tip
      In SAS Management Console, you can clear the credentials cache by selecting Filethen selectClear Credentials Cache from the main menu.
  4. 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 User Logins.
      • 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.
  5. If the workspace server needs to access Kerberized network resources (such as network file systems 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 to all services. See Windows Privileges.
  6. Inform users that they can select the IWA option 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 should not make changes to the advanced IWA settings in their client-side connection profiles.

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

User Logins

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, cannot 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 do not 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).

Registering SPNs

Automatic Registration

In a standard configuration on Windows, you do not manually register service principal names (SPNs). Instead, each participating SAS server uses the local system account under which it runs to self-register two SPNs against the computer object of the machine where it runs. These Active Directory registrations are in the format SAS/fully-qualified-machine-name and SAS/netbios-machine-name (for example, SAS/machineA.company.com and SAS/machineA).
In a standard configuration on Windows, clients can construct a standard SPN (because they know the format and the target machine), so users do not have to supply an SPN when they initiate an IWA connection.

Manual Registration

In circumstances such as the following, manual registration of SPNs is necessary in order to support Kerberos connections:
CAUTION:
SPNs must be unique among the objects that are in the same Active Directory forest.
A given SPN must not be assigned to more than one object. If a duplicate SPN is found in response to a TGS request, the Key Distribution Center sends an error to the client that the principal was not found.
To manually register an SPN, use the Microsoft tool setspn. For example, the following command registers customValue as the SPN for all servers that run as services under the local system account on a machine that is named myServer:
setspn -A customValue myServer
Note: You must be a Windows domain administrator in order to use the setspn command.
Note: You must also make any necessary adjustments to client-side connection profiles (and the logical workspace server definition, if applicable). For example, if you supplied a custom value for the SPN, specify the new customValue in the Service principal name fields.
UNIX Specifics: On UNIX, the SPNs that are 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.

Manually Registering Object Spawner SPNs

Note: The following manual registration is required only on Windows systems. It does not have to be completed on UNIX systems.
By default, the SAS Object Spawner service runs as a local system. The best practice is to set this service to run under a service level account. Although the account must be an administrator, it allows system administrators to allow delegation to a single account rather than the whole computer if, delegation must be set to allow access to third-party resources (such as SQL and network shares).
When using a service level account to run the object spawner service in a SAS Grid environment, you need to configure the default SPNs:
setspn –A SAS/computerNetbios –u domain\ObjectSpawnerServiceAccount
setspn –A SAS/computerFullname –u domain\ObjectSpawnerServiceAccount
In non-grid environments, you can configure custom SPNs, such as the following:
setspn –A SASWS/computerNetbios –u domain\ObjectSpawnerServiceAccount
setspn –A SASWS/computerShortname –u domain\ObjectSpawnerServiceAccount
Note: The preceding SPN statements differ from the one that is built if you use the local system.

Manually Registering SQL SPNs

When registering a SQL Server database to use IWA, additional configuration steps are needed. The following scenarios provide information about possible configurations.
In the first scenario, the SQL Server service runs under a service account and SQL Server service is not on the same machine as the object spawner service. For this scenario, follow these steps:
  1. To register custom SPNs for the service, run the following commands:
    setspn –A MSSQLSVC/computerNetboisName: sqlPort –u domain\sqlServiceAccount 
    setspn –A MSSQLSVC/fullyQualifiedDomainName: port –u domain\sqlServiceAccount
    setspn –A MSSQLSVC/machineName: sqlInstance –u domain\sqlServiceAccount
    Create the SPNs for each DNS alias, if any are being used.
  2. Run the setspn –x command to verify that no duplicate SPNs exist.
  3. Verify that the SQL Server is accepting Kerberos connections. Run the following command from the SQL Management Studio on the computer where the object spawner service runs:
    SELECT auth_scheme FROM sys.dm_exec_connections WHERE session_id = @@spid;  
    If the query does not return KERBEROS, the SPNs might not be created correctly, or there might be other issues, such as port 88 (the Kerberos ticketing service) is blocked.
  4. Create an ODBC connection on the same machine where the spawner resides, by completing the following steps:
    1. From the Windows Start menu, select Control Panelthen selectAdministrative Toolsthen selectData Sources (ODBC). The ODBC Data Source Administrator dialog box is displayed.
    2. Select the System DSN tab and click Add.
    3. Use the Create New Data Source wizard to configure the connection.
In the second scenario, the SQL Server service runs under a service account and is on the same machine as the object spawner service. In this scenario, since both services reside on the same machine, no delegation is required for the object spawner to access the SQL Service.
Note: You need to configure delegation if the object spawner needs to delegate credentials across the network, for example, to access a network share.
In the third scenario, the SQL Server service runs under a local system account and is on the same machine as the object spawner service. This configuration is not a best practice and is therefore not supported by Microsoft. If a custom SPN for the SQL Server service account is required or preferred, the Microsoft SQL Server 2012 Native Client needs to be installed and configured.

Forcing Kerberos

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, follow these instructions. These instructions assume that you have already fully configured IWA.
Note: You cannot use Windows local accounts with this configuration, because those accounts cannot 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. Restart the metadata server.
  3. 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: On Windows systems, if the workspace server accesses network resources (such as network filesystems or IWA connections to databases), you must also mark the account under which the spawner runs as trusted for delegation to all services. See Windows Privileges.
    Note: On UNIX systems, the account that the SAS SPN is registered against must be trusted for delegation in Active Directory.
  4. Restart the object spawner.
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.
UNIX Specifics: It is not necessary to force use of Kerberos on UNIX, because IWA on UNIX supports only the Kerberos protocol.

Supported Protocols

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 do not 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.

IWA to an 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).

IWA to a Clustered Metadata Server

Introduction

A clustered metadata server on Windows runs under a domain account. No local system account is available to perform the usual self-registration of SPNs. Instead, you must manually register SPNs for all of the host machines in the cluster.

Example

For a metadata server that runs as sasmeta@company.com on three dedicated machines (machineA, machineB, and machineC), you might register the following SPNs:
  • SAS/machineA.company.com
  • SAS/machineA
  • SAS/machineB.company.com
  • SAS/machineB
  • SAS/machineC.company.com
  • SAS/machineC
In this example, the SPNs are registered against the Active Directory principal that corresponds to the sasmeta@company.com account. See Manual Registration.

Shared Hardware

If other SAS servers that run as services share any of the clustered metadata server’s hardware, Active Directory conflicts can occur, because one SPN cannot be associated with two Active Directory identities.
You can work around such conflicts by using either of the following methods:
  • Reconfigure the other servers to run under the metadata server’s domain account (instead of running under the local system account).
    Note: If you make this adjustment to the object spawner, the domain account must be a Windows administrator on the spawner's host and must have the Windows user rights Adjust memory quotas for a process and Replace a process level token. These user rights assignments are part of the local security policy for the Windows computer that hosts the spawner.
  • Adjust the configuration to reference the domain account’s user principal name (UPN). For example, if the metadata server runs as sasmeta@company.com, and the UPN that is registered in Active Directory for that account is sasmeta@company.com, then users should enter the value sasmeta@company.com in the Service principal name (SPN) field of the IWA Advanced Settings dialog box in their client-side connection profiles.
    advanced settings dialog box

IWA to Servers That Use DNS Aliases

To support Kerberos connections to a server that uses a DNS alias, manually register SPNs that reference the alias (instead of referencing the machine name).
For example, for a metadata server on Windows that runs under the local system account and uses the alias DNSalias, you might register the following custom SPNs.
  • SAS/DNSalias
  • SAS/DNSalias.company.com
In this example, the SPNs are registered against the Active Directory computer object that corresponds to the machine on which the metadata server runs. See Manual Registration.

About IWA from SAS Web Applications

The SAS implementation of IWA is for desktop applications only. Web applications can use IWA if they are configured for web authentication and the web application server supports IWA. See SAS Intelligence Platform: Middle-Tier Administration Guide.