Safeguard Docs
Credentials VaultProviders

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

SettingMeaning
urlBase address, for example https://pam.example.internal.
api_user, api_keyThe connector's own credentials. api_key is env:// or file://. Used as {{api_user}}, {{api_key}}, and {{basic}} (Base64 of user:key).
token_pathSet it to add a sign-in step. Leave it out when the API takes a key on every request.
token_methodPOST (default), GET or PUT.
token_bodyjson (default), form, or form-b64 (user and key Base64-encoded first).
token_body_templateThe 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_pathWhere the token is in the sign-in answer, for example access_token.
token_ttlHow long a token is reused (default 4m). On a 401 the runner signs in again once.
fetch_methodGET (default), POST or PUT.
fetch_pathThe request path, with placeholders, for example /api/v1/secrets/{{id}}/fields/{{field}}. No query string here.
fetch_queryThe query string, for example env={{env}}.
fetch_body_template, fetch_content_typeA body for POST/PUT, JSON (default) or application/x-www-form-urlencoded.
auth_headerName: value, for example Authorization: Bearer {{token}} or X-API-Key: {{api_key}}. Default with a sign-in step: Authorization: Bearer {{token}}.
password_json_pathWhere 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_pathWhere the user name is, for #username.
success_json_path, error_json_pathFor 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.pem

Reference: 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.login

Reference: pam://pamx/account=svc_dast/env=prod.

On this page