... | ... | @@ -28,207 +28,7 @@ There are separate [instructions](cloudpath) for configuring CloudPath certifica |
|
|
|
|
|
See the [testing instructions](testing).
|
|
|
|
|
|
## Building CertCache
|
|
|
## Building, Configuring, and Running CertCache
|
|
|
|
|
|
As described in the [architecture](architecture) page, there are several components to CertCache, and those are spread across several projects.
|
|
|
|
|
|
The Node application (API and queue processing) is the [certcache](https://code.stanford.edu/et/certcache/) repository.
|
|
|
|
|
|
The AWS API Gateway and SQS configuration is handled by [Terraform](https://terraform.io) using a custom [certcache](https://code.stanford.edu/tf_modules/certcache) module. The definition in our various environments should look like:
|
|
|
|
|
|
### `itlab` certcache
|
|
|
|
|
|
module "certcache" {
|
|
|
source = "git::ssh://git@code.stanford.edu/tf_modules/certcache.git"
|
|
|
stages = [ "itlab" ]
|
|
|
role_name = "hosting"
|
|
|
}
|
|
|
|
|
|
### `authnz-x` certcache
|
|
|
|
|
|
module "certcache" {
|
|
|
source = "git::ssh://git@code.stanford.edu/tf_modules/certcache.git"
|
|
|
stages = [ "dev", "test", "int", "uat" ]
|
|
|
role_name = "authnz-x-worker"
|
|
|
}
|
|
|
|
|
|
### `authnz` certcache
|
|
|
|
|
|
module "certcache" {
|
|
|
source = "git::ssh://git@code.stanford.edu/tf_modules/certcache.git"
|
|
|
stages = [ "prod" ]
|
|
|
role_name = "authnz-prod-worker"
|
|
|
}
|
|
|
|
|
|
The container image is built on a base Debian Stretch + NodeJS [image](https://code.stanford.edu/et/core-node/), using a [Packer](https://packer.io/) [build project](https://code.stanford.edu/et/core-certcache/).
|
|
|
|
|
|
## Unit Definition
|
|
|
|
|
|
The CertCache image is currently run as a container using [fleet](https://github.com/coreos/fleet) unit; it will migrate to [Kubernetes](https://kubernetes.io/) in the near future. The unit file is used to start and stop the container, and to register the container with a load balancer (the LB is also used for SSL offload).
|
|
|
|
|
|
*NOTE*: certcache has not yet been tested in a load balanced pool, so only one instance should be run in each environment.
|
|
|
|
|
|
The unit definition is in the [itlab-apps](https://code.stanford.edu/et/itlab-apps) project as [certcache/units/certcache.service](https://code.stanford.edu/et/itlab-apps/blob/master/certcache/units/certache.service), along with an [envvars](https://code.stanford.edu/et/itlab-apps/blob/master/certcache/envvars) file to define the runtime environment.
|
|
|
|
|
|
CertCache uses the following environment variables
|
|
|
|
|
|
|Name|Value|Description|
|
|
|
|----|-----|-----------|
|
|
|
|IMAGE|localhost:5000/core/certcache:nightly|Docker image to run|
|
|
|
|CONFIG_FILE|/app/config.json|path to the config file, inside the container|
|
|
|
|RUN_ENV|prod|runtime environment|
|
|
|
|LOG_FORMAT|combined|log format (Apache combined-style)
|
|
|
|ENV_PORT|8020|port to expose on the Docker host|
|
|
|
|HTTP_PORT|8080|port to use inside the container|
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
The configuration file should be mounted into the container as `/app/config.json`; the JSON file has "sections" (sub-objects) to define various settings:
|
|
|
|
|
|
### Example Configuration
|
|
|
|
|
|
{
|
|
|
"numProcs": 1,
|
|
|
"aws": {
|
|
|
"region": "us-west-2"
|
|
|
},
|
|
|
"cloudpath": {
|
|
|
"url": "https://onboard.cloudpath.net/admin/api/",
|
|
|
"key": "SECRET",
|
|
|
"prefix": "/certificate/Pk/"
|
|
|
},
|
|
|
"db": {
|
|
|
"host": "mysql.rds-zone.us-west-2.rds.amazonaws.com",
|
|
|
"ssl": "Amazon RDS",
|
|
|
"user": "certcache",
|
|
|
"password": "SECRET",
|
|
|
"port": 3306,
|
|
|
"database": "certcache"
|
|
|
},
|
|
|
"healthcheck": {
|
|
|
"path": "/api-docs"
|
|
|
},
|
|
|
"introspection": {
|
|
|
"url": "https://authz.itlab.stanford.edu/introspect",
|
|
|
"client_id": "certcache.itlab.stanford.edu",
|
|
|
"client_secret": "SECRET"
|
|
|
},
|
|
|
"scopes": {
|
|
|
"read": "certcache:read",
|
|
|
"write": "certcache:write"
|
|
|
},
|
|
|
"periodic": {
|
|
|
"interval": 900,
|
|
|
"unknown_days": 7,
|
|
|
"compliance_days": 10
|
|
|
},
|
|
|
"sqs": {
|
|
|
"main": "certcache.fifo",
|
|
|
"dl": "certcache_dl.fifo",
|
|
|
"visibilityTimeout": 60,
|
|
|
"maxMessages": 1,
|
|
|
"checkInterval": 40,
|
|
|
"checkDLInterval": 40,
|
|
|
"waitSeconds": 20
|
|
|
}
|
|
|
}
|
|
|
|
|
|
### Top Level Configuration
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|numProces|1|Numer of API processes to run|
|
|
|
|
|
|
### `aws` Configuration
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|region|us-west-2|AWS Region in which certcache is running|
|
|
|
|profile|-|(Optional) AWS profile to use, if not using instance profiles|
|
|
|
|
|
|
Other AWS settings are obtained from the environment or from EC2 instance roles.
|
|
|
|
|
|
### `cloudpath` Configuration
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|url|https://onboard.cloudpath.net/admin/api/|Base CloudPath API URL - trailing slash is required|
|
|
|
|key|SECRET|CloudPath API key, which access to query and revoke certificates|
|
|
|
|prefix|/certificate/Pk/|prefix to use before the CloudPath PK in API URLs - trailing slash is required|
|
|
|
|
|
|
### `db` Configuration
|
|
|
|
|
|
CertCache requires a MySQL database; we're using AWS [RDS](https://aws.amazon.com/rds/mysql/).
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|host|mysql.xxx.us-west-2.rds.amazonaws.com|server hostname|
|
|
|
|ssl|Amazon RDS|SSL configuration, using Amazon RDS profile; can also be an object ([docs](https://github.com/mysqljs/mysql#ssl-options))|
|
|
|
|port|3306|database server port|
|
|
|
|database|certcache|database name|
|
|
|
|user|certcache|database username|
|
|
|
|password|SECRET|database password|
|
|
|
|
|
|
*NOTE* We did try using the new RDS IAM functionality, but it does not work with current NodeJS MySQL client pooling.
|
|
|
|
|
|
### `healthcheck` Configuration
|
|
|
|
|
|
|Key |Value |Description|
|
|
|
|----|---------|-----------|
|
|
|
|path|/api-docs|path used for requests to /healthcheck endpoint|
|
|
|
|
|
|
The healthcheck endpoint is always available over HTTP.
|
|
|
|
|
|
### `introspection` Configuration
|
|
|
|
|
|
Access to the CertCache API is controlled using [OAuth 2.0](https://tools.ietf.org/html/rfc6749); the API must be configured to use [Token Introspection](https://tools.ietf.org/html/rfc7662) to obtain information about client tokens.
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|url|https://authz.itlab.stanford.edu/introspect|Introspection endpoint on the OAuth 2.0 Authorization Server|
|
|
|
|client_id|certcache.itlab.stanford.edu|client ID for introspection|
|
|
|
|client_secret|SECRET|client secret for introspection|
|
|
|
|
|
|
### `scopes` Configuration
|
|
|
|
|
|
CertCache supports separate read and write OAuth 2.0 scopes, which are configurable.
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|read|certcache:read|scope that grants clients read access|
|
|
|
|write|certcache:write|scope that grants clients write access|
|
|
|
|
|
|
### `periodic` Configuration
|
|
|
|
|
|
CertCache runs a `revoker` process to handle delayed / post-dated certificate revocations.
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|-----|-----------|
|
|
|
|interval|900|# of seconds between periodic processor runs|
|
|
|
|unknown_days|7|# of days before newly issued certs (`unknown` status) are marked as `not_ok`|
|
|
|
|compliance_days|10|# of days before non-compliance changes (`not_ok` status) take effect|
|
|
|
|
|
|
Note: compliance updates that set a cert's status to `ok` are processed immediately
|
|
|
|
|
|
Each time the periodic processor runs it
|
|
|
|
|
|
* changes status to `expired` when certs have expired
|
|
|
* applies delayed status changes
|
|
|
* cleans up delayed updates that have been applied
|
|
|
* revokes certs marked for revocation
|
|
|
|
|
|
### `sqs` Configuration
|
|
|
|
|
|
Notifications from CloudPath are pushed onto an SQS queue. CertCache has an SQS process that periodically
|
|
|
|
|
|
|Key|Value|Description|
|
|
|
|---|---|---|
|
|
|
|main|certcache.fifo|main queue, where notifications arrive|
|
|
|
|dl|certcache_dl.fifo|dead letter queue, where failed notifications are held|
|
|
|
|visibilityTimeout|60|how long messages are hidden while they are processed|
|
|
|
|maxMessages|1|maximum number of messages to receive in each SQS query|
|
|
|
|checkInterval|40|# of seconds between queue runs|
|
|
|
|checkDLInterval|40|# of seconds between dead letter runs|
|
|
|
|waitSeconds|20|# of seconds to wait on an empty queue|
|
|
|
See the certcache [instructions](certcache).
|
|
|
|