jwt

Documentation

Overview

Package jwt contains support for using JWT tokens to authenticate and authorize incoming connections.

We require that incoming tokens have been signed with either RSA or EC keys. The public keys used for validation are stored in the database and are periodically refreshed.

Incoming JWT tokens are required to have the well-known "jti" token identifier field set. This is checked against a list of revoked token ids that are also stored in the database.

A minimally-acceptable token is shown below:

{
   "jti": "a25dac04-9f3e-49c1-a068-ee0a2abbd7df",
   "https://github.com/cockroachdb/replicator": {
     "sch": [
       [ "database", "schema" ],
       [ "another_database", "*" ],
       [ "*", "required_schema" ],
       [ "*", "*" ]
     ]
   }
}

As seen above, we use a globally-unique namespace to provide a list of schemas that the caller is allowed to use. Additional fields may be added to this namespace in the future.

Index

• Variables
• func InsertRevokedToken(ctx context.Context, tx types.StagingQuerier, auth types.Authenticator, ...) error
• func InsertTestingKey(ctx context.Context, tx types.StagingQuerier, auth types.Authenticator, ...) (method jwt.SigningMethod, signer crypto.PrivateKey, err error)
• func ProvideAuth(ctx *stopper.Context, db types.StagingQuerier, stagingDB ident.StagingSchema) (auth types.Authenticator, err error)
• type ClaimData
• type Claims
  • func NewClaim(schemas []ident.Schema) (Claims, error)
  • func Sign(method jwt.SigningMethod, key crypto.PrivateKey, schemas []ident.Schema) (Claims, string, error)
  • func (c Claims) Valid() error

Variables

var (
	// PublicKeysTable is the name of the table that contains public
	// keys used to validate incoming JWT tokens.
	PublicKeysTable = ident.New("jwt_public_keys")
	// RefreshDelay controls how ofter a watcher will refresh its schema. If
	// this value is zero or negative, refresh behavior will be disabled.
	RefreshDelay = flag.Duration("jwtRefresh", time.Minute,
		"how often to scan for updated JWT configuration; set to zero to disable")
	// RevokedIdsTable allows a list of known-bad "jti" token ids to be
	// rejected.
	RevokedIdsTable = ident.New("jwt_revoked_ids")
)

var Set = wire.NewSet(ProvideAuth)

Set is used by Wire.

Functions

func InsertRevokedToken

func InsertRevokedToken(
	ctx context.Context,
	tx types.StagingQuerier,
	auth types.Authenticator,
	stagingDB ident.StagingSchema,
	id string,
) error

InsertRevokedToken inserts the id of a revoked token into the Authenticator.

func InsertTestingKey

func InsertTestingKey(
	ctx context.Context,
	tx types.StagingQuerier,
	auth types.Authenticator,
	stagingDB ident.StagingSchema,
) (method jwt.SigningMethod, signer crypto.PrivateKey, err error)

InsertTestingKey generates a new private key and updates the existing Authenticator with the associated public key.

func ProvideAuth

func ProvideAuth(
	ctx *stopper.Context, db types.StagingQuerier, stagingDB ident.StagingSchema,
) (auth types.Authenticator, err error)

ProvideAuth is called by Wire to construct a JWT-based authenticator. This provider will also start a background goroutine to look for configuration changes in the database.

Types

type ClaimData

type ClaimData struct {
	Schemas []ident.Schema `json:"schemas,omitempty"`
}

ClaimData is the custom data that we want to embed in a JWT token.

type Claims

type Claims struct {
	jwt.RegisteredClaims
	// Place our extension in a proper namespace, for compatibility with
	// e.g. Auth0.
	Ext       ClaimData `json:"https://github.com/cockroachdb/replicator,omitempty"`
	LegacyExt ClaimData `json:"https://github.com/cockroachdb/cdc-sink,omitempty"`
}

Claims extends the core JWT Claims with elements specific to Replicator.

func NewClaim

func NewClaim(schemas []ident.Schema) (Claims, error)

NewClaim returns a minimal clam that would provide access to the requested schemas.

func Sign

func Sign(
	method jwt.SigningMethod, key crypto.PrivateKey, schemas []ident.Schema,
) (Claims, string, error)

Sign generates a new JWT that is compatible with Replicator. This method is used for testing and for the example quickstart.

func (Claims) Valid

func (c Claims) Valid() error

Valid implements jwt.Claims.