Skip to main content
Every Baton connector uses a type-safe configuration system. Configuration flows through three layers:
  1. Command-line flags (--domain example.com)
  2. Environment variables (BATON_DOMAIN=example.com)
  3. A config file (YAML)
Flags take precedence over environment variables, which take precedence over the config file. A field’s default value applies when none of the three sets it.

Standard flags (all connectors)

Every connector automatically has these flags through the SDK. Run ./baton-yourservice --help to see the flags for a specific connector. Hidden flags don’t appear there.

Output and logging

Daemon mode

A connector runs in daemon mode when you set --client-id, and it exits with an error unless you also set --client-secret. A connector that runs as a Windows service always runs in daemon mode.

Sync performance

Provisioning and operations

See Test provisioning locally for how to combine these flags.

Targeted sync

OpenTelemetry (operators)

Built-in subcommands

Every connector also has subcommands. Two are useful while you build:
  • capabilities prints the capability manifest as JSON.
  • config prints the configuration schema.

Environment variables

Every flag maps to an environment variable with the BATON_ prefix:
Rules:
  • The prefix is BATON_.
  • Dashes become underscores: --base-dn becomes BATON_BASE_DN.
  • Use upper case. On systems with case-sensitive environment variables, baton_domain doesn’t match.
Example:

Config file format

Connectors read configuration from a YAML file:
By default, the connector looks for .baton.yaml in the current directory. To use a different file, set the BATON_CONFIG_PATH environment variable to its path. The file name must end in .yaml or .yml.

Define your configuration

You declare a connector’s configuration fields in pkg/config/config.go, group them into a field.Configuration, and pass that to config.RunConnector:
Run go generate (or make generate in a Starter Pack project) to create conf.gen.go. It defines a struct with one typed field for each configuration field, tagged with mapstructure:"<field-name>", and it satisfies the field.Configurable interface that RunConnector requires. Your connector constructor receives this struct. See Building connectors for the full setup. field.NewConfiguration also accepts these options: WithConnectorDisplayName, WithHelpUrl, WithIconUrl, WithCatalogId, WithIsDirectory, and WithConstraints, which registers field relationships.

Field types

StringField

Flag: --domain example.okta.com Environment variable: BATON_DOMAIN=example.okta.com

BoolField

Flag: --ldaps or --ldaps=true Environment variable: BATON_LDAPS=true
Don’t call WithRequired(true) on a BoolField. The SDK panics when it builds the schema.

IntField

Flag: --port 636 Environment variable: BATON_PORT=636

StringSliceField

Flag: --skip-groups "Group1" --skip-groups "Group2" Environment variable: BATON_SKIP_GROUPS="Group1,Group2"

StringMapField

A map of string keys to values:

SelectField and MultiSelectField

SelectField limits a field to one value from a list. MultiSelectField allows several:
Flag: --auth-type oauth

Other field types

For specialized inputs, the field package also has MultilineField, FileUploadField, RandomField, and Oauth2Field.

Field options

Required fields

If a required field has no value, the connector exits with an error that names the field and says it’s required.

Secret fields

C1 obscures secret fields in its configuration interface.

Default values

WithDefaultValueFunc computes a default when the connector starts, and WithSuggestedValue suggests a value in the C1 configuration interface without setting a default.

Hidden fields

Shorthand flags

Display and metadata options

Who sets a field

WithExportTarget controls who is expected to set a field: Fields you add to a connector appear in the C1 configuration interface unless you set a different target. Use ExportTargetCLIOnly for settings that tenant admins shouldn’t see. WithRequiredInGUI makes a field required in the interface without making it required on the command line.

Validation rules

String validation

The string ruler also has Eq, Len, NotContains, and format checks such as IsEmail, IsHostname, IsIP, IsURI, and IsUUID.

Integer validation

Other validation

WithStringSlice, WithStringMap, and WithBool accept rules for those field types. WithStringSlice supports item-count limits, uniqueness, and rules for each item.

Field relationships

Relationships constrain which fields can be set together. Register them with field.WithConstraints when you build the configuration:

Required together

Both must be provided, or neither:

Mutually exclusive

At most one can be provided:
A field marked required can’t be part of a mutually exclusive set, because the SDK treats that relationship as invalid.

At least one required

Dependent fields

The first list of fields depends on the second. If you set any field in the first list, you must set every field in the second:
The two lists can’t share a field.

Configuration precedence

When the same setting is specified more than one way:

Quick reference

Common patterns

Check connector-specific flags