python-rasenmaeher-api
This application can be configured with environment variables. Below is a example list of available variables. You can find all available variables here https://github.com/pvarki/python-rasenmaeher-api/blob/main/src/rasenmaeher_api/rmsettings.py.
| ENV VAR | Default value | Info / Usage |
|---|---|---|
| RM_PORT | 8000 | Docker API listen port |
| RM_WORKERS_COUNT | 2 | Number of uvicorn workers |
| RM_RELOAD | False | Reload service on code change |
| RM_ENVIRONMENT | dev | Run dev / prod environment |
| RM_CFSSL_HOST | None | CFSSL host url |
| RM_CFSSL_PORT | None | CFSSL service port |
| RM_KEYCLOAK_SERVER_URL | None | Keycloak server url (http://1234:8080/auth) |
| RM_KEYCLOAK_CLIENT_ID | None | Keycloak client id |
| RM_KEYCLOAK_REALM_NAME | None | Keycloak realm name |
| RM_KEYCLOAK_CLIENT_SECRET | None | Keycloak secert |
| RM_LDAP_CONN_STRING | None | LDAP conn string |
| RM_LDAP_USERNAME | None | LDAP username |
| RM_LDAP_CLIENT_SECRET | None | LDAP connection secret |
| RM_SQLITE_FILEPATH_PROD | /opt/rasenmaher/persistent/sqlite/rm_db.sql | location for sqlite database file in "prod" |
| RM_SQLITE_FILEPATH_DEV | /tmp/rm_db.sql | location for sqlite database file in "dev", local development |
You can create .env file in the root directory and place all environment variables here.
All environment variables should start with RM_ prefix.
For example if you see in your "rasenmaeher_api/rmsettings.py" a variable named like random_parameter, you should provide the "RM_RANDOM_PARAMETER" variable to configure the value. This behaviour can be changed by overriding env_prefix in rasenmaeher_api.rmsettings.RMSettings.model_config.
An example of .env file:
`bash
RM_RELOAD="True"
RM_PORT="8000"
RM_ENVIRONMENT="dev"
`
You can read more about BaseSettings class here: https://pydantic-docs.helpmanual.io/usage/settings/
Integration APIs are always https in port 4625. Default location for the manifest is /pvarki/kraftwerk-rasenmaeher-init.json
`json
{
"dns": "sleepy-sloth.pvarki.fi",
"products": {
"tak": "tak.sleepy-sloth.pvarki.fi",
"ptt": "ptt.sleepy-sloth.pvarki.fi"
}
}
`
| State | Method | URI | Request JSON | Response JSON | Api description . |
|---|---|---|---|---|---|
| Dummy | GET | /api/v1/enroll/status/{work_id} | NA | {'status':'None/Processing/Denied/WaitingForAcceptance/ReadyForDelivery/Delivered'} | Check the situation of enrollment process, None = no enrollment started, this work_id is free to use. |
| Dummy | POST | /api/v1/enroll/init | {'work_id':'{work_id}'} | {'work_id':'{work_id}', 'id_hash':{id_string} } | Start service access enrollment for given {work_id} |
| Dummy | GET | /api/v1/enroll/deliver/{id_string} | NA | {'dl_link':"{http://here.be/zip}"} | Deliver download link for enrollment zip |
| Dummy | POST | /api/v1/enroll/accept | { 'permit_string':'{permit_string}, 'id_hash':'{id_hash}' '} | { 'access':'granted/denied/None', 'work_id':'{work_id}' } | Accept the enrollment request |
| Testing | POST | /api/v1/product/sign_csr | { 'TO':'DO'} | { 'TO':'DO'} | Accept the enrollment request |
| Testing | POST | /api/v1/enroll/accept | { 'permit_string':'{permit_string}, 'id_hash':'{id_hash}' '} | { 'access':'granted/denied/None', 'work_id':'{work_id}' } | Accept the enrollment request |
# REQUEST A NEW CERTIFICATE USING CSR (requires cfssl backend for the api container)
`curl -L -H "Content-Type: application/json" -d '{"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBUjCB+QIBADBqMQswCQYDVQQGEwJVUzEUMBIGA1UEChMLZXhhbXBsZS5jb20x\nFjAUBgNVBAcTDVNhbiBGcmFuY2lzY28xEzARBgNVBAgTCkNhbGlmb3JuaWExGDAW\nBgNVBAMTD3d3dy5leGFtcGxlLmNvbTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IA\nBK/CtZaQ4VliKE+DLIVGLwtSxJgtUKRzGvN1EwI3HRgKDQ3l3urBIzHtUcdMq6HZ\nb8jX0O9fXYUOf4XWggrLk1agLTArBgkqhkiG9w0BCQ4xHjAcMBoGA1UdEQQTMBGC\nD3d3dy5leGFtcGxlLmNvbTAKBggqhkjOPQQDAgNIADBFAiAcvfhXnsLtzep2sKSa\n36W7G9PRbHh8zVGlw3Hph8jR1QIhAKfrgplKwXcUctU5grjQ8KXkJV8RxQUo5KKs\ngFnXYtkb\n-----END CERTIFICATE REQUEST-----\n"}' 127.0.0.1:8000/api/v1/takreg | jq`
# REQUEST A NEW CERTIFICATE WITHOUT CSR (requires cfssl backend for the api container)
`curl -L -H "Content-Type: application/json" -d '{ "request": {"hosts":["harjoitus1.pvarki.fi"], "names":[{"C":"FI", "ST":"Jyvaskyla", "L":"KeskiSuomi", "O":"harjoitus1.pvarki.fi"}], "CN": "harjoitus1.pvarki.fi"}, "bundle":true, "profile":"client"}' 127.0.0.1:8000/takreg | jq`
# LIST CFSSL CRL LIST
`curl -L -H "Content-Type: application/json" -d '{ "request": {"hosts":["harjoitus1.pvarki.fi"], "names":[{"C":"FI", "ST":"Jyvaskyla", "L":"KeskiSuomi", "O":"harjoitus1.pvarki.fi"}], "CN": "harjoitus1.pvarki.fi"}, "bundle":true, "profile":"client"}' 127.0.0.1:8000/takreg | jq`
The cfssl used behind API listens this kind of stuff https://github.com/cloudflare/cfssl/blob/master/doc/api/endpoint_newcert.txt
# Enrollment - Enroll a new work_id
`curl -H "Content-Type: application/json" -d '{"work_id":"porakoira666"}' http://127.0.0.1:8000/api/v1/enrollment/init`
# Enrollment - Check the status and availability of work_id
`curl http://127.0.0.1:8000/api/v1/enrollment/status/koira`
- # Enrollment - Request the download link using the provided work_id_hash
`curl http://127.0.0.1:8000/api/v1/enrollment/deliver/zxzxzxzxzxzxzxxzzx`- # Enrollment - Accept enrollment using permit_str
`curl -H "Content-Type: application/json" -d '{"enroll_str":"zxzxzxzxzxzxzxxzzx", "permit_str":"PaulinTaikaKaulinOnKaunis_PaulisMagicPinIsBuuutiful!11!1"}' http://127.0.0.1:8000/api/v1/enrollment/accept`- # Enrollment - Set download link for enrollment
`curl -H "Content-Type: application/json" -d '{"download_link":"https://kuvaton.com","enroll_str":"zxzxzxzxzxzxzxxzzx", "permit_str":"PaulinTaikaKaulinOnKaunis_PaulisMagicPinIsBuuutiful!11!1"}' http://127.0.0.1:8000/api/v1/enrollment/config/set-dl-link`- # Enrollment - Set state for enrollment
`curl -H "Content-Type: application/json" -d '{"state":"ReadyForDelivery","enroll_str":"zxzxzxzxzxzxzxxzzx", "permit_str":"PaulinTaikaKaulinOnKaunis_PaulisMagicPinIsBuuutiful!11!1"}' http://127.0.0.1:8000/api/v1/enrollment/config/set-state`- # Enrollment - Add new permit_str
`curl -H "Content-Type: application/json" -d '{"permissions_str":"all", "new_permit_hash":"too_short","permit_str":"PaulinTaikaKaulinOnKaunis_PaulisMagicPinIsBuuutiful!11!1"}' http://127.0.0.1:8000/api/v1/enrollment/config/add-manager`
For more controlled deployments and to get rid of "works on my computer" -syndrome, we always make sure our software works under docker.
It's also a quick way to get started with a standard development environment.
We need buildkit:
export DOCKER_BUILDKIT=1
And also the exact way for forwarding agent to running instance is different on OSX:
export DOCKER_SSHAGENT="-v /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock -e SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock"
and Linux:
export DOCKER_SSHAGENT="-v $SSH_AUTH_SOCK:$SSH_AUTH_SOCK -e SSH_AUTH_SOCK"
Build image, create container and start it:
docker build --ssh default --target devel_shell -t rasenmaeher_api:devel_shell . docker create --name rasenmaeher_api_devel -v `pwd`":/app" -it `echo $DOCKER_SSHAGENT` -v /var/run/docker.sock:/var/run/docker.sock rasenmaeher_api:devel_shell docker start -i rasenmaeher_api_devel
Hooks are executed by prek, a drop-in pre-commit replacement that reads the same
.pre-commit-config.yaml. If working in Docker instead of native env you need to run the
checks in docker too:
docker exec -i rasenmaeher_api_devel /bin/bash -c "prek install --install-hooks" docker exec -i rasenmaeher_api_devel /bin/bash -c "prek run --all-files"
You need to have the container running, see above. Or alternatively use the docker run syntax but using the running container is faster:
docker run --rm -it -v `pwd`":/app" rasenmaeher_api:devel_shell -c "prek run --all-files"
You can use the devel shell to run py.test when doing development, for CI use the "tox" target in the Dockerfile:
docker build --ssh default --target tox -t rasenmaeher_api:tox . docker run --rm -it --network host -v /var/run/docker.sock:/var/run/docker.sock -v `pwd`":/app" `echo $DOCKER_SSHAGENT` rasenmaeher_api:tox
NOTE: This will not work from the git submodule directory in the integration repo, docker tests must be run from the original repo.
There's a "production" target as well for running the application, remember to change that architecture tag to arm64 if building on ARM:
docker build --ssh default --target production -t rasenmaeher_api:amd64-latest . docker run --rm -it --name rasenmaeher_openapijson rasenmaeher_api:amd64-latest rasenmaeher_api openapi docker run -it --name rasenmaeher_api rasenmaeher_api:amd64-latest
There is also a specific target for just dumping the openapi.json:
docker build --ssh default --target openapi -t rasenmaeher_api:amd64-openapi . docker run --rm -it --name rasenmaeher_openapijson rasenmaeher_api:amd64-openapi
TLDR:
change to a branch:
git checkout -b my_branch
install uv: https://docs.astral.sh/uv/getting-started/installation/
Install project deps and pre-commit hooks (via prek):
uv sync source .venv/bin/activate prek install --install-hooks prek run --all-files
Ready to go.
Remember to activate your virtualenv whenever working on the repo, this is needed because the mypy hook uses the "system" python for now (because reasons).
Pipeline can pass a public-key whose private key is used to sign JWTs to access RM API with environment variable $EXTERNAL_JWT_PUBKEY_B64. The public key should be base64-encoded to avoid issues with newlines and such when the key is passed through the system.
Export a previously generated key to the container:
export EXTERNAL_JWT_PUBKEY_B64=$(cat ~/p/jwt-test/public_key.pub | base64) rmlocal up --build
Generate a token and set it in the environment TOKEN. The JWT should have the claim anon_admin_session set to true. Use the token in the API call:
curl -X POST --insecure https://localmaeher.dev.pvarki.fi:4439/\
api/v1/token/code/generate -H 'Content-type: application/json' \
-H "Authorization: Bearer $TOKEN" \
-d '{"claims": {"anon_admin_session": true}}'
Versioning is handled with bump-my-version. To increment, use bump-my-version bump <patch/minor/major>.
You can use bump-my-version show-bump to see how each option would affect the version.
Federation orchestration is specified only for TAK Servers because there is urgent need for it and this compose based deployment is being deprecated. A generic federation orchestration system will be specified for https://github.com/opendefence/core
A service whose JWT signing public key RMAPI trusts can call:
POST /api/v1/federation/tak/trustPOST /api/v1/federation/tak/outgoing
Both require Authorization: Bearer <JWT> and accept exactly
{"remote_base": "fast-flounder.solution.dev.pvarki.fi"}. The peer is a full
DNS hostname with an optional HTTPS port (:4439 for development). Schemes,
paths, credentials, IP literals, tak. prefixes, unknown fields and
self-federation are rejected. Hostnames are lowercased and port 443 is omitted.
The first label must fit TAK's 30-character display-name limit. Cross-domain
peers are allowed.
The caller runs trust on both servers, waits for both successful responses, and calls outgoing on exactly one. The caller owns this coordination; RMAPI does not elect a server or initiate a reverse connection.
Use multikeyjwt 1.8 or later to issue a fresh token for each request:
from uuid import uuid4
from multikeyjwt import Issuer
token = Issuer.singleton().issue(
{
"iss": "federation-orchestrator",
"sub": "federation-orchestrator",
"aud": "rasenmaeher:tak-federation:localmaeher.dev.pvarki.fi",
"nonce": str(uuid4()),
"federation_action": "trust",
"remote_base": "fast-flounder.solution.dev.pvarki.fi",
},
lifetime=60,
)
The signing key belongs to the external service. Provision only its PEM public
key through JWT_PUBKEY_PATH or EXTERNAL_JWT_PUBKEY_B64 (Compose maps
RMAPI_EXTERNAL_JWT_PUBKEY_B64). Restart workers after key changes; removing
the environment variable alone does not remove a previously persisted
external.pub. Issuer and subject are attribution; signing-key trust is not
bound to a particular issuer name.
The audience must be one exact string for the target deployment's manifest
dns; it contains no HTTPS port. Audience arrays are rejected. iss and
sub must be nonempty strings. Integer iat, nbf and exp are all
required, with iat <= nbf < exp and at most 300 seconds from issue to expiry.
Clocks must be synchronized; verification uses zero clock leeway. The signed
action must match the route, and the canonical signed peer must match the body,
including any nondefault HTTPS port. Browser cookies and ordinary session
tokens cannot authorize these routes.
Every nonce is a UUID, normalized before consumption in the existing database. Replays and concurrent duplicate requests are rejected before dispatch. After an authorized attempt, retry with a fresh token and nonce, even if the product request failed or timed out. TAK's idempotent readbacks make the desired-state retry safe.
RMAPI synchronously calls only manifest product tak using its product mTLS
identity, a fixed internal federation path, no redirects and a 30-second budget.
It never forwards the external JWT. The TAK integration must provide both
internal federation endpoints; deploy that implementation before using these
public routes. Local development HTTPS uses port 4439 and the development CA;
use a verified CA bundle when calling it.
HTTP 200 confirms a validated configuration readback, including no-ops;
changed distinguishes changes from existing configuration. Trust returns the
CA fingerprint and both default group directions. Outgoing returns the observed
connection status (possibly null); success does not prove traffic delivery or
persistence across restart.
Failures use detail with code, stage, message and
may_have_changed. Statuses are 403 for JWT/replay rejection, 422 for input,
404 when TAK is absent, 409 for prerequisite/configuration conflicts, 502 for
upstream or invalid responses, 503 for unavailable local resources/lock state,
and 504 for timeouts. A timeout may follow a successful write. Verified actor,
issuer, operation, peer, nonce and result are audited without logging the JWT.
Upgrading to multikeyjwt 1.8 also changes existing authentication: any
Authorization header takes precedence over cookies, including invalid/empty
headers. Cookie clients must omit unusable headers. Optional JWT authentication
returns None on invalid credentials; existing mTLS fallback remains usable.