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` showThe 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"]
}categoryisNATIVE(the Safeguard vault),EXTERNAL(a PAM or secret store a vault entry can point at) orLOCAL(env,file).refFieldsare the parts of a reference, in order. A form joins them aspam://<type>/plus each field with/. A field with"part": "query"or"part": "fragment"becomes?key=valueor#valueinstead of a path part.configFieldsare the provider's settings insecret-providers.yaml. Eachkeymust be a real setting of the file.- Field
typeis one ofstring,url,path,int,bool,enum(withoptions),duration,secretRefandtext. - A field with
"secret": truehas typesecretRef. It is never sent to the platform. The app turns it into anenv://orfile://placeholder in the generatedsecret-providers.yamlsnippet. capabilitieslistsFETCH,RELEASE,LEASE,APPROVE,ROTATEandTEST.
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
*Errormade withErrffor 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 withTransportError, which marks the transient ones (connection, timeout, 429, 5xx) so the resolver retries them. - Build HTTP clients with
Env.HTTPClient, which appliesca_cert, the client certificate and the timeout, and do not follow redirects, so a token is never sent to another address. Read secret settings withEnv.Bootstrap, which acceptsenv://andfile://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), asprovider_delinea.godoes. - Add a method for each optional capability the product supports:
Releaseto check in,TestConnectionto 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
ProviderConfiginconfig.gowith ayaml:"..."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 asecretReffield. - If the provider has settings it cannot work without, add a case for its type to
CheckProvidersincheckin.gososafeguard vault providersreports what is missing. Without one, the provider is reported as configured.
2. The Go tests
- Add the type to the
wantlist ofTestEveryStrategyIsRegisteredWithADescriptorinstrategy_test.go. That test checks the descriptor is complete, the example reference passes yourValidateRef, and secret fields aresecretRef. - Add your good and bad references to
TestValidateRefPerStrategyand a case toTestSelectByScheme. - Add a case to
TestCapabilitiesAreDerivedFromTheInstance. - Add
provider_acme_pam_test.gowith 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 usewantNoLeak).
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.yamlsnippet are built from the descriptor. - No audit code. Audit rows carry the provider as the strategy's
type. - No
ValidateRefcall 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.
Credentials vault CLI reference
The safeguard vault, safeguard secrets and safeguard hostscan commands, the /vault panel in the interactive terminal, and the runner's vault settings.
Retire a project, product or connector
How to archive and restore a project or product, delete one, disconnect a connector and keep its configuration, or remove a connector and its credentials, with what each action keeps and what it cannot undo.