From 39f2690575b526e603c11c295875342aa35b8ab4 Mon Sep 17 00:00:00 2001 From: Aldrian Harjati Date: Mon, 16 Oct 2023 16:08:33 -0400 Subject: [PATCH] add more details/instructions --- README.md | 145 ++++++++++++++++++++++++++++++++++-- images/sbl_project_svcs.png | Bin 0 -> 34899 bytes 2 files changed, 140 insertions(+), 5 deletions(-) create mode 100644 images/sbl_project_svcs.png diff --git a/README.md b/README.md index 2420ffd..307dbc6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # User and Financial Institutions Management API This app communicates with Keycloak to provide some user management functionality, as well as serving as `Institutions API` to retrieve information about institutions. +--- +## Contact Us +If you have an inquiry or suggestion for the user and financial institutions management API or any SBL related code, please reach out to us at + --- ### Dependencies - [Poetry](https://python-poetry.org/) is used as the package management tool. Once installed, just running `poetry install` in the root of the project should install all the dependencies needed by the app. @@ -8,18 +12,37 @@ This app communicates with Keycloak to provide some user management functionalit - [jq](https://jqlang.github.io/jq/download/) is used for parsing API responses in the curl command examples shown below --- -## Pre-requesites +## Pre-requisites [SBL Project Repo](https://github.com/cfpb/sbl-project) contains the `docker-compose.yml` to run the ancillary services. - Not all services need to run, this module `regtech-user-fi-management` is part of the docker compose file, which doesn't need to be ran in docker for local development. - Issuing `docker compose up -d pg keycloak` would start the necessary services (postgres, and keycloak) +```bash +$ cd ~/Projects/sbl-project +$ docker compose up -d pg keycloak +[+] Running 3/3 + ⠿ Network sbl-project_default Created 0.2s + ⠿ Container sbl-project-pg-1 Started 2.6s + ⠿ Container sbl-project-keycloak-1 Started 13.4s +``` +![Docker](images/sbl_project_svcs.png) --- ## Running the app -Once the [Dependencies](#dependencies), and [Pre-requesites](#pre-requesites) have been satisfied, we can run the app by going into the `src` folder, then issue the poetry run command: +Once the [Dependencies](#dependencies), and [Pre-requisites](#pre-requisites) have been satisfied: +- All dependencies installed +- Postgres and keycloak services started + +we can run the app by going into the `src` folder, then issue the poetry run command: ```bash -cd src -poetry run uvicorn main:app --reload --port 8888 +$ poetry run uvicorn main:app --reload --port 8888 +INFO: Will watch for changes in these directories: ['/Projects/regtech-user-fi-management/src'] +INFO: Uvicorn running on http://127.0.0.1:8888 (Press CTRL+C to quit) +INFO: Started reloader process [37993] using StatReload +INFO: Started server process [37997] +INFO: Waiting for application startup. +INFO: Application startup complete. ``` + ### Local development notes - [.env.template](.env.template) is added to allow VS Code to search the correct path for imports when writing tests, just copy the [.env.template](.env.template) file into `.env` file locally - [src/.env.template](./src/.env.template) is added as the template for the app's environment variables, appropriate values are already provided in [.env.local](./src/.env.local) for local development. If `ENV` variable with default of `LOCAL` is changed, copy this template into `src/.env`, and provide appropriate values, and set all listed empty variables in the environment. @@ -41,6 +64,17 @@ curl 'localhost:8880/realms/regtech/protocol/openid-connect/token' \ --data-urlencode 'client_id=regtech-client' | jq -r '.access_token' ``` +For local development, we can retrieve the access token and store it to local variable then use this variable on API calls. +```bash +export RT_ACCESS_TOKEN=$(curl 'localhost:8880/realms/regtech/protocol/openid-connect/token' \ +-X POST \ +-H 'Content-Type: application/x-www-form-urlencoded' \ +--data-urlencode 'username=user1' \ +--data-urlencode 'password=user' \ +--data-urlencode 'grant_type=password' \ +--data-urlencode 'client_id=regtech-client' | jq -r '.access_token') +``` + --- ## Functionalities There are 2 major functionalities provided by this app, one serves as the integration with Keycloak, and the other to integrate with Institutions database to show institutions' information. Below are the routers for these functionalities. As mentioned above, authentication is required to access the endpoints. @@ -110,13 +144,114 @@ There are 2 major functionalities provided by this app, one serves as the integr ``` For both these routers, the needed roles to access each endpoint is decorated with the `@requires` decorator, i.e. `@requires(["query-groups", "manage-users"])`. Refer to [institutions router](./src/routers/institutions.py) for the decorator example; these roles corresponds to Keycloak's roles. +--- +## Example of Local Development Flow +- Install [Poetry](https://python-poetry.org/), [Docker](https://www.docker.com/) and [jq](https://jqlang.github.io/jq/download/) +- Checkout [SBL Project Repo](https://github.com/cfpb/sbl-project) and [SBL User and Financial Institution Management API Repo](https://github.com/cfpb/regtech-user-fi-management) +- Open a terminal, and run keycloak and postqres +```bash +# go to sbl-project repo root directory +cd ~/Projects/sbl-project + +# bring up postgres and keycloak +docker compose up -d pg keycloak +[+] Running 3/3 + ⠿ Network sbl-project_default Created 0.2s + ⠿ Container sbl-project-pg-1 Started 2.6s + ⠿ Container sbl-project-keycloak-1 Started 13.4s +``` + +- Open another terminal, and run keycloak and postqres +```bash +# go to regtech-user-fi-management's src directory +cd ~/Projects/regtech-user-fi-management/src + +# run local api server +poetry run uvicorn main:app --reload --port 8888 + +INFO: Will watch for changes in these directories: ['/Users/harjatia/Projects/regtech-user-fi-management/src'] +INFO: Uvicorn running on http://127.0.0.1:8888 (Press CTRL+C to quit) +INFO: Started reloader process [42182] using StatReload +INFO: Started server process [42186] +INFO: Waiting for application startup. +INFO: Application startup complete. +INFO: 127.0.0.1:51374 - "GET /v1/admin/me HTTP/1.1" 200 OK +``` + +- Using first terminal or new terminal, run and test API Calls +```bash +# Retrieve and store token key +export RT_ACCESS_TOKEN=$(curl 'localhost:8880/realms/regtech/protocol/openid-connect/token' \ + -X POST \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode 'username=admin1' \ + --data-urlencode 'password=admin' \ + --data-urlencode 'grant_type=password' \ + --data-urlencode 'client_id=regtech-client' | jq -r '.access_token') + +# test token key +curl localhost:8888/v1/admin/me -H "Authorization: Bearer ${RT_ACCESS_TOKEN}" | jq -r '.' + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 801 100 801 0 0 7545 0 --:--:-- --:--:-- --:--:-- 8010 +{ + "claims": { + "exp": 1697482762, + "iat": 1697482462, + "jti": "3380a7bb-765b-4197-a500-19eb424518ce", + "iss": "http://localhost:8880/realms/regtech", + "aud": [ + "realm-management", + "account" + ], + "sub": "631dbab3-4dcf-46bf-b283-55c18a3722e6", + "typ": "Bearer", + "azp": "regtech-client", + "session_state": "c8d4b4c8-3d3f-41b3-aebc-b4cab3b314eb", + "allowed-origins": [ + "*" + ], + "realm_access": { + "roles": [ + "offline_access", + "uma_authorization", + "default-roles-regtech" + ] + }, + "resource_access": { + "realm-management": { + "roles": [ + "manage-users", + "query-groups" + ] + }, + "account": { + "roles": [ + "manage-account" + ] + } + }, + "scope": "email profile", + "sid": "c8d4b4c8-3d3f-41b3-aebc-b4cab3b314eb", + "email_verified": false, + "preferred_username": "admin1", + "given_name": "", + "family_name": "" + }, + "name": "", + "username": "admin1", + "email": "", + "id": "631dbab3-4dcf-46bf-b283-55c18a3722e6", + "institutions": [] +} +``` + --- ## API Documentation This module uses the [FastAPI](https://fastapi.tiangolo.com/) framework, which affords us built-in [Swagger UI](https://swagger.io/tools/swagger-ui/), this can be accessed by going to `http://localhost:8888/docs` - _Note_: The `Try It Out` feature does not work within the Swagger UI due to the use of `AuthenticationMiddleware` --- - ## Open source licensing info 1. [TERMS](TERMS.md) diff --git a/images/sbl_project_svcs.png b/images/sbl_project_svcs.png new file mode 100644 index 0000000000000000000000000000000000000000..fa969d4e1ff0fb158a9a6b607b7f187d1990bbb6 GIT binary patch literal 34899 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