bcda-ssas-app

System-to-System Authentication Service (SSAS)

The SSAS can be run as a standalone web service or embedded as a library.

Code Organization

The outline below shows the physical directory structure of the code, with package names highlighted. The service package contains a standalone http service that presents the authorization library via two http servers, one for admin tasks and one for authorization tasks.

Imports always go up the directory tree from leaves; that is, parents do not import from their children. Children may import from their siblings. In short, the ssas and cfg packages must not import from packages in the service directory.

• ssas
  • cfg
    • configuration management; cfg should not import from ssas packages
  • service
    • admin
      • contains the REST API for managing the service implementation
    • main
      • cli for running servers and some admin tasks
    • public
      • contains the rest API for authorization services

Configuration

Values below are either indicated by Required, SSAS, BCDA, or a combination.

• Required values must be present in the docker-compose.*.yml files.
• Some values are primarily for the use of the BCDA API, and are only used by SSAS for testing purposes.
• Some values are only used by the BCDA API; they are listed for reference.

Very long keys have been split across two rows for formatting purposes.

Some variables below have a note indicating their name should be changed. These changes serve to make the names consistent with established naming patterns and/or to clarify their purpose. They should be made after we complete the initial deployments to AWS envs so that we don't have to change all of our existing deployment checklists in a short timeframe.

Development Setup

Install and Use Pre-commit

Anyone committing to this repo must use the pre-commit hook to lower the likelihood that secrets will be exposed.

Step 1: Install pre-commit

You can install pre-commit using the MacOS package manager Homebrew:

brew install pre-commit

Other installation options can be found in the pre-commit documentation.

Step 2: Install the hooks

You will need to manually install goimports for the following commands to function:

go install golang.org/x/tools/cmd/goimports@latest

Run the following command to install the hook:

pre-commit install

This will download and install the pre-commit hooks specified in .pre-commit-config.yaml, which includes gitleaks for secret scanning and go-imports to ensure that any added, copied, or modified go files are formatted properly.

Go Modules

The project uses Go Modules allowing you to clone the repo outside of the $GOPATH. This also means that running go get inside the repo will add the dependency to the project, not globally.

Build

Build all the code and containers with make docker-bootstrap. Alternatively, docker-compose up ssas will build and run the SSAS by itself. Note that SSAS needs the db container to be running as well.

Bootstrapping CLI

SSAS currently has a simple CLI intended to make bootstrapping tasks and manual testing easier to accomplish. The CLI will only run one command at a time; commands do not chain.

The sequence of commands needed to bootstrap the SSAS into a new environment is as follows:

1. migrate, which will build or update the tables
2. add-fixture-data, which adds the admin group and seeds minimal data for smoke Testing
3. new-admin-system, which adds an admin system and returns its client_id
4. reset-secret, which replaces the secret associated with a client_id and returns that new secret
5. start, which starts the servers and the token blacklist cache

You will need the admin client_id and secret to use the service's admin endpoints.

Note that to initialize our docker container, we use migrate-and-start, which combines the first three of the steps above with some conditional logic to make sure we're running in a development environment. This command should most likely not be used elsewhere.

Test

The SSAS can be tested by running make unit-test. You can also use the repo-wide command make test, which will run tests against the entire repo, including the SSAS code. Some tests are designed to be only run as needed, and are excluded from make by a build tag. To include one of these test suites, follow the instructions at the top of the test file.

Integration Testing

To run postman tests locally:

Build and startup the required containers. Building with docker-compose up first will significantly improve the performance of the following steps.

docker-compose up
docker-compose stop
docker-compose up -d db
docker-compose up ssas

If this is the first time you've started the containers, set up your database tables and seed them with sample group and systems:

make load-fixtures

point your browser at one of the following ports, or use the postman test collection in tests.

• public server: 3103
• admin server: 3104
• forwarding server: 3105

Goland IDE

To run a test suite inside of Goland IDE, edit its configuration from the Run menu and add values for all necessary environmental variables. It is also possible to run individual tests, but that may require configurations for each test.

Docker Fun

To get postgres dump of schema (replace PASSHERE with password)

docker run --rm --network bcda-ssas-app_default -e PGPASSWORD=PASSHERE -it postgres pg_dump -s -h bcda-ssas-app_db_1 -d bcda -U postgres > schema.sql

To reset a secret by client id:

docker-compose run --rm ssas sh -c 'ssas --reset-secret --client-id=[client_id]'

To list all active IPs from the connected database:

docker-compose run --rm ssas sh -c 'ssas --list-ips'

Swagger Documentation

The admin server has Swagger documentation. To access:

1. Make sure it's been built (the container will stop after a few seconds when the documentation is ready)

   docker-compose up documentation

2. Make sure the ssas container is running

   docker-compose up ssas

3. Access Swagger in your browser: http://localhost:3104/swagger