Getting Started - Configure a Data Store
The bootstrap startup script (bootstrap-local-dms.ps1) creates a default data
store and provisions the database schema automatically. This page covers the
remaining step: creating API client credentials so you can authenticate and make
requests.
What the Bootstrap Created
Running bootstrap-local-dms.ps1 provisioned:
- A data store (PostgreSQL or SQL Server database) registered in the Configuration Service
- The Ed-Fi database schema provisioned via the
api-schema-toolsCLI
API client credentials are not created by the bootstrap unless you pass
-AddSmokeTestCredentials. Otherwise, you create them separately so you control
which vendor, claim set, and education organizations are associated with the
client.
Step 1: Create API Credentials
If you started the services with -AddSmokeTestCredentials, the bootstrap
script created the credentials for you and printed the key and secret at the end
of its output. Record them and continue with Step 2.
The Configuration Service returns the secret only once, so it can't be retrieved
later.
Otherwise, for local development, use the Get-SmokeTestCredential helper from the
repository's smoke test module. It creates a vendor and application in the
Configuration Service and returns a key and secret.
From the eng/docker-compose directory:
Import-Module ../smoke_test/modules/SmokeTest.psm1 -Force
$cred = Get-SmokeTestCredential -ConfigServiceUrl "http://localhost:8081"
Write-Host "Key: $($cred.Key)"
Write-Host "Secret: $($cred.Secret)"
Record the key and secret. You will need them to request API tokens.
Get-SmokeTestCredential creates a vendor named "Smoke Test Vendor" with an
application using the EdFiSandbox claim set, pre-associated with a data
store created by the bootstrap. It is intended for local development and
testing, not production deployments.
Get-SmokeTestCredential creates a new application on each call. It does
not retrieve existing credentials, and the generated secret cannot be recovered
afterward. It reuses the "Smoke Test Vendor" vendor if it already exists, but
the application name ("Smoke Test Application") must be unique for the vendor,
so running it a second time against the same environment fails. To obtain a
fresh credential, either pass a different -ApplicationName, or reset the local
stack (./bootstrap-local-dms.ps1 -d -v, then re-run it without flags). The
same applies if you started the services with -AddSmokeTestCredentials.
If you started with -AddSmokeTestCredentials, the bootstrap already associated
its credential with every school-year data store, so you can skip this note.
If you created year-specific data stores (for example, with -SchoolYearRange),
the default Get-SmokeTestCredential call above associates the client with only
the first data store, so requests to the other school-year routes return a
403. Create a credential for all of the data stores instead. The snippet uses a
different application name, so it works even if you already ran the call above:
# Get a Configuration Service admin token. This uses the local admin client
# that Get-SmokeTestCredential registers; Add-CmsClient reuses it if it exists.
Import-Module ../Dms-Management.psm1 -Force
Add-CmsClient -CmsUrl "http://localhost:8081" -ClientId "smoke-test-admin" -DisplayName "Smoke Test Administrator"
$adminToken = Get-CmsToken -CmsUrl "http://localhost:8081" -ClientId "smoke-test-admin"
# List the data stores and pass all of their IDs to the helper
$dataStores = @(Get-DataStore -CmsUrl "http://localhost:8081" -AccessToken $adminToken)
$dataStores | Select-Object id, name
$dataStoreIds = @($dataStores | ForEach-Object { [long]$_.id })
$cred = Get-SmokeTestCredential -ConfigServiceUrl "http://localhost:8081" `
-ApplicationName "Smoke Test Application (all data stores)" -DataStoreIds $dataStoreIds
Write-Host "Key: $($cred.Key)"
Write-Host "Secret: $($cred.Secret)"
The admin client's secret is a fixed development default in
Dms-Management.psm1. Use these helpers only for local development.
Step 2: Request an OAuth Token
Use the client credentials to obtain a bearer token from the Configuration Service:
$auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("<key>:<secret>"))
$token = Invoke-RestMethod -Method Post -Uri "http://localhost:8081/connect/token" `
-Headers @{ "Authorization" = "Basic $auth" } `
-ContentType "application/x-www-form-urlencoded" `
-Body @{
"grant_type" = "client_credentials"
}
A successful response returns a JSON object containing access_token,
expires_in, and token_type.
If you are using Keycloak as your identity provider, the token endpoint is
http://localhost:8045/realms/edfi/protocol/openid-connect/token. Keycloak also
requires the realm and client to be configured before tokens will be accepted by
the Ed-Fi API. See Identity Provider
Configuration for the
Keycloak token endpoint and setup instructions.
Step 3: Make an API Request
Use the token to call the Ed-Fi API:
Invoke-RestMethod -Uri "http://localhost:8080/api/data/ed-fi/schools" `
-Headers @{ Authorization = "Bearer $($token.access_token)" }
An empty array [] is a valid response. It means the data store is connected
and no schools have been loaded yet.
If you receive a 403 Authorization Denied response with the message "No
database instances are authorized for this client," the credentials you are
using were not linked to a data store when they were created. Ensure you are
using the key and secret from -AddSmokeTestCredentials or
Get-SmokeTestCredential, which associate the application with the data store
created by the bootstrap. If you created a
vendor or application manually through the Configuration Service, you must also
associate it with a data store before API requests will succeed. If you have
multiple data stores (for example, from -SchoolYearRange), see Multiple data
stores above — the credential must be
associated with every data store you intend to reach.
If you receive a 503 response with a message about database provisioning, run
bootstrap-local-dms.ps1 again from a clean state (./bootstrap-local-dms.ps1 -d -v) — the data store exists but the schema was not provisioned.