windowsauthtoken

README

Windows Authentication Handler for Go

Package windowsauthtoken implements Go HTTP middleware that will extract the username of a Windows user when running a Go web application in IIS with Windows authentication enabled. Package windowsauthtoken works with the HttpPlatformHandler module. When Windows authentication is enabled on the IIS website or application and HttpPlatformHandler is configured to pass the user's token to the Go web application, HttpPlatformHandler will pass the handle to the Go web application in the X-IIS-WindowsAuthToken HTTP header. The middleware providwed by package windowsauthtoken will obtain the full domain name of the Windows user and will make the username available to the web application.

Package windowsauthtoken is only available on a Windows Server when running the Go web application through IIS using the HttpPlatformHandler module. When using this package on non-Windows platforms, it is essentially a no-op passthrough hamdler, so it is safe to use and call in web applications that can run on multiple platforms.

Usage

First, get the source code for the package:

$ go get github.com/mfcollins3/windowsauthtoken

Next, use the middleware in your web application. HttpPlatformHandler will pass the Windows authentication token on every request, and it is the responsibility of your web application to close the handle, so you will want to apply the middleware globally to all requests. To do this, you will typically wrap the http.DefaultServeMux handler with the WindowsAuthTokenHandler middleware:

package main

import (
    "net/http"
    
    "github.com/mfcollins3/windowsauthtoken"
)

func main() {
    // TODO: register HTTP handlers with net/http
    
    rootHandler := windowsauthtoken.Handler(
        http.DefaultServeMux,
        func(username string) error {
            // Store username somewhere for the request. For example,
            // you can use Gorilla Toolkit's context package to store
            // the username in the request.
            return nil
        }, TokenUsername)
    log.Fatal(http.ListenAndServe(":8080", rootHandler))    
}

To run your Go web application in IIS, do the following:

1. Install HttpPlatformHandler
2. Create a website or application virtual directory in an existing website.
3. Create a new handler module mapping that maps all requests (*) to the httpPlatformHandler module.
4. Copy your Golang application to the physical directory that you pointed the website or application virtual directory to in step 2.
5. Create a web.config file in the physical directory:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*" verb="*"
           modules="httpPlatformHandler"
           resourceType="Unspecified"/>
    </handlers>
    <httpPlatform processPath="PATH-TO-EXE-HERE"
                  arguments="ANY-COMMAND-LINE-ARGUMENTS-HERE"
                  startupRetryCount="3"
                  stdoutLogEnabled="true"
                  forwardWindowsAuthToken="true"/>
  </system.webServer>
</configuration>

HttpPlatformHandler will pass the TCP/IP port for the web application to listen to for incoming requests in the HTTP_PLATFORM_PORT environment variable, so be sure that you use that in your program or pass it as an argument to your web application server.

Documentation

Overview

Package windowsauthtoken implements Windows user authentication using Windows domain credentials for Go web applications. Package windowsauthtoken is designed to work when the web application is being hosted by IIS on a Windows Server connected to a Windows domain using the HttpPlatformHandler module to forward requests from IIS to the web application.

HttpPlatformHandler supports a configuration option that forwards the handle for the Windows token for the authenticated user to the Go web application by attaching the X-IIS-WindowsAuthToken HTTP header to the forwarded request. Package windowsauthtoken implements a middleware handler that will execute on every request to extract the handle from the HTTP header, obtain the name of the authenticated user, and make the Windows username available to the web application.

HttpPlatformHandler will pass the handle on every request that is forwarded to the web application, and it is the responsibility of the web application to close the handle at the end of the request. This is handled automatically by the middleware. But because the handle is passed on every request, it is recommended that you wrap the http.DefaultServeMux handler or your root handler with the middleware. For example:

package main

import (
    "net/http"

    "github.com/mfcollins3/windowsauthtoken"
)

func main() {
    // TODO: register HTTP handlers with net/http

    rootHandler := windowsauthtoken.Handler(
        http.DefaultServeMux,
        func(username string) error {
            // Store username somewhere for the request. For example,
            // you can use Gorilla Toolkit's context package to store
            // the username in the request.
            return nil
        })
    log.Fatal(http.ListenAndServe(":8080", rootHandler))
}

Index

• func Handler(next http.Handler, callback Callback, tokenValue TokenValue) http.Handler
• type Callback
• type TokenValue

Functions

func Handler

func Handler(next http.Handler, callback Callback, tokenValue TokenValue) http.Handler

Handler returns an HTTP handler that will process the token for the authenticated user that is passed to the web application in the X-IIS-WindowsAuthToken HTTP header. Handler will obtain the Windows username for the authenticated user and will pass the username to the web application using the callback parameter.

Types

type Callback

type Callback func(username string) error

Callback is an application-provided function that the web application provides to the Handler middleware. The callback function will be called on each request after the username for the authenticated Windows user has been obtained. The application can use the callback to store the username for processing within the request.

type TokenValue

type TokenValue int

TokenValue is an enumeration that specifies which user token value should be passed to the callback handler by the Windows authentication token handler. The current options are either to send the DOMAIN\Username vale or the user's SID to the callback handler.

const (
	// TokenUsername indicates that the Windows authentication token handler
	// will invoke the callback handler with the Windows username
	// (DOMAIN\Username) for the authenticated user.
	TokenUsername TokenValue = iota

	// TokenSid indicates that the Windows authentication token handler will
	// invoke the callback handler with the authenticated user's SID as a
	// string.
	TokenSid
)