This chapter discusses secrets management and how to use it.
<details open markdown="block"> <summary> Page Contents </summary> 1. TOC </details>Secret management software allows users to securely store sensitive data such as passwords, keys and tokens in a central location with strict access controls. Secret managers can set secrets to expire, be auto-generated and, in case of a security breach, be revoked. This functionality enables Stardog administrators to secure their server and database passwords outside of Stardog and manager them without any modifications to your Stardog configuration.
Stardog Knowledge Catalog integrates with the following secret managers to store usernames and password for catalog metadata providers:
Hashicorp Vault
AWS Secrets Manager
Azure Key Vault
Google Secret Manager
Stardog currently supports secrets stored as a single string value for a password or a serialized JSON object with username and password attributes. Catalog metadata providers that are configured to use a secret manager will read in the secret values at runtime.
To use a secret with a catalog metadata provider you first add your secret manager to the Knowledge Catalog by inserting configuration data into the tag:stardog:api:catalog:crypt:external named graph in your catalog database.
Each secret manager requires different properties.
Hashicorp Vault
| Property | Description |
|---|---|
| http://www.w3.org/1999/02/22-rdf-syntax-ns#type | tag:stardog:api:catalog:crypt:Vault |
| tag:stardog:api:catalog:crypt:url | vault url |
| tag:stardog:api:catalog:crypt:token | access token |
AWS Secrets Manager
| Property | Description |
|---|---|
| http://www.w3.org/1999/02/22-rdf-syntax-ns#type | tag:stardog:api:catalog:crypt:Aws |
| tag:stardog:api:catalog:crypt:accessKey | client access key |
| tag:stardog:api:catalog:crypt:secretKey | client secret key |
| tag:stardog:api:catalog:crypt:awsRegion | AWS region code |
Azure Key Vault
| Property | Description |
|---|---|
| http://www.w3.org/1999/02/22-rdf-syntax-ns#type | tag:stardog:api:catalog:crypt:Azure |
| tag:stardog:api:catalog:crypt:url | key vault url |
| tag:stardog:api:catalog:crypt:tenantId | azure tenant id |
| tag:stardog:api:catalog:crypt:clientId | azure client id |
| tag:stardog:api:catalog:crypt:clientSecret | azure client secret |
Google Secret Manager
| Property | Description |
|---|---|
| http://www.w3.org/1999/02/22-rdf-syntax-ns#type | tag:stardog:api:catalog:crypt:Google |
| tag:stardog:api:catalog:crypt:projectId | google project id |
| tag:stardog:api:catalog:crypt:apiKey | google api key |
Here’s an example of adding a Hashicorp Vault secret manager:
insert data {
graph <tag:stardog:api:catalog:crypt:external> {
<urn:hashi> a <tag:stardog:api:catalog:crypt:Vault> ;
rdfs:label "HashiCorp Vault" ;
<tag:stardog:api:catalog:crypt:token> "xxxxxxxxxxxxxxxxxxxx" ;
<tag:stardog:api:catalog:crypt:url> "http://myhost.com:8200/v1"
}
}
Once you have added a secret manager configuration you can then begin to add external secrets to your metadata provider configurations.
Currently, to save metadata provider credentials with external secrets you have to use the catalog HTTP API.
POST http://<stardog address>:5820/admin/catalog/credentials
Example JSON body:
{
"username": "{username}",
"password": "{password}",
"label": "Test Credential 1",
"secret": {
"manager": "urn:vault",
"id": "secret/data/sql-user",
"version": "1"
}
}
Catalog Credential Attributes:
| Attribute | Description |
|---|---|
| username | A valid username or the {username} variable that will be replaced with a secret value |
| password | A valid password or the {password} variable that will be replaced with a secret value |
| token | Used for systems that take an API key or bearer access token or the {password} variable that will be replaced with a secret value |
| clientId | Used for systems that support OAuth |
| clientSecret | Used for systems that support OAuth or the {password} variable that will be replaced with a secret value |
| label | A description for the credential |
| secret.manager | The IRI for a secret manager configuration |
| secret.id | The path or key for a secret |
| secret.version | A version for a secret if supported by target secret manager |
After you POST a credential to the catalog credential store you will be returned an access key that you can then use in a catalog metadata provider configuration just like any other stored provider credential.
{"accessKey":"89f7ffff-7db7-4cb8-9a77-d98c3b1e8b1d"}
The secret will be retrieved and any secret variables will be replaced with the actual secret values when the provider runs on its scheduled time.