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]| Part | Meaning |
|---|---|
TargetType | ARCON'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). |
ServerIp | The server's IP address or host name, exactly as it is registered in ARCON. |
UserName | The account on that server. |
open_for_hours | Optional. How long ARCON opens the password for, in hours (default 1, or the provider's open_for_hours). |
#username | Optional. 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
- The password-retrieval API (application-to-application) enabled and licensed.
- An API user and key for Safeguard, allowed to retrieve only the scan accounts, with no approval step on those accounts for this user.
- 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.
- The target type values for the in-scope servers and applications.
- 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-in | POST /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 answer | Result.accessToken | access_token |
| Password request | POST /dv/api/sdk/GetTargetDevicePassKey | POST /api/ServicePassword/GetTargetDevicePassKey |
| Request body | [{"UserName":"<user>","ServerIp":"<server>","TargetType":"<type>","OpenForHours":"<hours>"}] | the same |
| Authorization | Authorization: Bearer <token> | the same |
| Password in the answer | Result.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:
| Setting | What it changes | Example |
|---|---|---|
token_path, token_method | Sign-in path and method | /dv/api/sdk/GetToken |
token_body | Sign-in body format: json, form, or form-b64 (user and key Base64-encoded) | json |
token_body_template | Sign-in body, with {{api_user}} and {{api_key}} | {"Username":"{{api_user}}","Password":"{{api_key}}"} |
token_json_path | Where the token is in the sign-in answer | Result.accessToken |
token_ttl | How long a token is reused | 4m |
fetch_path, fetch_method, fetch_query | Password request path, method, query string | /dv/api/sdk/GetTargetDevicePassKey |
fetch_body_template | Password request body, with {{type}}, {{server}}, {{user}}, {{hours}}, and optionally {{reason}}, {{scan_ref}}, {{runner}} | see the table above |
fetch_content_type | Body content type | application/json |
auth_header | How the token is sent, Name: value with {{token}} | Authorization: Bearer {{token}} |
password_json_path, username_json_path | Where the password and user name are in the answer. Dotted path, numbers index arrays | Result.0.Password |
success_json_path, error_json_path | Where ARCON reports failure inside a 200 answer, and its message | Success, 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
- On the runner:
safeguard vault providersshowsarconas configured. safeguard secrets test pam://arcon/<TargetType>/<ServerIp>/<UserName>with a UAT account prints OK and a length class.- 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_pathdoes not match the answer),TLS(ca_cert). - 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.
Provider setup
What your PAM administrator prepares, what goes in the runner's provider file, and how to check each provider before a scan depends on it.
CyberArk
Read scan credentials from CyberArk through the Central Credential Provider (CCP) REST API with a client certificate, or from CyberArk Conjur.