Safeguard Docs
Credentials VaultDeveloper guide

Add a credential provider

How credential sources are built as strategies in the Safeguard CLI and platform, the optional capabilities a strategy can add, and the steps to add a new PAM or secret store.

Add a credential provider

Every place a credential can live is a strategy: ARCON, CyberArk, HashiCorp Vault, Delinea Secret Server, BeyondTrust, Azure Key Vault, AWS Secrets Manager, the REST connector, environment variables, files, and the Safeguard vault itself. Everything that uses credentials (the resolver, scan jobs, host scans, the check-in loop, the audit trail, the app's forms) talks to the strategy interface, a registry and descriptors, never to a provider by name. So a new provider is one file on the runner side and one class on the platform side. No scanner, form or audit code changes.

This page is for people who work on Safeguard's code. To use an existing provider, see Provider setup.

The pattern

The same shape exists in Go, in the CLI and runner (pkg/secrets in sg-cli), and in Java, on the platform (service/vault/provider in sg-notification).

CredentialProvider (the strategy)            required for every backend
  Type() string                              "arcon", "delinea", "safeguard" ...
  Describe() Descriptor                      label, category, schemes, reference syntax and fields, settings
  Capabilities() Capabilities                worked out from the optional interfaces below
  Fetch(ctx, Ref) (Value, error)             read the value a reference names
  ValidateRef(Ref) error                     check the provider-specific part of a reference

Optional capabilities, found with a type assertion (Go) or instanceof (Java), never by provider name:
  Releaser  Release(ctx) error               check in at scan end (BeyondTrust)
  Leaser    Checkout / Renew / Checkin       leases (the Safeguard vault)
  Approver  RequestAccess / AwaitDecision    approval before use (the Safeguard vault)
  Rotator   Rotate                           rotation (the Safeguard vault)
  Tester    TestConnection(ctx) error        check the provider's own sign-in

Registry
  Register(Descriptor, Factory, Validate)    called from the strategy file's init() in Go
                                             (a Spring @Component per strategy in Java)
  Select(ref)                                scheme to strategy: env:// env, file:// file,
                                             sgvault:// and pam://safeguard/ the Safeguard vault,
                                             vault:// hashicorp-vault, pam://<type>/ that type
  Descriptors()                              what forms and `safeguard vault provider-types` show

The Go names are in pkg/secrets/strategy.go (CredentialProvider, Releaser, Leaser, Approver, Rotator, Tester, Register, Select, Descriptors, LookupStrategy) and descriptor.go (Descriptor, Field). The Java names are CredentialProviderStrategy, CredentialProviderRegistry, ProviderDescriptor, and the capability interfaces Leaser, Approver and Rotator.

An external provider needs only Fetch and ValidateRef on the runner, because the platform never reads an external provider's value: it only checks the shape of references. Capabilities that the platform performs, such as approval and rotation of Safeguard vault credentials, are listed in the descriptor as static capabilities.

The descriptor

A descriptor is JSON with the same field names in Go and Java. The app builds its forms from it, and safeguard vault provider-types --json prints it.

{
  "type": "delinea",
  "label": "Delinea Secret Server",
  "category": "EXTERNAL",
  "schemes": ["pam"],
  "refSyntax": "pam://delinea/<secretId>/<fieldSlug>",
  "refExample": "pam://delinea/4711/password",
  "refFields": [
    { "key": "secretId", "label": "Secret id", "type": "string", "required": true, "pattern": "^[0-9]{1,18}$" },
    { "key": "fieldSlug", "label": "Field slug", "type": "string", "required": true, "pattern": "^[A-Za-z0-9_-]{1,64}$" }
  ],
  "configFields": [
    { "key": "url", "label": "Address", "type": "url", "required": true },
    { "key": "api_key", "label": "Password or client secret", "type": "secretRef", "secret": true }
  ],
  "capabilities": ["FETCH", "TEST"]
}
  • category is NATIVE (the Safeguard vault), EXTERNAL (a PAM or secret store a vault entry can point at) or LOCAL (env, file).
  • refFields are the parts of a reference, in order. A form joins them as pam://<type>/ plus each field with /. A field with "part": "query" or "part": "fragment" becomes ?key=value or #value instead of a path part.
  • configFields are the provider's settings in secret-providers.yaml. Each key must be a real setting of the file.
  • Field type is one of string, url, path, int, bool, enum (with options), duration, secretRef and text.
  • A field with "secret": true has type secretRef. It is never sent to the platform. The app turns it into an env:// or file:// placeholder in the generated secret-providers.yaml snippet.
  • capabilities lists FETCH, RELEASE, LEASE, APPROVE, ROTATE and TEST.

Add a provider, step by step

The example adds a provider called acme-pam. Use the Delinea files as a model: pkg/secrets/provider_delinea.go on the runner side and DelineaStrategy.java on the platform side.

1. The Go strategy (sg-cli)

Create pkg/secrets/provider_acme_pam.go. It holds the type name, the descriptor, the reference check, the provider, and an init() that registers them.

package secrets

const TypeAcmePAM = "acme-pam"

func init() {
	labels[TypeAcmePAM] = "Acme PAM"
	Register(acmeDescriptor, func(cfg ProviderConfig, env *Env) (Provider, error) {
		if strings.TrimSpace(cfg.URL) == "" {
			return nil, Errf(NotConfigured, TypeAcmePAM, "it has no url", "", nil)
		}
		return &acmeProvider{cfg: cfg, env: env}, nil
	}, validateAcmeRef)
}

var acmeDescriptor = Descriptor{
	Type: TypeAcmePAM, Label: "Acme PAM", Category: CategoryExternal, Schemes: []string{SchemePAM},
	RefSyntax:  "pam://acme-pam/<account>",
	RefExample: "pam://acme-pam/svc-scan",
	RefFields:  []Field{refField("account", "Account", "The account name in Acme PAM")},
	ConfigFields: withConfig(commonConfig(true),
		secretField("api_key", "API key", "Acme PAM API key", true)),
	StaticCapabilities: []Capability{CapTest},
}

func validateAcmeRef(ref Ref) error { /* check the part after pam://acme-pam/ */ return nil }

type acmeProvider struct { cfg ProviderConfig; env *Env }

func (*acmeProvider) Type() string { return TypeAcmePAM }

func (p *acmeProvider) Fetch(ctx context.Context, ref Ref) (Value, error) {
	// call the API; return Errf(code, TypeAcmePAM, reason, hint, cause) for every failure
}

Rules for the strategy:

  • Return an *Error made with Errf for every failure, with one of the existing codes (AUTH_FAILED, FORBIDDEN, NOT_FOUND, TLS, UNREACHABLE, TIMEOUT, BAD_REFERENCE, EMPTY). Never put a value in an error. Wrap network failures with TransportError, which marks the transient ones (connection, timeout, 429, 5xx) so the resolver retries them.
  • Build HTTP clients with Env.HTTPClient, which applies ca_cert, the client certificate and the timeout, and do not follow redirects, so a token is never sent to another address. Read secret settings with Env.Bootstrap, which accepts env:// and file:// only.
  • A provider that is a thin layer over a REST API can reuse the templated HTTP engine that ARCON, REST and Delinea share (newHTTPEngine), as provider_delinea.go does.
  • Add a method for each optional capability the product supports: Release to check in, TestConnection to test the sign-in. The capability list in the descriptor then follows from the interfaces the provider implements.
  • If a new setting is needed, add it to ProviderConfig in config.go with a yaml:"..." tag, and list it in the secret settings if it holds a secret. A test fails if a descriptor field is not a real setting, or if a secret setting is not a secretRef field.
  • If the provider has settings it cannot work without, add a case for its type to CheckProviders in checkin.go so safeguard vault providers reports what is missing. Without one, the provider is reported as configured.

2. The Go tests

  • Add the type to the want list of TestEveryStrategyIsRegisteredWithADescriptor in strategy_test.go. That test checks the descriptor is complete, the example reference passes your ValidateRef, and secret fields are secretRef.
  • Add your good and bad references to TestValidateRefPerStrategy and a case to TestSelectByScheme.
  • Add a case to TestCapabilitiesAreDerivedFromTheInstance.
  • Add provider_acme_pam_test.go with a test server: success, each error code, a retry on a transient failure, and a check that no value appears in an error (the existing tests use wantNoLeak).

Run go test ./pkg/secrets/....

3. The Java strategy (sg-notification)

Create service/vault/provider/AcmePamStrategy.java, a Spring @Component that implements CredentialProviderStrategy:

@Component
public class AcmePamStrategy implements CredentialProviderStrategy {
    public static final String TYPE = "acme-pam";

    @Override public String type() { return TYPE; }

    @Override
    public void validateTail(RefTail t) {
        if (t.size() != 1 || t.query() != null || t.fragment() != null) throw RefTail.bad();
        // check t.seg(0)
    }
}

validateTail receives the part after the provider, already split and with every segment checked for unsafe characters. Throw RefTail.bad() for a reference the runner could not read. The platform never contacts the provider.

4. The Java descriptor

Add an entry for acme-pam to src/main/resources/vault/provider-types.json. Copy it from the CLI: safeguard vault provider-types --json. The descriptor must match the Go one.

Then register the class in the static list CredentialProviderRegistry.builtinStrategies(), and add the type to the expected sets in CredentialProviderRegistryTest (the strategy beans, and the external types in pamReferencesTypesAreTheExternalStrategies). The tests fail if a strategy has no descriptor or the reverse, if the capabilities in the descriptor disagree with the interfaces the class implements, or if the example reference does not validate to itself.

Run the vault tests of the service, for example mvn -B test -Dtest='CredentialProviderRegistryTest,PamReferencesTest'.

5. What you do not change

  • No caller of the resolver, no scan job, no host scan code.
  • No form in the web app. The Add a credential form, the Providers tab and the generated secret-providers.yaml snippet are built from the descriptor.
  • No audit code. Audit rows carry the provider as the strategy's type.
  • No ValidateRef call sites. They go through the registry.

After release, acme-pam appears in safeguard vault provider-types and in the app's product list, and a vault entry can hold pam://acme-pam/svc-scan.

Rotation strategies

Rotation of Safeguard vault credentials has its own small registry on the runner, pkg/secrets/rotate, with one strategy per kind (ssh-password, ssh-key, http-token). A strategy changes the credential on the target, verifies a new sign-in with it, and can roll back. It is separate from credential providers because it acts on the target system, not on a PAM. Add a kind there only with the platform's rotation kinds; see Rotation for what exists.

On this page