Microservice implementation of Federation Service for CanDIG v2
Based on CanDIG demo projects: OpenAPI variant service demo, Python Model Service.
- Connexion for implementing the API
- Bravado-core for Python classes from the spec
- Python 3
- Pytest
The federation_service can be installed in a py3.7+ virtual environment:
pip install -r requirements.txt
On initialization of the docker container, the server listed in .env as FEDERATION_SELF_SERVER will be registered. This is your own server.
To register other peer servers, use the /federation/v1/servers POST endpoint, described in federation.yaml. This call must be authorized with a site administrator access token from your own server (obtainable via CanDIGv2/site_admin_token.py). The authentication object should contain a valid JWT from the peer server's identity issuer (obtainable on the peer server likewise via CanDIGv2/site_admin_token.py). The Keycloak endpoint URL of the issuer should also be included. This will be compared with the iss claim in the JWT to make sure that they are the same.
## add server
curl -X "POST" "http://candig.docker.internal:5080/federation/v1/servers" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <site admin token>' \
-d $'{
"server": {
"id": "new-candig",
"url": "http://some-place.candig.ca",
"location": {
"name": "New CanDIG",
"province": "ON",
"province-code": "ca-on"
}
},
"authentication": {
"issuer": "https://some-place.candig.ca/auth/realms/candig",
"token": "<token from issuer>"
}
}'
In order for a service external to the CanDIG node to be registered as an external service, you must make sure that the tokens issued by the service's IDP contain the correct audience claim for the CanDIG node: you can find this audience in any CanDIG-issued token or in the CanDIG node's .env file, under KEYCLOAK_CLIENT_ID. Ask your OIDC administrator to do this, if needed.
To register the service, use the /federation/v1/external-service POST endpoint, described in federation.yaml. This call must be authorized with a site administrator access token from your own server (obtainable via CanDIGv2/site_admin_token.py). The object should contain a valid JWT from the external service's identity issuer, possibly a service token or a special user designated as the "service user". The Keycloak endpoint URL of the issuer should also be included. This will be compared with the iss claim in the JWT to make sure that they are the same.
## add external service
curl -X "POST" "http://candig.docker.internal:5080/federation/v1/external-service" \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <site admin token>' \
-d $'{
"service": "<external service name, unique in the system>",
"authentication": {
"token": "<service token>",
"issuer": "http://candig.docker.internal:8080/auth/realms/candig"
}
}'
You should use uwsgi to run the app for all functionalities to work as expected. The --master flag enables graceful reloading of the server without closing the socket and is useful to apply any changes to the code while developing. For more details, read the uwsgi documentation.
# Run Server
uwsgi federation.ini --master
# Reload server gracefully, replace <pid> with the uwsgi process ID
kill -HUP <pid>
Once the service is running, a Swagger UI can be accessed at : /federation/v1.
Tests can be run with pytest:
pytest tests/test_uniform_federation.py
However, the tests are best run inside the docker container, if you're running in the CanDIGv2 environment:
docker exec candigv2_federation_1 pytest
There is a documentation website with detailed information on how federated queries work and how they are tested.