themis

README

Themis

Summary

A JWT token issuer for devices that connect to the XMiDT cluster.

Table of Contents

• Code of Conduct
• Details
• Build
• Deploy
• Contributing

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Details

Themis provides a flexible strategy to issue JWT tokens to devices that need to connect to the XMiDT cluster.

Endpoints

There are three main endpoints (directly mapped to servers key, issuer and claims in configuration) this service provides:

• GET /keys/{KID} - PEM format
• GET /keys/{KID}/key.json - JWK format

This endpoint allows fetching the public portion of the key that themis uses to sign JWT tokens. For example, Talaria can use this endpoint to verify the signature of tokens which devices present when they attempt to connect to XMiDT.

Configuration for this endpoint is required when the issue endpoint is configured and vice versa.

• GET /issue

This is the main and most compute intensive Themis endpoint as it creates JWT tokens based on configuration.

• GET /claims

Configuring this endpoint is required if no configuration is provided for the previous two.

JWT Claims Configuration

Claims can be configured through the token.claims, partnerID and remote configuration elements. The claim values themselves can come from multiple sources.

Fixed values in configuration

token:
  ...

  claims:
    capabilities
      value:
        - capability0
        - capability1

The above config would create the claim:

"capabilities":  ["capability0", "capability1"]

HTTP Header or Parameter

token:  
  ...

  claims:
    mac:
      header: X-Midt-Mac-Address
      parameter: mac

The value of the mac claim would come from the specified header or parameter name of the request to the /issue endpoint.

PartnerID

Although it is configured separately, it behaves very similarly to the previous source type.

partnerID:
  claim: partner-id
  metadata: pid # only needed when a remote claims server needs this value
  header: X-Midt-Partner-ID
  parameter: pid
  default: comcast

Remote claims

remote:
  method: "POST"
  url: "http://remote-claims-server.example.com/claims"

For more informatiom on how to configure Themis to run as your remote claims server, read the next section on Remote Server Claims Configuration.

Remote Server Claims Configuration

Using Themis as the remote claims server

You can do this by configuring only the claims server in your configuration file. Claims are configured exactly the same as explained above.

Sending data to remote server

Suppose the remote claims server needs the ID of the device requesting a token in the form of an HTTP Header named X-Midt-Device-Id. The token.metadata configuration element allows you to specify which values are sent to the remote claims server.

token:
  ...
  metadata:
    ID:
      header: X-Midt-Device-Id

Build

There is a single binary for themis and its execution is fully driven by configuration.

Makefile

The Makefile has the following options you may find helpful:

• make build: builds the Themis binary
• make docker: builds a docker image for themis
• make local-docker: builds a docker image for themis with the local version tag
• make test: runs unit tests with coverage for Themis
• make clean: deletes previously-built binaries and object files

Deploy

At the simplest form, run the binary with the flag specifying the configuration file

./themis -f themis.yaml

Docker

We recommend using docker for local development.

# Build docker image for themis
# themis.yaml specifies the static claims which will be returned in the JWT
make local-docker

# Run container service
docker run -p 6501:6501 themis:local

# Request a JWT token
curl http://localhost:6501/issue -H 'X-Midt-Mac-Address: mac:1122334455'

Contributing

Refer to CONTRIBUTING.md.

Documentation

Overview

SPDX-FileCopyrightText: 2017 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2017 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2019 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

Index

• Constants
• Variables
• func BuildClaimsRoutes(in ClaimsRoutesIn)
• func BuildHealthRoutes(in HealthRoutesIn)
• func BuildIssuerRoutes(in IssuerRoutesIn)
• func BuildKeyRoutes(in KeyRoutesIn)
• func BuildMetricsRoutes(in MetricsRoutesIn)
• func BuildPprofRoutes(in PprofRoutesIn)
• func CheckServerRequirements(k KeyRoutesIn, i IssuerRoutesIn, c ClaimsRoutesIn) error
• func New(opts fx.Option) (*fx.App, error)
• func SetLogger(delegate http.Handler) http.Handler
• type ClaimsRoutesIn
• type HealthRoutesIn
• type IssuerRoutesIn
• type KeyRoutesIn
• type MetricsRoutesIn
• type PprofRoutesIn
• type ServerChainIn

Constants

const (
	TraceIDHeaderName = "Trace-ID"
	SpanIDHeaderName  = "Span-ID"
)

const (
	ApplicationName = "themis"
)

const ServerLabel = "server"

ServerLabel is the metric label for which internal server (key, claims, etc) a metric is for

Variables

var (
	GitCommit = "undefined"
	Version   = "undefined"
	BuildTime = "undefined"
)

Functions

func BuildClaimsRoutes

func BuildClaimsRoutes(in ClaimsRoutesIn)

func BuildHealthRoutes

func BuildHealthRoutes(in HealthRoutesIn)

func BuildIssuerRoutes

func BuildIssuerRoutes(in IssuerRoutesIn)

func BuildKeyRoutes

func BuildKeyRoutes(in KeyRoutesIn)

func BuildMetricsRoutes

func BuildMetricsRoutes(in MetricsRoutesIn)

func BuildPprofRoutes

func BuildPprofRoutes(in PprofRoutesIn)

func CheckServerRequirements

func CheckServerRequirements(k KeyRoutesIn, i IssuerRoutesIn, c ClaimsRoutesIn) error

CheckServerRequirements is an fx.Invoke function that does post-configuration verification that we have required servers. The valid server configurations are:

Both keys and issuer present.  Claims is optional in this case
Neither keys or issuer present.  Claims is required in this case

Any other arrangements results in an error.

func New

func New(opts fx.Option) (*fx.App, error)

func SetLogger

func SetLogger(delegate http.Handler) http.Handler

Types

type ClaimsRoutesIn

type ClaimsRoutesIn struct {
	fx.In
	Router  *mux.Router `name:"servers.claims"`
	Handler token.ClaimsHandler
}

type HealthRoutesIn

type HealthRoutesIn struct {
	fx.In
	Router  *mux.Router `name:"servers.health"`
	Handler xhealth.Handler
}

type IssuerRoutesIn

type IssuerRoutesIn struct {
	fx.In
	Router  *mux.Router `name:"servers.issuer"`
	Handler token.IssueHandler
}

type KeyRoutesIn

type KeyRoutesIn struct {
	fx.In
	Router     *mux.Router `name:"servers.key"`
	Handler    key.Handler
	HandlerJWK key.HandlerJWK
}

type MetricsRoutesIn

type MetricsRoutesIn struct {
	fx.In
	Router  *mux.Router `name:"servers.metrics"`
	Handler xmetricshttp.Handler
}

type PprofRoutesIn

type PprofRoutesIn struct {
	fx.In
	Router *mux.Router `name:"servers.pprof"`
}

type ServerChainIn

type ServerChainIn struct {
	fx.In

	RequestCount     *prometheus.CounterVec   `name:"server_request_count"`
	RequestDuration  *prometheus.HistogramVec `name:"server_request_duration_ms"`
	RequestsInFlight *prometheus.GaugeVec     `name:"server_requests_in_flight"`
}