User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Microsoft SQL Server (MSSQL)

Encrypting Network Traffic

Looker strongly recommends encrypting network traffic between the Looker application and your database. Consider one of the options described here.

If you’re interested in using SSL encryption, see the Microsoft documentation.

Configuring Server Authentication

Looker requires “SQL Server Authentication” on your MSSQL server, but server’s can also be configured for “Windows Integrated Authentication” only. That will need to be changed to “Windows Integrated Authentication and SQL Server Authentication”.

If this is not set properly Looker will be unable to connect. This will appear in your SQL Server log messages like: “An attempt to log in using SQL authentication failed. Server is configured for windows authentication only.”

If this change is required you can complete the following steps:

  1. In SQL Server Management Studio Object Explorer, right-click the server, and then click Properties.
  2. On the Security page, under Server authentication, select the new server authentication mode, and then click OK.
  3. In the SQL Server Management Studio dialog box, click OK to acknowledge the requirement to restart SQL Server.
  4. In Object Explorer, right-click your server, and then click Restart. If SQL Server Agent is running, it must also be restarted.

You can read about this more in Microsoft’s documentation.

Creating a Looker User

Looker authenticates to your database using SQL Server Authentication. Using a domain account is not supported.

To create an account, run the following commands. Change some_password_here to a unique, secure password:

CREATE LOGIN looker
  WITH PASSWORD = 'some_password_here';
USE MyDatabase;
CREATE USER looker FOR LOGIN looker;
GO

Granting the Looker User Permission to SELECT from Tables

Looker requires the SELECT permission for each table or schema you will want to query. There are multiple ways to assign SELECT permission:

Granting the Looker User Permission to View and Stop Running Queries

Looker requires rights to detect and stop currently running queries, which requires the following permissions:

To grant these permissions, run the following commands:

USE Master;
GRANT ALTER ANY CONNECTION TO looker;
GRANT VIEW SERVER STATE to looker;
GO

Granting the Looker User Permission to Create Tables

To give the Looker user the permission to create PDTs, issue the following commands:

USE MyDatabase;
GRANT CREATE TABLE to looker;
GO

Temp Schema Setup

To create a schema owned by the Looker user and grant the necessary rights to the Looker user, issue this command:

CREATE SCHEMA looker_scratch AUTHORIZATION looker;

Configuring Kerberos Authentication

If you use Kerberos authentication with your MSSQL database, follow these steps to configure Looker to connect using Kerberos.

The Looker analyst team may need to assist in configuring this correctly.

Setting Up the Kerberos Client Configuration

The first thing to do is to ensure the installation of several pieces of software and the presence of several files on the Looker machine.

Kerberos Client

Verify that the Kerberos client is installed on the Looker machine by running kinit. If the Kerberos client not, install the Kerberos client’s binaries.

For example, on Redhat/CentOS, this would be:

sudo yum install krb5-workstation krb5-libs krb5-auth-dialog

Java 8

Java 8 must be installed on the Looker machine and in the PATH and JAVA_HOME of the Looker user. If necessary, install it locally in the looker directory.

Java Cryptography Extension

  1. Download and install the Java Cryptography Extension (JCE) for Java 8 from this page.

    • Locate the jre/lib/security directory for the Java installation.
    • Remove the following JAR files from this directory: local_policy.jar and US_export_policy.jar.
    • Replace these two files with the JAR files included in the JCE Unlimited Strength Jurisdiction Policy Files download.

    It may be possible to use versions of Java prior to Java 8 with the JCE installed, but this is not recommended.

  2. Update JAVA_HOME and PATH in ~looker/.bash_profile to point to the correct installation of Java and source ~/.bash_profile or log out and in again.

  3. Verify the Java version with java -version.

  4. Verify the JAVA_HOME environment variable with echo $JAVA_HOME.

gss-jaas.conf

Create a gss-jaas.conf file in the looker directory with these contents:

com.sun.security.jgss.initiate {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true
    doNotPrompt=true;
};

If necessary for testing, debug=true can be added to this file like this:

com.sun.security.jgss.initiate {
    com.sun.security.auth.module.Krb5LoginModule required
    useTicketCache=true
    doNotPrompt=true
    debug=true;
};

krb5.conf

The server running Looker should also have a valid krb5.conf file. By default, this file is in /etc/krb5.conf. If it is in another location, that must be indicated in the environment (KRB5_CONFIG in the shell environment).

You may need to copy this from another Kerberos client machine.

lookerstart.cfg

Point to the gss-jaas.conf and krb5.conf files by making a file in the looker directory (the same directory that contains the looker startup script) called lookerstart.cfg that contains the following lines:

JAVAARGS="-Djava.security.auth.login.config=/path/to/gss-jaas.conf -Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.krb5.conf=/etc/krb5.conf" LOOKERARGS=""

If the krb5.conf file is not at /etc/krb5.conf then it will also be necessary to add this variable:

-Djava.security.krb5.conf=/path/to/krb5.conf

For debugging, add these variables:

-Dsun.security.jgss.debug=true -Dsun.security.krb5.debug=true

Then restart Looker with ./looker restart.

Authenticating with Kerberos

User Authentication

  1. If krb5.conf is not in /etc/, then use the environment variable KRB5_CONFIG to indicate its location.

  2. Run the command klist to make sure there is a valid ticket in the Kerberos ticket cache.

  3. If there is no ticket, run kinit username@REALM or kinit username to create the ticket.

  4. The account used with Looker will likely be headless, so you can get a keytab file from Kerberos to store the credential for long-term use. Use a command like kinit -k -t looker_user.keytab username@REALM to get the Kerberos ticket.

Automatically Renewing the Ticket

Set up a cron job that runs every so often to keep an active ticket in the Kerberos ticket cache. How often this should run depends on the configuration of the cluster. klist should give an indication of how soon tickets expire.

Configuring the Looker Connection

Follow the instructions in the Connecting Looker to Your Database documentation page to create a connection to your MSSQL database. In the Additional Params section of the Connection Settings page, add the following:

;integratedSecurity=true;authenticationScheme=JavaKerberos

Some networks are configured for two Kerberos realms, one for Windows Active Directory and the other for Linux and other non-Windows systems. In that case, when the Linux-focused Realm and the Active Directory Realm are configured to trust each other, it is called “cross-realm authentication”.

If your network uses cross-realm authentication, you must explicitly specify the Kerberos principal for MSSQL Server. In the Additional Params field, add the following:

;serverSpn=service_name/FQDN\:PORT@REALM

Replacing FQDN and PORT@REALM with your network information. For example:

;serverSpn=MSSQLSvc/dbserver.internal.example.com:1433@AD.EXAMPLE.COM

In addtion, the Connection Settings page in Looker requires entries in the Username and Password fields, but these are not required for Kerberos. Enter dummy values in these fields.

Test the connection to make sure that it is configured correctly.

Feature Support

Looker’s ability to provide some features depends on whether the database dialect can support them.

In the current Looker release, Microsoft SQL Server supports the following Looker features:

Next Steps

After completing the database configuration, you can connect to the database from Looker using these directions. When you select your dialect, be sure to choose between the 2005 and 2008+ options as appropriate. Microsoft SQL Server versions 2008 and later support additional timeframe features.

Top