Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

krb5 authentication provider #65

Merged
merged 4 commits into from
Mar 13, 2023
Merged

krb5 authentication provider #65

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
49891bb
New krb5 authenticator
PeteBassettBet365 Nov 7, 2022
a7ea017
change the krb-keytabcachefile param name to krb5-credcachefile
PeteBassettBet365 Nov 7, 2022
f210d67
Merge branch 'main' into krb5authenticator
PeteBassettBet365 Mar 9, 2023
e810ff0
update changelog
PeteBassettBet365 Mar 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 36 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,28 +61,50 @@ Other supported formats are listed below.
* `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

To connect with kerberos authentication from a Linux server you can use the optional krb5 package.
Imported krb alongside the main driver
```
package main

import (
...
_ "github.com/microsoft/go-mssqldb"
_ "github.com/microsoft/go-mssqldb/integratedauth/krb5"
)

func main() {
...
}
```

It will become available for use when the connection string parameter "authenticator=krb5" is used.

The package supports authentication via 3 methods.

* 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
authenticator=krb5;server=DatabaseServerName;database=DBName;user id=MyUserName;krb5-realm=domain.com;krb5-configfile=/etc/krb5.conf;krb5-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
authenticator=krb5;server=DatabaseServerName;database=DBName;krb5-configfile=/etc/krb5.conf;krb5-credcachefile=~/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;
authenticator=krb5;server=DatabaseServerName;database=DBName;user id=MyUserName;password=foo;krb5-realm=comani.com;krb5-configfile=/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:
* `krb5-configfile` (mandatory) - path to kerberos configuration file.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

krb5-configfile (mandatory) - path to kerberos configuration file.

please file a followup issue to make these parameters optional. Per the Kerberos specs, there are default locations for these files and those paths can also be overridden by environment variables.
If the krb5 package this driver uses doesn't follow that spec, the driver itself should by looking in the default locations and checking the environment variables.

Also - consider some way to establish a chain of integrated authenticators so the connection string on Windows can be the same connection string on Linux and it will use the most appropriate authenticator .

It seems like it could be reasonably simple to do, since a Windows app would only have the SSPI authenticator registered and a Linux app could have both NTLM and Krb5. The app could set the protocol ordering in the latter case.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi. Just a quick note to say, yes I'll look into it.

* `krb5-realm` (required with keytab and raw credentials) - Domain name for kerberos authentication.
* `krb5-keytabfile` - path to Keytab file.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is it worthwhile to support both the new and old values to avoid the breaking change? This code has been around long enough now that some folks could be using Chandan's strings.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a CHANGELOG.md, please document the fix and the breaking changes there. We're getting some flak from the community now on being better about such documentation per #76

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@PeteBassettBet365 @chandanjainn @LessTravelledWay I would merge this once it includes the CHANGELOG update if the breaking changes are acceptable.

* `krb5-credcachefile` - path to Credential cache.
* `krb5-dnslookupkdc` - Optional parameter in all contexts. Set to lookup KDCs in DNS. Boolean. Default is true.
* `krb5-udppreferencelimit` - Optional parameter in all contexts. 1 means to always use tcp. MIT krb5 has a default value of 1465, and it prevents user setting more than 32700. Integer. Default is 1.

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>

Expand Down Expand Up @@ -115,16 +137,16 @@ The package supports authentication via 3 methods.

```

* `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`
* `sqlserver://username@host/instance?krb5-configfile=path/to/file&krb5-credcachefile=/path/to/cache`
* `sqlserver://username@host/instance?krb5-configfile=path/to/file&krb5-realm=domain.com&krb5-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`
* `server=localhost;user id=sa;database=master;app name=MyAppName;krb5-configfile=path/to/file;krb5-credcachefile=path/to/cache;authenticator=krb5`
* `server=localhost;user id=sa;database=master;app name=MyAppName;krb5-configfile=path/to/file;krb5-realm=domain.com;krb5-keytabfile=path/to/keytabfile;authenticator=krb5`


ADO strings support synonyms for database, app name, user id, and server
Expand All @@ -145,8 +167,8 @@ The package supports authentication via 3 methods.
* `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`
* `odbc:server=localhost;user id=sa;database=master;app name=MyAppName;krb5-configfile=path/to/file;krb5-credcachefile=path/to/cache;authenticator=krb5`
* `odbc:server=localhost;user id=sa;database=master;app name=MyAppName;krb5-configfile=path/to/file;krb5-realm=domain.com;krb5-keytabfile=path/to/keytabfile;authenticator=krb5`

### Azure Active Directory authentication

Expand Down
Loading