Skip to content

Latest commit

 

History

History
73 lines (55 loc) · 7.38 KB

integrate-a3s-docker-compose-convention.md

File metadata and controls

73 lines (55 loc) · 7.38 KB
Raw

Integrating A3S Into A Docker-Compose by Convention

The quickstart guide uses docker-compose to compose several inter-related docker containers into a functioning environment. However, the components of that environment are dependent on one another.

  • The a3s is dependent on the a3s-postgresql Postgresql docker container, as it uses Postgresql as it's relational data store. The a3s container must be configured to connect to this database.
  • The a3s-identity-server component also depends on the a3s-postgresql Postgresql docker container, as it needs to read many of the same relational stores that A3S operates on to issue access tokens to users.
  • The a3s container is dependent on the a3s-identity-server to be it's access token issuer.

How do the containers running in this enviroment know where to connect? Internally, the docker images that are built for A3S and A3S-Identity-Server have a default internal configuration which assumes the setup within the quickstart docker-compose file. All the settings can be overridden by mounting in custom configuration files into the various containers, but this couples the integrating party to the changing configuration of A3S and IDS4, which is undesirable. Therefore, when pulling A3S and IDS4 containers into your own docker-compose environments, understanding and using the following conventions will enable you to pull the A3S, IDS4, and mutually required Postgresql container into your docker-compose environment without the need to configure (and therefore mount in configurations into the containers) for each of the containers.

Default Configurations

  • a3s and the a3s-identity-server containers connect to the Postgresql container using the following settings:

    • hostname: a3s-postgresql. This necessitates the name of the service within the quickstart docker-compose file to be this value.
    • username: postgres. This is the reason the POSTGRES_USER=postgres environment variable (within the Postgresql container) is configured as such.
    • password: postgres. This is the reason the POSTGRES_PASSWORD=postgres environment variable (within the Postgresql container) is configured as such.
    • database: identity_server. This is the reason the POSTGRES_DB=identity_server environment variable (within the Postgresql container) is configured as such.

  • a3s also protects it's own resources with itself and requires access tokens issued by a3s-identity-server for authenticated access. Therefore, A3S must be configured with a3s-identity-server to be it's access tokens issuer. The default configuration for this IssuerURL is http://a3s-identity-server, which necessitates the name of the IDS4 container to be a3s-identity-server with the docker-compose.yml.

Docker Compose Convention

When pulling in A3S containers into your own docker-compose environments, ensure that the following naming conventions are adhered to within your docker-compose.yml file and you will not need to configure any of the A3S related containers to connect to one another. Note The A3S quickstart docker-compose file adheres to these conventions and can be used as a reference:

  • Name the A3S service a3s.
  • Name the Identity Server 4 service: a3s-identity-server.
  • Name the Postgresql service: a3s-postgresql.
  • Ensure the Postgresql username is: postgres
  • Ensure the Postgresql password is: postgres
  • Ensure the Postgresql instance has a database called: identity_server.
  • If using the official Postgres image, this can all be done as follows:
a3s-postgresql:
    networks:
      - a3s-quickstart
    image: "postgres:10.7-alpine"
    restart: always
    ports:
      # Use a non standard port mapping to avoid potential collisions with other Postgres instances running on the host.
      - '5478:5432'
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_DB=identity_server

Figure 1: An excerpt from the AS3 quickstart docker-compose.yml showing how to configure credentials and a default database when using the official Postgres docker image.

Automatically Running Security Contracts on Docker-compose Up

Security Contracts are a central concept within A3S. Therefore, the A3S quickstart guide intentionally includes instructions for manually applying a security contract in order to expose the user to these concepts. This is also the reason why quickstart docker-compose file does not contain any setup for automatically applying a security contract.

When integrating A3S into your docker-compose environment, it is not necessary to manually apply the security contract in the same fashion as the A3S quickstart guide. The application of a security contract is simply:

  1. Obtaining an access token for a user that has the a3s.securityContracts.update permission.
  2. PUT the security contract using the API.

This can be achieved with any user agent capable of making the required HTTP API requests. The A3S makes use of Postman for API testing and discoverability. Therefore, the following example demonstrates how to use a Newman docker container to programatically run a Postman collection when starting up a docker-compose environment. The Postman collection simply performs the same steps as 1. and 2. above.

newman:
   networks:
     - a3s-quickstart   
   image: "postman/newman_alpine33" 
   command: run /etc/newman/register-a3s-contract.postman_collection.json --global-var client-id='a3s-default' --global-var client-secret='secret'  --global-var a3s-host=http://a3s --global-var auth-server-base-url=http://a3s-identity-server --delay-request 15000 
   volumes:
       - ../../postman:/etc/newman
   depends_on:
     - a3s-identity-server

Figure 2: An excerpt from a docker-compose.yml file that uses a Newman container to automatically run a Postman collection to apply a desired security contract on docker-compose up. Note! The required register-a3s-contract.postman_collection.json is mounted in as a volume and would be expected to be inside the ../../postman folder on the host machine in this example.