Interface IProfileClient

Defines the interface for the client used to communicate with the Neon Assistant or a custom service. These services provides access to user and workstation specific settings including secrets and general properties. This is used for activities such as CI/CD automation and integration testing.

Namespace: Neon.Deployment

Assembly: Neon.Common.dll

Syntax

public interface IProfileClient

Remarks

Implementations of this interface address the following scenarios:

Gaining access to secrets. NEONFORGE has standardized on 1Password for password management and the Neon Profile Service abstracts the details of authenticating with 1Password and accessing secrets.

This interface supports two kinds of secrets: passwords and values. These are somewhat of an artifact of how we implemented this using 1Password. Secret passwords are values retrieved from a 1Password item's password field and secret values correspond to a 1Password item value field. We found this distinction useful because 1Password reports when passwords are insecure or duplicated but we have other secrets where these checks can be distracting. Custom implementation can choose to follow this pattern or just treat both types of secret the same.

You can also obtain a specific property from a secret password or value by using this syntax:
SECRETNAME[PROPERTY]
This is useful for obtaining both the username and password from a login, or all of the different properties from a credit card, etc. This blurs the difference between secret passwords and secret values a bit but we're going to retain both concepts anyway.
Profile values are also supported. These are non-secret name/value pairs used for describing the local environment as required for CI/CD. For example, we use this for describing the IP addresses available for deploying a test NEONKUBE cluster. Each developer will often need distict node IP addresses that work on the local LAN and also don't conflict with addresses assigned to other developers.

NEONFORGE's internal implementation simply persists profile values on the local workstation as a YAML file which is referenced by our profile service.
Abstracting access to the user's master password. NEONFORGE has implemented an internal Windows application that implements a profile service that prompts the developer for their master 1Password, optionally caching it for a period of time so the user won't be prompted as often. This server also handles profile and secret lookup.

Managing Sign-in:

Some profile service implementations prompt the developer for master credentials and then cache these for a period of time, so the developer isn't innundated with password requests.

EnsureAuthenticated(TimeSpan) can be used to have the developer sign-in the profile server, optionally specifiying the number of seconds the server will remain signed-in afterwards. This is useful for situations where an operation requests secrets as the operation progresses and it'll be possible for the sign-in period to expire before the operation completes.

note

We originally tried to manage this by loading any secrets at the beginning of an operation, so (hopefully) we'd obtain all of them while the user was still present to enter any credentials. This worked for operations executing as a single process, but doesn't really work well for operations that span multiple processess. We tried to address this with client-side caching via environment variables, but that introduced other issues, so we removed caching support.

Methods

EnsureAuthenticated(TimeSpan)

Requests that the profile server be signed-in when it's not already signed or extend the sign-in period. By default, the sign-in period will be extended by the default time configured for the server but this can be overridden via signinPeriod (which comes in handy for operations that may take longer than the profile server default).

Declaration

void EnsureAuthenticated(TimeSpan signinPeriod = default)

Parameters

Type	Name	Description
TimeSpan	signinPeriod	Optionally how long to extend the sign-in. Passing zero (the default) or values less than zero, will extend the sign-in by the default sign-in period implemented by the profile server.

Remarks

Profile implementations that don't required that developers sign-in when secrets are requested should treat this as a NOP and just return OK.

Exceptions

Type	Condition
ProfileException	Thrown if the profile server returns an error, i.e. when the server is not currently signed-in..

GetProfileValue(string, bool)

Requests a profile value from the assistant.

Declaration

string GetProfileValue(string name, bool nullOnNotFound = false)

Parameters

Type	Name	Description
string	name	Identifies the profile value.
bool	nullOnNotFound	Optionally specifies that `null` should be returned rather than throwing an exception when the profile value does not exist.

Returns

Type	Description
string	The password value.

Exceptions

Type	Condition
ProfileException	Thrown if the profile server returns an error.

GetSecretPassword(string, string, string, bool)

Requests the value of a secret password from 1Password via the assistant.

Declaration

string GetSecretPassword(string name, string vault = null, string masterPassword = null, bool nullOnNotFound = false)

Parameters

Type	Name	Description
string	name	Specifies the secret name.
string	vault	Optionally specifies the 1Password vault. This defaults to the current user (as managed by the IProfileClient implementaton).
string	masterPassword	Optionally specifies the master 1Password when it is already known.
bool	nullOnNotFound	Optionally specifies that `null` should be returned rather than throwing an exception when the secret does not exist.

Returns

Type	Description
string	The password value.

Exceptions

Type	Condition
ProfileException	Thrown if the profile server returns an error.

GetSecretValue(string, string, string, bool)

Requests the value of a secret value from 1Password via the assistant.

Declaration

string GetSecretValue(string name, string vault = null, string masterPassword = null, bool nullOnNotFound = false)

Parameters

Type	Name	Description
string	name	Specifies the secret name.
string	vault	Optionally specifies the 1Password vault. This defaults to the current user (as managed by the IProfileClient implementaton).
string	masterPassword	Optionally specifies the master 1Password when it is already known.
bool	nullOnNotFound	Optionally specifies that `null` should be returned rather than throwing an exception when the secret does not exist.

Returns

Type	Description
string	The password value.

Exceptions

Type	Condition
ProfileException	Thrown if the profile server returns an error.

Signout()

Requests that the profile server sign-out from it's credential source.

Declaration

void Signout()