didcomauth

README

didcomauth: commercio.network DID-based HTTP authentication

This package implements commercio.network-based authentication, leveraging gorilla/mux for route management.

Authentication happens if the user can prove the ownership of its DID by signing a challenge with its signing key.

A resource-based JWT token is released to the user that can prove the ownership of its DID, assuming he was authorized by the resource owner to access it.

DID resolution happens on the commercio.network blockchain, assuming that the user created a DID on it.

Endpoints

didcomauth adds the following endpoints to your mux:

• a challenge URL, by default on /auth/challenge
• a subdirectory under which every HTTP handler requires DID authentication, by default /protected

The protected path can be customized, refer to the godoc for more information.

Each HTTP call requires two headers to be specified:

• X-DID, the DID which should be authenticated
• X-Resource, the resource to be accessed

Each protected handler can decide whether allowing or not access to a specific resource based on the X-Resource header, didcomauth's concerns revolve around authentication only.

Example server

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/commercionetwork/didcomauth"
	"github.com/gorilla/mux"
)

func main() {
	m := mux.NewRouter()

	err := didcomauth.Configure(didcomauth.Config{
		JWTSecret: "secret",
		CacheType: didcomauth.CacheTypeRedis,
		ProtectedPaths: []didcomauth.ProtectedMapping{
			{
				Methods: []string{http.MethodGet},
				Path:    "/upload/{id:(?:.+)}",
				Handler: uploadHandler,
			},
		},
	}, m)

	m.HandleFunc("/foo", func(writer http.ResponseWriter, request *http.Request) {
		fmt.Fprintln(writer, "Foo!")
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Fatal(http.ListenAndServe(":6969", m))
}

func uploadHandler(writer http.ResponseWriter, request *http.Request) {
	vars := mux.Vars(request)
	id := vars["id"]

	fmt.Fprintf(writer, "your upload id is: %s", id)
}

Documentation

Index

• Constants
• func Configure(c Config, r *mux.Router) error
• type AuthResponse
  • func (ar AuthResponse) ResponseBytes() ([]byte, error)
  • func (ar AuthResponse) Validate() error
• type CacheType
• type Challenge
  • func (c Challenge) MarshalBinary() (data []byte, err error)
  • func (c Challenge) SignaturePayload() []byte
• type Config
  • func (c *Config) Validate() error
• type DidComAuthClaims
• type ProtectedMapping
• type ReleaseJWTResponse

Constants

const (
	DIDHeader      = "X-DID"
	ResourceHeader = "X-Resource"
)

Functions

func Configure

func Configure(c Config, r *mux.Router) error

Configure configures DID:COM authentication endpoints on mr.

Types

type AuthResponse

type AuthResponse struct {
	Challenge
	Response string `json:"response"`
}

func (AuthResponse) ResponseBytes

func (ar AuthResponse) ResponseBytes() ([]byte, error)

ResponseBytes returns the bytes representation of the base64-encoded Response field.

func (AuthResponse) Validate

func (ar AuthResponse) Validate() error

Validate checks that AuthResponse is valid and does not contains bogus data.

type CacheType

type CacheType int

const (
	CacheTypeRedis CacheType = iota
	CacheTypeMemory
)

type Challenge

type Challenge struct {
	Challenge string `json:"challenge"`
	Timestamp int64  `json:"timestamp"`
	DID       string `json:"did,omitempty"`
}

func (Challenge) MarshalBinary

func (c Challenge) MarshalBinary() (data []byte, err error)

encoding.Binary{Marshaler,Unmarshaler} interface implementation

func (Challenge) SignaturePayload

func (c Challenge) SignaturePayload() []byte

SignaturePayload returns the bytes on which the user should have placed its signature.

type Config

type Config struct {
	RedisHost         string
	ProtectedBasePath string
	ProtectedPaths    []ProtectedMapping
	JWTSecret         string
	CommercioLCD      string
	CacheType         CacheType
	CacheProvider     cache
}

Config holds data regarding the didcomauth module configuration, such as redis host, Challenge and protected base URL path.

func (*Config) Validate

func (c *Config) Validate() error

type DidComAuthClaims

type DidComAuthClaims struct {
	*jwt.StandardClaims
	Resource string `json:"resource"`
	DID      string `json:"did"`
}

DidComAuthClaims represents the JWT claim we release after a successful DID authentication

type ProtectedMapping

type ProtectedMapping struct {
	Methods []string
	Path    string
	Handler http.HandlerFunc
}

ProtectedMapping represents a URI resource handled under the DID-authenticated protected path.

type ReleaseJWTResponse

type ReleaseJWTResponse struct {
	Token string `json:"token"`
}

ReleaseJWTResponse represents a JSON struct which we return to a caller if the DID authentication is successful.