Internal Service Overview¶

Docker Containers¶

Docker containers are required to run in 3DIAX’s cloud. This allows software vendors to have complete control over the runtime environment in which their service operates. Documentation on Docker containers are available from various sources, though we recommend the Official Docker Tutorial for those who are new to Docker and containers. Docker containers at Authentise run inside a distributed Docker Swarm. In general you should assume that your container will be limited to 512M of RAM and a single CPU, though exceptions can be made on request. If you have questions or assistance with container technology feel free to contact Authentise at info@authentise.com

It is preferred, though not required, that your Docker image be available on the Docker Hub. The image can be private - you simply need to share read access to the image with authentiseautomation. Your Docker image should be tagged uniquely - do not use the latest tag. Image tags should use semantic versioning. If you are using a git repository for source code management please use a tag format such as X.Y-Z-gNNNNNN where X is the major version number, Y is the minor version number, Z is the number of commits passed version X.Y‘s tag, and gNNNNNN is the short form hash of the commit. This is the same value you would see from the output of git describe. This structure makes it very easy to relate particular container images to source code versions. If you do not use git feel free to specify another semantic version scheme that relates to your SCM tool of choice.

RESTful HTTP interface¶

Services running in Authentise’s cloud communicate with each other over HTTP. This is a protocol that has some major drawbacks, but overall provides an interface that is easy to implement in any language. HTTP services should be able to send and receive JSON. Operations using the GET method should be idempotent. Requests should respond within 3 seconds to avoid timing out. Long-running operations should use an architecture where a client creates the operation using POST and the response provides a URL where the client can request status updates. The client then makes a GET request to that URL to get updated information on the long-running operation.

Services using an HTTP interface should expect to be load-balanced on a naive load balancer such that successive requests may be serviced by separate copies of the service that do not share memory directly. Data sharing should be achieved through client cookies and some kind of coordinated data store such as a shared in-memory cache or database.

Authentise has several backend services that providers can use for common tasks such as making callback requests, handling user sessions, and granting permissions to resources. If you are interested in making use of these services please contact contact us

When providing an External Service the provider validate and provide JWTs as described in the External Service Provider Reference. This is not true of internal services. Because the services run inside Authentise cloud there is no need to validate the identity and authenticity of the service. Authentise instead can use the fact that the service is running in our datacenter to authenticate its actions.

When providing an Internal Service to Authentise you must include documentation on the various endpoints for the service. The documentation should include every URL path the service supports, the HTTP methods that can be used on the path (GET, PUT, POST, etc), the HTTP status codes that can be returned during normal operation, and the JSON data that the endpoint accepts on PUT/POST/PATCH and emits on GET/DELETE, if any. A good example template is the Reference or the Reference.