REST connector
Read scan credentials from any PAM or secret store with an HTTP API by describing its sign-in and fetch requests in the provider file, with an example for ManageEngine PAM360 and a note on Delinea Secret Server.
REST connector
The REST connector (type: rest) reads a secret from any PAM or secret store that has an HTTP API. You describe two requests in the provider file, an optional sign-in and the fetch, and the reference supplies the values for that one secret.
Reference
pam://<name>/<key>=<value>/<key>=<value>[#password|#username]
pam://rest/<name>/<key>=<value>/...<name> is the provider's name in the file. Each key=value fills the {{key}} placeholder in the fetch templates. A key that no template uses is refused, and so are the reserved keys api_user, api_key, basic and token. Percent-encode values that hold /, #, ? or %.
Settings
| Setting | Meaning |
|---|---|
url | Base address, for example https://pam.example.internal. |
api_user, api_key | The connector's own credentials. api_key is env:// or file://. Used as {{api_user}}, {{api_key}}, and {{basic}} (Base64 of user:key). |
token_path | Set it to add a sign-in step. Leave it out when the API takes a key on every request. |
token_method | POST (default), GET or PUT. |
token_body | json (default), form, or form-b64 (user and key Base64-encoded first). |
token_body_template | The sign-in body, with {{api_user}} and {{api_key}}. Default for json: {"Username":"{{api_user}}","Password":"{{api_key}}"}; for forms: grant_type=password&username={{api_user}}&password={{api_key}}. |
token_json_path | Where the token is in the sign-in answer, for example access_token. |
token_ttl | How long a token is reused (default 4m). On a 401 the runner signs in again once. |
fetch_method | GET (default), POST or PUT. |
fetch_path | The request path, with placeholders, for example /api/v1/secrets/{{id}}/fields/{{field}}. No query string here. |
fetch_query | The query string, for example env={{env}}. |
fetch_body_template, fetch_content_type | A body for POST/PUT, JSON (default) or application/x-www-form-urlencoded. |
auth_header | Name: value, for example Authorization: Bearer {{token}} or X-API-Key: {{api_key}}. Default with a sign-in step: Authorization: Bearer {{token}}. |
password_json_path | Where the secret is in the answer: a dotted path where numbers index arrays (data.items.0.value), or $ when the whole answer is the value (a JSON string, or plain text). |
username_json_path | Where the user name is, for #username. |
success_json_path, error_json_path | For APIs that answer 200 with a failure inside: the flag (false, 0, "failed" and similar mean failure) and the message to show. |
Fetch templates may also use {{reason}} (the provider's reason, or Safeguard scan <scan> on <runner>), {{scan_ref}}, {{runner}} and {{target}}, so the PAM's own audit can record which scan asked. A reference key of the same name takes precedence.
Every value is escaped for where it lands (JSON string, URL path segment, query value, form value, header) in a single pass, so a reference cannot add a field, change the path, or inject a header. Templates come only from the provider file. Redirects are not followed, so a token or key is never sent to another address.
Delinea Secret Server
Secret Server has its own provider type, delinea, which does what this example does with fewer settings. See Delinea Secret Server. Use this recipe when you need to change the request, for example to send a comment with the read.
Written from Delinea Secret Server's public REST API (OAuth2 password grant, then the secret field endpoint). Check the paths against your Secret Server version and test with safeguard secrets test before relying on it.
providers:
- name: ss-rest
type: rest
url: https://secretserver.example.internal/SecretServer
api_user: svc-safeguard # a Secret Server application account
api_key: file:///etc/safeguard/delinea-password
token_path: /oauth2/token
token_body: form # grant_type=password&username=...&password=...
token_json_path: access_token
fetch_method: GET
fetch_path: /api/v1/secrets/{{id}}/fields/{{field}}
password_json_path: $ # the endpoint answers with the field value itself
ca_cert: /etc/safeguard/internal-root-ca.pem
allowed_refs:
- "id=1201/field=password"
- "id=1202/field=password"Reference: pam://ss-rest/id=1201/field=password (the secret's id and the field's slug, for example password or username).
For a secret that requires a comment, Secret Server has a restricted field endpoint that takes the comment in a POST body. With it, the comment can name the scan:
fetch_method: POST
fetch_path: /api/v1/secrets/{{id}}/restricted/fields/{{field}}
fetch_body_template: '{"comment":"{{reason}}"}'Secrets that need check-out, approval or a double lock are not read by this configuration.
Example: ManageEngine PAM360
Written from PAM360's public REST API (an API user's AUTHTOKEN header, resource and account ids). Test against your instance before relying on it.
providers:
- name: pam360
type: rest
url: https://pam360.example.internal:8282
api_key: file:///etc/safeguard/pam360-authtoken
fetch_method: GET
fetch_path: /restapi/json/v1/resources/{{resource}}/accounts/{{account}}/password
auth_header: "AUTHTOKEN: {{api_key}}"
password_json_path: operation.Details.PASSWORD
success_json_path: operation.result.status
error_json_path: operation.result.message
ca_cert: /etc/safeguard/internal-root-ca.pemReference: pam://pam360/resource=1201/account=1502. The resource and account ids are shown in PAM360, or returned by its getResourceIdAccountId API.
Example: an API key on every request
providers:
- name: pamx
type: rest
url: https://pamx.example.internal
api_key: env://PAMX_API_KEY
fetch_path: /api/accounts/{{account}}/password
fetch_query: env={{env}}&reason={{reason}}
auth_header: "X-API-Key: {{api_key}}"
password_json_path: data.password
username_json_path: data.loginReference: pam://pamx/account=svc_dast/env=prod.
Azure Key Vault and AWS Secrets Manager
Read scan credentials from Azure Key Vault or AWS Secrets Manager with the runner's own cloud identity.
Environment variables and files
Read a scan credential from an environment variable or a local file on the machine that runs the scan, for CI jobs and for secrets another agent writes to disk.