Connecting to SQL Server

Prerequisites

PuppyGraph version 0.95 or higher.
The SQL Server instance is accessible over the network from the PuppyGraph instance.

Overview

PuppyGraph supports connecting to SQL Server with different authentication methods:

Connecting with username and password
Connecting with Azure AD Service Principal
Connecting with Kerberos / Windows Authentication (on-premises Active Directory, requires PuppyGraph 1.0 or higher)

Connecting with username and password

Configuration	Explanation
Username	The username used to connect to the SQL Server database.
Password	The password associated with the database user account.
JDBC URI	A JDBC-compatible connection string for the SQL Server instance. See Building the Connection URL for syntax details.
JDBC Driver Class	The class name of the SQL Server JDBC driver. Default: `com.microsoft.sqlserver.jdbc.SQLServerDriver`.
JDBC Driver URL	The URL of the SQL Server JDBC driver. Choose the version compatible with your SQL Server instance.

Connecting with Kerberos / Windows Authentication

Kerberos / Windows Authentication lets PuppyGraph connect to on-premises SQL Server instances joined to an Active Directory domain. No password is stored in the catalog configuration or transmitted over the wire. Authentication is handled entirely by a service principal and keytab mounted into the PuppyGraph container.

Additional prerequisites:

PuppyGraph version 1.0 or higher.
A Kerberos-enabled Active Directory domain with a service principal and keytab for PuppyGraph.
SQL Server configured to accept Windows Authentication (Integrated Security).

Operator setup

Three files must be present inside the PuppyGraph container before the catalog is created. These are typically mounted via Kubernetes ConfigMaps and Secrets.

File	Typical path	What it contains
Kerberos config	`/etc/puppygraph/krb5.conf`	Realm and KDC settings
Keytab	`/secrets/puppygraph.keytab`	Service principal credentials
JAAS config	`/etc/puppygraph/jaas.conf`	Login module configuration pointing to the keytab

Three environment variables wire the mounted files into the JVM:

Environment variable	Effect
`AUTHENTICATION_KERBEROS_CONFIGPATH`	Sets `-Djava.security.krb5.conf`
`AUTHENTICATION_KERBEROS_JAASCONFIGPATH`	Sets `-Djava.security.auth.login.config`
`AUTHENTICATION_KERBEROS_DEBUG` (optional)	Set to `true` to enable Kerberos debug logging (`-Dsun.security.krb5.debug=true`). Only set this when troubleshooting authentication issues.

Sample krb5.conf:

[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_kdc = false
    dns_lookup_realm = false
    rdns = false
    udp_preference_limit = 1

[realms]
    EXAMPLE.COM = {
        kdc = kdc.example.com
        admin_server = kdc.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

Sample jaas.conf:

SQLJDBCDriver {
  com.sun.security.auth.module.Krb5LoginModule required
  useKeyTab=true
  keyTab="/secrets/puppygraph.keytab"
  principal="puppygraph_reader@EXAMPLE.COM"
  storeKey=true
  refreshKrb5Config=true
  doNotPrompt=true;
};

Configuration

Configuration	Explanation
SQL Server Auth Type	Kerberos / Windows Authentication (on-prem AD)
JDBC URI	A JDBC connection string for the SQL Server instance, for example: `jdbc:sqlserver://dbhost.example.com:1433;databaseName=mydb;encrypt=true;`. PuppyGraph automatically appends `integratedSecurity=true;authenticationScheme=JavaKerberos;`. Do not include these manually.
Server SPN Override	The Service Principal Name registered in Active Directory for this SQL Server instance. Providing this value is recommended. When connecting to multiple SQL Server instances, each instance must have a distinct SPN configured, making this field mandatory.
JDBC Driver Class	The class name of the SQL Server JDBC driver. Default: `com.microsoft.sqlserver.jdbc.SQLServerDriver`.
JDBC Driver URL	The URL of the SQL Server JDBC driver. Choose the version compatible with your SQL Server instance.

Username and password are not required and will be ignored when Kerberos authentication is selected.

Demo

See Querying SQL Server Data as a Graph for a complete demo. The demo includes setting up the connection to a SQL Server instance.