dpop

README

dpop

Go library for DPoP (OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer).

This implementation is current for draft-fett-oauth-dpop-03, published October 30, 2019.

Usage

Go API

See the godoc.

CLI

This repository also contains a small command line tool that can be used for trying out DPoP, demo-dpop:

# build the demo-dpop binary
make

# generates a new private key to use for signing
demo-dpop create-key --key-name my-local-key

# Outputs an example curl line with a DPoP proof in a header, which can be used during a token exchange:
demo-dpop proof --key-name my-local-key --url https://as.example.com/token --method POST

# Outputs an example curl line with a DPoP proof header, which can be used in conjunction with an access
# token for a resource server access:
demo-dpop proof --key-name my-local-key --url https://resource1.example.com/api/endpoint --method POST

Dependencies

• Go 1.12 (using go modules)

Code signing

This repo also contains a work-in-progress to use the Secure Enclave Processor (SEP) as a key-storage for a signing a DPoP JWT. This has additional dependencies:

• macOS >= 10.12
• TouchID hardware
• Developer Tools installed
• Code Signing certificate available

(macOS requires code signing to use the Keychain with the enclave)

License

dpop is licensed under the Apache License, Version 2.0

Documentation

Overview

Copyright 2014 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Index

• Variables
• type Proof
  • func New(key jose.SigningKey) (Proof, error)
• type ProofClaims
• type TokenExchange
  • func (be *TokenExchange) Exchange(ctx context.Context, code string, extra url.Values) (*oauth2.Token, error)
• type Validator
  • func (pv *Validator) ValidateResourceAccess(req *http.Request, keyFingerprint string) (*ProofClaims, []byte, *jose.JSONWebKey, error)
  • func (pv *Validator) ValidateTokenRequest(req *http.Request) (*ProofClaims, []byte, *jose.JSONWebKey, error)

Variables

var (
	ErrProofMissing          = errors.New("dpop: HTTP Header '" + httpHeader + "' not present in request")
	ErrProofMalformedHeader  = errors.New(`dpop: HTTP Header '` + httpHeader + `' contained a malformed JWT header`)
	ErrProofMalformedClaim   = errors.New(`dpop: HTTP Header '` + httpHeader + `' contained a malformed JWT claim`)
	ErrProofInvalidSignature = errors.New(`dpop: HTTP Header '` + httpHeader + `' contained an invalid JWT`)
)

Types

type Proof

type Proof interface {
	// ForRequest annotates an HTTP Request with a DPoP header.
	ForRequest(r *http.Request, extraClaims interface{}) error
}

func New

func New(key jose.SigningKey) (Proof, error)

New creates a DPoP Proof that can generate DPoP headers for a request.

type ProofClaims

type ProofClaims struct {
	jwt.Claims
	HTTPMethod string `json:"htm,omitempty"`
	HTTPUri    string `json:"htu,omitempty"`
}

ProofClaims are common claims in the DPoP proof JWT.

type TokenExchange

type TokenExchange struct {
	// Config for the OAuth exchange.
	Config *oauth2.Config
	// Binder provides the HTTP DPoP  header for this exchange.
	Proof Proof
	// Client optionally overrides the HTTP Client to use for the Exchange. If nil, http.DefaultClient is used
	Client *http.Client
}

func (*TokenExchange) Exchange

func (be *TokenExchange) Exchange(ctx context.Context, code string, extra url.Values) (*oauth2.Token, error)

Exchange wraps the process of creating an OAuth Token exchange with a DPoP header.

type Validator

type Validator struct {
	xjwt.VerifyConfig
}

ProofValidator validates DPoP proof headers

func (*Validator) ValidateResourceAccess

func (pv *Validator) ValidateResourceAccess(req *http.Request, keyFingerprint string) (*ProofClaims, []byte, *jose.JSONWebKey, error)

ValidateResourceAccess parses and performs a PARTIAL validation of the DPoP proof JWT.

It returns common proof claims, raw claims, and the public JWK used to sign the proof.

keyFingerprint is the "jkt#S256" cnf claim from a JWT based Access Token or from an introspection response.

Callers MUST do additional validation for their use case of:

ProofClaims.JTI: For replay protection, confirm this JTI has not been used before:
	   Within a reasonable consideration of accuracy and resource
       utilization, a JWT with the same "jti" value has not been
       received previously (see Section 9.1).

func (*Validator) ValidateTokenRequest

func (pv *Validator) ValidateTokenRequest(req *http.Request) (*ProofClaims, []byte, *jose.JSONWebKey, error)

ValidateTokenRequest parses and performs a PARTIAL validation of the DPoP proof JWT.

It returns common proof claims, raw claims, and the public JWK used to sign the proof.

Callers MUST do additional validation for their use case of:

	ProofClaims.JTI: For replay protection, confirm this JTI has not been used before:
		   Within a reasonable consideration of accuracy and resource
	       utilization, a JWT with the same "jti" value has not been
	       received previously (see Section 9.1).

 JSONWebKey: The caller must calculate the JWK SHA-256 Thumbprint, encoding it using base64url, and
 	embed it in any Access Tokens issued or make it available in the introspection request:
			tb, err := key.Thumbprint(crypto.SHA256)
 		cnfThumbprint := base64.URLEncoding.EncodeToString(tb)

 JSONWebKey: Algorithm and key type are acceptable.

If this Client has previously used a DPoP binding at Token request, you may also wish to restrict the JSONWebKey to a previously used value.