add Kerberos auth #35
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -28,6 +28,7 @@ Other supported formats are listed below. | |
| * `false` - Data sent between client and server is not encrypted beyond the login packet. (Default) | ||
| * `true` - Data sent between client and server is encrypted. | ||
| * `app name` - The application name (default is go-mssqldb) | ||
| * `authenticator` - Can be used to specify use of a registered authentication provider. (e.g. ntlm, winsspi (on windows) or krb5 (on linux)) | ||
|
|
||
| ### Connection parameters for ODBC and ADO style connection strings | ||
|
|
||
|
|
@@ -59,6 +60,32 @@ Other supported formats are listed below. | |
| * `Workstation ID` - The workstation name (default is the host name) | ||
| * `ApplicationIntent` - Can be given the value `ReadOnly` to initiate a read-only connection to an Availability Group listener. The `database` must be specified when connecting with `Application Intent` set to `ReadOnly`. | ||
|
|
||
| ### Kerberos Active Directory authentication outside Windows | ||
| The package supports authentication via 3 methods. | ||
|
There was a problem hiding this comment. what's the default approach used if the connection string doesn't specify one explicitly? If a keytab file exists in some default location will it be used without having to specify it in the connection string? There was a problem hiding this comment. @shueybubbles as of now, no. The user needs to explicitly specify the locations for keytab/cache. A default location can be added. Should we? Refer this comment There was a problem hiding this comment. the MIT doc itself says to put it in /etc by default, or set environment variable KRB5_CONFIG. Couldn't we just rely on those too? I'm a bit surprised the jcmturner/gokrb5 module isn't already doing that There was a problem hiding this comment. I'd expect someone to be able to set the kerberos environment variables https://web.mit.edu/kerberos/krb5-1.12/doc/admin/env_variables.html and not have to put them all explicitly in the connection string here. There was a problem hiding this comment. I read https://github.com/jcmturner/gokrb5/blob/master/config/krb5conf.go and have a recommendation for a fallback model for the kr5b.conf file location.
If the user doesn't specify paths to keytab or cache, they probably can rely on the defaults defined in krb5.conf. Does this seem reasonable? There was a problem hiding this comment. @shueybubbles yes, it does. will make the changes. There was a problem hiding this comment. thx I think trying to follow the MIT spec will help developers. If |
||
|
|
||
| * Keytabs - Specify the username, keytab file, the krb5.conf file, and realm. | ||
|
|
||
| authenticator=krb5;server=DatabaseServerName;database=DBName;user id=MyUserName;realm=domain.com;krb5conffile=/etc/krb5.conf;keytabfile=~/MyUserName.keytab | ||
|
|
||
| * Credential Cache - Specify the krb5.conf file path and credential cache file path. | ||
|
|
||
| authenticator=krb5;server=DatabaseServerName;database=DBName;krb5conffile=/etc/krb5.conf;krbcache=~/MyUserNameCachedCreds | ||
|
|
||
| * Raw credentials - Specity krb5.confg, Username, Password and Realm. | ||
|
|
||
| authenticator=krb5;server=DatabaseServerName;database=DBName;user id=MyUserName;password=foo;realm=comani.com;krb5conffile=/etc/krb5.conf; | ||
|
|
||
| ### Kerberos Parameters | ||
|
|
||
| * `authenticator` - set this to `krb5` to enable kerberos authentication. If this is not present, the default provider would be `ntlm` for unix and `winsspi` for windows. | ||
| * `krb5conffile` (mandatory) - path to kerberos configuration file. | ||
| * `realm` (required with keytab and raw credentials) - Domain name for kerberos authentication. | ||
| * `keytabfile` - path to Keytab file. | ||
| * `krbcache` - path to Credential cache. | ||
| * For further information on usage: | ||
| * <https://web.mit.edu/kerberos/krb5-1.12/doc/admin/conf_files/krb5_conf.html> | ||
| * <https://web.mit.edu/kerberos/krb5-1.12/doc/basic/index.html> | ||
|
|
||
| ### The connection string can be specified in one of three formats | ||
|
|
||
| 1. URL: with `sqlserver` scheme. username and password appears before the host. Any instance appears as | ||
|
|
@@ -88,11 +115,17 @@ Other supported formats are listed below. | |
|
|
||
| ``` | ||
|
|
||
| * `sqlserver://username@host/instance?krb5conffile=path/to/file&krbcache=/path/to/cache` | ||
| * `sqlserver://username@host/instance?krb5conffile=path/to/file&realm=domain.com&keytabfile=/path/to/keytabfile` | ||
|
|
||
| 2. ADO: `key=value` pairs separated by `;`. Values may not contain `;`, leading and trailing whitespace is ignored. | ||
| Examples: | ||
|
|
||
| * `server=localhost\\SQLExpress;user id=sa;database=master;app name=MyAppName` | ||
| * `server=localhost;user id=sa;database=master;app name=MyAppName` | ||
| * `server=localhost;user id=sa;database=master;app name=MyAppName;krb5conffile=path/to/file;krbcache=path/to/cache;authenticator=krb5` | ||
| * `server=localhost;user id=sa;database=master;app name=MyAppName;krb5conffile=path/to/file;realm=domain.com;keytabfile=path/to/keytabfile;authenticator=krb5` | ||
|
|
||
|
|
||
| ADO strings support synonyms for database, app name, user id, and server | ||
| * server <= addr, address, network address, data source | ||
|
|
@@ -112,6 +145,8 @@ Other supported formats are listed below. | |
| * `odbc:server=localhost;user id=sa;password=foo}bar` // Literal `}`, password is "foo}bar" | ||
| * `odbc:server=localhost;user id=sa;password={foo{bar}` // Literal `{`, password is "foo{bar" | ||
| * `odbc:server=localhost;user id=sa;password={foo}}bar}` // Escaped `} with`}}`, password is "foo}bar" | ||
| * `odbc:server=localhost;user id=sa;database=master;app name=MyAppName;krb5conffile=path/to/file;krbcache=path/to/cache;authenticator=krb5` | ||
| * `odbc:server=localhost;user id=sa;database=master;app name=MyAppName;krb5conffile=path/to/file;realm=domain.com;keytabfile=path/to/keytabfile;authenticator=krb5` | ||
|
|
||
| ### Azure Active Directory authentication | ||
|
|
||
|
|
@@ -322,6 +357,7 @@ db.QueryContext(ctx, `select * from t2 where user_name = @p1;`, mssql.VarChar(na | |
| * Supports Single-Sign-On on Windows | ||
| * Supports connections to AlwaysOn Availability Group listeners, including re-direction to read-only replicas. | ||
| * Supports query notifications | ||
| * Supports Kerberos Authentication | ||
|
|
||
| ## Tests | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
if I don't set a specific authenticator, can the integratedAuth code in the core try to connect using the default provider first, then fall back to any other registered providers ?
This is the scenario:
If my client app imports the krb5 package will the runtime behavior correctly use SSPI on Windows, krb5 in prod, and ntlm in preprod?
If my connection string does have an authenticator tag then I'd expect it to fail to connect if that method isn't available or is mis-configured on the host.
If the connection string doesn't have an authenticator tag, I'd expect to have a predictable behavior based on what is available on the host at runtime and not have to create separate connection strings for every possible environment.