Safeguard Docs
Credentials VaultProviders

ARCON PAM

+m.group(2).replace(",")+

ARCON PAM

Safeguard integrates with ARCON PAM through ARCON's password-retrieval API (application-to-application password retrieval). The runner signs in with an API user and key, asks for the password of one target account, and uses it for the scan.

Reference

pam://arcon/<TargetType>/<ServerIp>/<UserName>[?open_for_hours=<n>][#password|#username]
PartMeaning
TargetTypeARCON's target type for the account, as your ARCON administrator names it (for example the type used for Windows servers, Linux servers, databases or web applications).
ServerIpThe server's IP address or host name, exactly as it is registered in ARCON.
UserNameThe account on that server.
open_for_hoursOptional. How long ARCON opens the password for, in hours (default 1, or the provider's open_for_hours).
#usernameOptional. Returns the account's user name instead of the password.

Example: pam://arcon/Windows/10.0.5.17/svc_scan. Through a vault entry the app builds this for you from the ARCON PAM fields (target type, server IP or host, user name, optional hours).

What the ARCON administrator prepares

  1. The password-retrieval API (application-to-application) enabled and licensed.
  2. An API user and key for Safeguard, allowed to retrieve only the scan accounts, with no approval step on those accounts for this user.
  3. The API address reachable from the runner over HTTPS, and the internal CA certificate that signed it. If ARCON requires a client certificate, a certificate and key for the runner.
  4. The target type values for the in-scope servers and applications.
  5. Which API variant is enabled on your ARCON release (below), and the request and answer details from ARCON's API documentation for that release.

Runner configuration

providers:
  - name: arcon
    type: arcon
    url: https://arcon.example.internal
    variant: digital-vault          # or: legacy
    api_user: env://ARCON_API_USER  # a literal user name is accepted too
    api_key: file:///etc/safeguard/arcon-api-key
    ca_cert: /etc/safeguard/internal-root-ca.pem
    # client_cert: /etc/safeguard/arcon-client.pem   # only if ARCON requires mutual TLS
    # client_key:  /etc/safeguard/arcon-client.key
    open_for_hours: "1"
    allowed_refs:
      - "Windows/10.0.5.*/svc_scan"

The key file must be readable only by the runner's account. Check the entry with safeguard vault providers.

The two API variants

variant: digital-vault (default)variant: legacy
Sign-inPOST /dv/api/sdk/GetToken, JSON {"Username":"<api_user>","Password":"<api_key>"}POST /arconToken, form grant_type=password&username=<base64 api_user>&password=<base64 api_key>
Token in the answerResult.accessTokenaccess_token
Password requestPOST /dv/api/sdk/GetTargetDevicePassKeyPOST /api/ServicePassword/GetTargetDevicePassKey
Request body[{"UserName":"<user>","ServerIp":"<server>","TargetType":"<type>","OpenForHours":"<hours>"}]the same
AuthorizationAuthorization: Bearer <token>the same
Password in the answerResult.0.Password (the first element of the Result array)the same

The token is kept in memory for token_ttl (default 4 minutes) and requested again once if ARCON answers 401.

Adjusting the request to your ARCON release

ARCON's request and answer details can differ between releases. Every detail is a setting, so you can match your release on site without a Safeguard update:

SettingWhat it changesExample
token_path, token_methodSign-in path and method/dv/api/sdk/GetToken
token_bodySign-in body format: json, form, or form-b64 (user and key Base64-encoded)json
token_body_templateSign-in body, with {{api_user}} and {{api_key}}{"Username":"{{api_user}}","Password":"{{api_key}}"}
token_json_pathWhere the token is in the sign-in answerResult.accessToken
token_ttlHow long a token is reused4m
fetch_path, fetch_method, fetch_queryPassword request path, method, query string/dv/api/sdk/GetTargetDevicePassKey
fetch_body_templatePassword request body, with {{type}}, {{server}}, {{user}}, {{hours}}, and optionally {{reason}}, {{scan_ref}}, {{runner}}see the table above
fetch_content_typeBody content typeapplication/json
auth_headerHow the token is sent, Name: value with {{token}}Authorization: Bearer {{token}}
password_json_path, username_json_pathWhere the password and user name are in the answer. Dotted path, numbers index arraysResult.0.Password
success_json_path, error_json_pathWhere ARCON reports failure inside a 200 answer, and its messageSuccess, Message

Values from the reference are escaped for where they land (JSON string, URL path, query, form), so a reference cannot add fields or change the request. Templates come only from the provider file.

Errors inside a 200 answer

Some ARCON releases answer HTTP 200 with a failure flag and a message instead of an HTTP error. When the answer has no password, the runner looks for a failure flag (Success, IsSuccess, Status and similar, or success_json_path) and a message (Message, ErrorMessage, Error and similar, or error_json_path). It reports the message, cleaned of control characters and of the API key and cut at 160 characters, with a code chosen from it: AUTH_FAILED for token and sign-in problems, FORBIDDEN for permission and approval problems, NOT_FOUND for an unknown server, target or account, otherwise EMPTY. For example:

Could not read the credential for the host credential from ARCON (arcon): the API user is not allowed to retrieve this account (ARCON said: User is not authorised for this target). Check the API user's permission on this account in ARCON, and that no approval is pending for it.

Verify on your ARCON before go-live

  1. On the runner: safeguard vault providers shows arcon as configured.
  2. safeguard secrets test pam://arcon/<TargetType>/<ServerIp>/<UserName> with a UAT account prints OK and a length class.
  3. If it fails, the code and ARCON's own message tell you which step to adjust: AUTH_FAILED (sign-in path, body format, user or key), NOT_FOUND (target type, server or user name, or the fetch path), EMPTY (password_json_path does not match the answer), TLS (ca_cert).
  4. Add the vault entry in the app, Test access from the runner, then run one scan and check the read in the entry's history and in ARCON's own audit log.

Release

ARCON opens the password for open_for_hours. The runner does not send a separate release or check-in request to ARCON; the window closes on ARCON's side. Keep open_for_hours short.

On this page