A JWT token issuer for devices that connect to the XMiDT cluster.
This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.
Themis provides a flexible strategy to issue JWT tokens to devices that need to connect to the XMiDT cluster.
There are three main endpoints (directly mapped to servers key
, issuer
and claims
in configuration) this service provides:
/keys/{KID}
- PEM format/keys/{KID}/key.json
- JWK formatThis 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.
/issue
This is the main and most compute intensive Themis endpoint as it creates JWT tokens based on configuration.
/claims
Configuring this endpoint is required if no configuration is provided for the previous two.
Claims can be configured through the token.claims
, partnerID
and remote
configuration elements. The claim values themselves can come from multiple sources.
token:
...
claims:
capabilities
value:
- capability0
- capability1
The above config would create the claim:
"capabilities": ["capability0", "capability1"]
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.
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:
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.
You can do this by configuring only the claims
server in your configuration file.
Claims are configured exactly the same as explained above.
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
There is a single binary for themis and its execution is fully driven by configuration.
The Makefile has the following options you may find helpful:
make build
: builds the Themis binarymake docker
: builds a docker image for themismake local-docker
: builds a docker image for themis with the local
version tagmake test
: runs unit tests with coverage for Themis make clean
: deletes previously-built binaries and object filesAt the simplest form, run the binary with the flag specifying the configuration file
./themis -f themis.yaml
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'
Refer to CONTRIBUTING.md.