Load balancing and health checks

When a Connect2id server is launched it becomes ready to serve requests when the health check endpoint becomes available and returns a 200 HTTP status code.

When setting up a load balancer / reverse proxy make sure you poll this endpoint to determine the operational status of a server. Do not poll the banner page (the root resource) as it will likely be loaded first, before all endpoints.

Calls to the monitoring endpoint (which includes the health check endpoint as sub-resource) require a bearer access token:

• monitor.apiAccessTokenSHA256

We recommend provisioning a dedicated access token for the load balancer.

The token can be passed in the Authorization header or in a access_token query parameter, with the latter method guaranteed to be supported by all load balancers.

For example:

http://c2id.com/monitor/v1/healthcheck?access_token=with1lohY8wion9ophair0icaquaXeiy

The health check endpoint will ping the underlying databases. If the cluster is run in replication mode it will also include a check for the “split brain” cluster condition, when communication between nodes has broken down, and there is risk of in-memory data becoming inconsistent.

Example healthy response, SQL backend, stateless cluster mode:

HTTP/1.1 200 Success
Cache-Control: must-revalidate,no-cache,no-store
Content-Type: application/json

{
	"authzStore.codeMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"authzStore.expendedTokenMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"authzStore.idAccessTokenMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"authzStore.longLivedAuthzMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"authzStore.revocationJournalMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"clients.registrationsMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"clients.remoteJWKSetCache.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"clients.remoteRequestJWTClaimsCache.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"federation.registrationsMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"op.authSessionMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"op.consentSessionMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"op.dPoPJTICache.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"sessionStore.sessionMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"sessionStore.sessionMap.sqlStore.pool.ConnectivityCheck": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	},
	"sessionStore.subjectMap.availability": {
		"healthy": true,
		"duration": 0,
		"timestamp": "2023-11-29T09:54:09.693+02:00"
	}
}

AWS Elastic Beanstalk

In AWS Elastic Beanstalk use the Application Healthcheck URL environment parameter (e.g. in AWS Cloud Formation) to set the URL for the health check endpoint together with the access token.

Example:

- Namespace: aws:elasticbeanstalk:application
  OptionName: Application Healthcheck URL #Spaces are correct!
  Value: '/monitor/v1/healthcheck?access_token=with1lohY8wion9ophair0icaquaXeiy'