Merge 0ce9674 into 1d7a30a

.gitignore

@@ -0,0 +1,5 @@
+.terraform
+*.tfstate*
+*.log
+*.swp
+*~

README.md

@@ -54,10 +54,14 @@ Other supported formats are listed below.
   * true - Server certificate is not checked. Default is true if encrypt is not specified. If trust server certificate is true, driver accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. This should be used only for testing.
 * `certificate` - The file that contains the public key certificate of the CA that signed the SQL Server certificate. The specified certificate overrides the go platform specific CA certificates.
 * `hostNameInCertificate` - Specifies the Common Name (CN) in the server certificate. Default value is the server host.
-* `ServerSPN` - The kerberos SPN (Service Principal Name) for the server. Default is MSSQLSvc/host:port.
+* `ServerSPN` - The Kerberos SPN (Service Principal Name) for the server. Default is MSSQLSvc/host:port.
 * `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`. 
-
+* `FedAuth` - The federated authentication scheme to use.
+  * `ActiveDirectoryApplication` - authenticates using an Azure Active Directory application client ID and client secret or certificate. Set the `user` to `client-ID@tenant-ID` and the `password` to the client secret. If using client certificates, provide the path to the PKCS#12 file containing the certificate and RSA private key in the `ClientCertPath` parameter, and set the `password` to the value needed to open the PKCS#12 file.
+  * `ActiveDirectoryMSI` - authenticates using the managed service identity (MSI) attached to the VM, or a specific user-assigned identity if a client ID is specified in the `user` field.
+  * `ActiveDirectoryPassword` - authenticates an Azure Active Directory user account in the form `[email protected]` with a password. This method is not recommended for general use and does not support multi-factor authentication for accounts.
+
 ### The connection string can be specified in one of three formats:
 
 

appveyor.yml

@@ -30,6 +30,8 @@ install:
   - go version
   - go env
   - go get -u github.com/golang-sql/civil
+  - go get -u golang.org/x/crypto/pkcs12
+  - go get -u github.com/Azure/go-autorest/autorest/adal
 
 build_script:
   - go build

conn_str.go

@@ -1,6 +1,7 @@
 package mssql
 
 import (
+	"errors"
 	"fmt"
 	"net"
 	"net/url"
@@ -13,6 +14,12 @@ import (
 
 const defaultServerPort = 1433
 
+const (
+	fedAuthActiveDirectoryPassword    = "ActiveDirectoryPassword"
+	fedAuthActiveDirectoryMSI         = "ActiveDirectoryMSI"
+	fedAuthActiveDirectoryApplication = "ActiveDirectoryApplication"
+)
+
 type connectParams struct {
 	logFlags                  uint64
 	port                      uint64
@@ -37,6 +44,11 @@ type connectParams struct {
 	failOverPartner           string
 	failOverPort              uint64
 	packetSize                uint16
+	fedAuthLibrary            byte
+	fedAuthADALWorkflow       byte
+	aadTenantID               string
+	aadClientCertPath         string
+	tlsKeyLogFile             string
 }
 
 func parseConnectParams(dsn string) (connectParams, error) {
@@ -229,6 +241,45 @@ func parseConnectParams(dsn string) (connectParams, error) {
 		}
 	}
 
+	p.fedAuthLibrary = fedAuthLibraryReserved
+	fedAuth, ok := params["fedauth"]
+	if ok {
+		switch {
+		case strings.EqualFold(fedAuth, fedAuthActiveDirectoryPassword):
+			p.fedAuthLibrary = fedAuthLibraryADAL
+			p.fedAuthADALWorkflow = fedAuthADALWorkflowPassword
+		case strings.EqualFold(fedAuth, fedAuthActiveDirectoryMSI):
+			p.fedAuthLibrary = fedAuthLibraryADAL
+			p.fedAuthADALWorkflow = fedAuthADALWorkflowMSI
+		case strings.EqualFold(fedAuth, fedAuthActiveDirectoryApplication):
+			p.fedAuthLibrary = fedAuthLibrarySecurityToken
+			p.aadClientCertPath = params["clientcertpath"]
+
+			// Split the user name into client id and tenant id at the @ symbol
+			at := strings.IndexRune(p.user, '@')
+			if at < 1 || at >= (len(p.user)-1) {
+				f := "Expecting user id to be clientID@tenantID: found '%s'"
+				return p, fmt.Errorf(f, p.user)
+			}
+
+			p.aadTenantID = p.user[at+1:]
+			p.user = p.user[0:at]
+		default:
+			f := "Invalid federated authentication type '%s': expected %s, %s or %s"
+			return p, fmt.Errorf(f, fedAuth, fedAuthActiveDirectoryPassword, fedAuthActiveDirectoryMSI, fedAuthActiveDirectoryApplication)
+		}
+
+		if p.disableEncryption {
+			f := "Encryption must not be disabled for federated authentication: encrypt='%s'"
+			return p, fmt.Errorf(f, encrypt)
+		}
+	}
+
+	p.tlsKeyLogFile, ok = params["tls key log file"]
+	if ok && p.tlsKeyLogFile != "" && p.disableEncryption {
+		return p, errors.New("Cannot set tlsKeyLogFile when encryption is disabled")
+	}
+
 	return p, nil
 }
 

doc/how-to-test-azure-ad-authentication.md

@@ -0,0 +1,176 @@
+# How to test Azure AD authentication
+
+To test Azure AD authentication requires an Azure SQL server configured with an
+[Active Directory administrator](https://docs.microsoft.com/en-us/azure/sql-database/sql-database-aad-authentication-configure).
+To test managed identity authentication, an Azure virtual machine configured with
+[system-assigned and/or user-assigned identities](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vm)
+is also required.
+
+The necessary resources can be set up through any means including the
+[Azure Portal](https://portal.azure.com/), the Azure CLI, the Azure PowerShell cmdlets or
+[Terraform](https://terraform.io/). To support these instructions, use the Terraform script at
+[examples/azuread/testing.tf](../examples/azuread/testing.tf).
+
+## Create Azure infrastructure
+
+Download [Terraform](https://terraform.io/) to a location on your PATH.
+
+Log in to Azure using the Azure CLI.
+
+```console
+you@workstation:~$ az login
+you@workstation:~$ az account show
+```
+
+If your Azure account has access to multiple subscriptions, use
+`az account set --subscription <name-or-ID>` to choose the correct one. You will need to have at
+least Contributor access to the portal and permissions in Azure Active Directory to create users
+and grants.
+
+Check out this source repository (if you haven't already), change to the `examples/azuread`
+directory and run Terraform:
+
+```console
+you@workstation:~$ git clone -b azure-auth https://github.com/wrosenuance/go-mssqldb.git
+you@workstation:~$ cd go-mssqldb/examples/azuread
+you@workstation:azuread$ terraform init
+you@workstation:azuread$ terraform apply
+```
+
+This will create an Azure resource group, a SQL server with a database, a virtual machine with a
+system-assigned identity and user-assigned identity. Resources are named based on a random
+prefix: to specify the prefix, use `terraform apply -var prefix=<alphanumeric-and-hyphens-ok>`.
+
+Upon successful completion, Terraform will display some key details of the infrastructure that has
+ been created. This includes the SSH key to access the VM, the administrator account and password
+ for the Azure SQL server, and all the relevant resource names.
+
+Save the settings to a JSON file:
+
+```console
+you@workstation:azuread$ terraform output -json > settings.json
+```
+
+Save the SSH private key to a file:
+
+```console
+you@workstation:azuread$ terraform output vm_user_ssh_private_key > ssh-identity
+```
+
+Copy the `settings.json` to the new VM:
+
+```console
+you@workstation:azuread$ scp -i ssh-identity settings.json "$(terraform output vm_admin_name)@$(terraform output vm_ip_address):"
+```
+
+## Set up Azure Virtual Machine for testing
+
+SSH to the new VM to continue setup:
+
+```console
+you@workstation:azuread$ ssh -i ssh-identity "$(terraform output vm_admin_name)@$(terraform output vm_ip_address)"
+```
+
+Once on the VM, update the system and install some basic packages:
+
+```console
+azureuser@azure-vm:~$ sudo apt update -y
+azureuser@azure-vm:~$ sudo apt upgrade -y
+azureuser@azure-vm:~$ sudo apt install -y git openssl jq build-essential 
+azureuser@azure-vm:~$ sudo snap install go --classic
+```
+
+Install the Azure CLI using the script as shown below, or follow the
+[manual install instructions](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-apt):
+
+```console
+azureuser@azure-vm:~$ curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
+```
+
+## Generate service principal certificate file
+
+Log in to Azure on the VM and set the subscription:
+
+```console
+azureuser@azure-vm:~$ az login
+azureuser@azure-vm:~$ az account set --subscription "$(jq -r '.subscription_id.value' settings.json)"
+```
+
+Use OpenSSL to create a new certificate and key in PEM format, using the :
+
+```console
+azureuser@azure-vm:~$ openssl rand -writerand ~/.rnd
+azureuser@azure-vm:~$ openssl req -x509 -nodes -newkey rsa:4096 -keyout client.key -out client.crt \
+                                    -subj "/C=US/ST=MA/L=Boston/O=Global Security/OU=IT Department/CN=AD-SP"
+azureuser@azure-vm:~$ openssl pkcs12 -export -out client.p12 -inkey client.key -in client.crt \
+                                    -passout "pass:$(jq -r '.app_sp_client_secret.value' settings.json)"
+azureuser@azure-vm:~$ export APP_SP_CLIENT_CERT="$PWD/client.p12"
+```
+
+Use the Azure CLI to add the client certificate to the application service principal:
+
+```console
+azureuser@azure-vm:~$ az ad sp credential reset --append --cert @client.crt \
+                                    --name "$(jq -r '.app_sp_client_id.value' settings.json)"
+```
+
+## Build source code and authorize users in database
+
+Clone this repository, build and run the `examples/azuread` helper that verifies the database
+exists and sets up access for the system-assigned and user-assigned identities.
+
+```console
+azureuser@azure-vm:~$ git clone -b azure-auth https://github.com/wrosenuance/go-mssqldb.git
+azureuser@azure-vm:~$ cd go-mssqldb
+azureuser@azure-vm:go-mssqldb$ go generate ./...
+azureuser@azure-vm:go-mssqldb$ go build -o azuread ./examples/azuread
+azureuser@azure-vm:go-mssqldb$ eval "$(jq -r -f examples/azuread/environment-settings.jq ../settings.json)"
+azureuser@azure-vm:go-mssqldb$ ./azuread -fedauth ActiveDirectoryPassword
+```
+
+For some basic connectivity tests, use the `examples/simple` helper. Run these commands on the
+Azure VM so that identity authentication is possible.
+
+```console
+azureuser@azure-vm:go-mssqldb$ go build -o simple ./examples/simple
+azureuser@azure-vm:go-mssqldb$ jq -r -f examples/azuread/ad-user-password-dsn.jq ../settings.json |
+                               xargs ./simple -debug -dsn 
+azureuser@azure-vm:go-mssqldb$ jq -r -f examples/azuread/ad-service-principal-dsn.jq ../settings.json |
+                               xargs ./simple -debug -dsn 
+azureuser@azure-vm:go-mssqldb$ jq -r -f examples/azuread/ad-system-assigned-id-dsn.jq ../settings.json |
+                               xargs ./simple -debug -dsn 
+azureuser@azure-vm:go-mssqldb$ jq -r -f examples/azuread/ad-user-assigned-id-dsn.jq ../settings.json |
+                               xargs ./simple -debug -dsn 
+```
+
+## Running the integration tests
+
+Now that your environment is configured, you can run `go test`:
+
+```console
+azureuser@azure-vm:go-mssqldb$ export SQLSERVER_DSN="$(jq -r -f examples/azuread/ad-system-assigned-id-dsn.jq ../settings.json)"
+azureuser@azure-vm:go-mssqldb$ go test -coverprofile=coverage.out ./...
+```
+
+## Tear down environment
+
+After you complete your testing, use Terraform to destroy the infrastructure you created.
+
+```console
+you@workstation:azuread$ terraform destroy
+```
+
+## Troubleshooting
+
+After Terraform runs you should be able to see resources that were created in the
+[Azure Portal](https://portal.azure.com/).
+
+If the Azure SQL server is successfully created you can connect to it using the AD admin user
+and password in SSMS. SSMS will prompt you to create firewall rules if they are missing. You
+can read the AD admin user and password from the `settings.json`, or run:
+
+```console
+you@workstation:azuread$ terraform output sql_ad_admin_user
+you@workstation:azuread$ terraform output sql_ad_admin_password
+```
+

examples/azuread/ad-service-principal-dsn.jq

@@ -0,0 +1 @@
+@uri "sqlserver://\(.app_sp_client_id.value)%40\(.tenant_id.value):\(.app_sp_client_secret.value)@\(.sql_server_fqdn.value)?database=\(.sql_database_name.value)&encrypt=true&fedauth=ActiveDirectoryApplication"

examples/azuread/ad-system-assigned-id-dsn.jq

@@ -0,0 +1 @@
+@uri "sqlserver://\(.sql_server_fqdn.value)?database=\(.sql_database_name.value)&encrypt=true&fedauth=ActiveDirectoryMSI"

examples/azuread/ad-user-assigned-id-dsn.jq

@@ -0,0 +1 @@
+@uri "sqlserver://\(.user_assigned_identity_client_id.value)@\(.sql_server_fqdn.value)?database=\(.sql_database_name.value)&encrypt=true&fedauth=ActiveDirectoryMSI"

examples/azuread/ad-user-password-dsn.jq

@@ -0,0 +1 @@
+@uri "sqlserver://\(.sql_ad_admin_user.value):\(.sql_ad_admin_password.value)@\(.sql_server_fqdn.value)?database=\(.sql_database_name.value)&encrypt=true&fedauth=ActiveDirectoryPassword"