secret-server-ruby
A gem for using Thycotic Secret Server as a vault for storing secrets and consuming them in Ruby programs.
Requires Secret Server 10.4 and higher, and an installation of the Secret Server SDK client tool.
This gem is unofficial and not supported by Thycotic.
Installation
Add this line to your application's Gemfile:
gem 'secret_server'
And then execute:
$ bundle
Or install it yourself as:
$ gem install secret_server
Initial Setup
Configure the connection to your Secret Server instance:
SecretServer.configure do |config|
config.path = "#{ENV['HOME']}/sdkclient"
config.url = 'https://myserver/SecretServer/'
config.rule = 'MyOnboardingRule'
config.key = 'MyOnboardingKey'
end
config.path
is the directory containing the SDK clientconfig.url
is the URL to your Secret Server instanceconfig.rule
is the name of an onboarding rule you have created (optional)config.key
is the onboarding key for that rule, if applicable (optional)
Alternatively, you can also pull configuration from the current environment:
SecretServer.env_configure
The gem will configure the connection using the variables SDK_CLIENT_PATH
,
SECRET_SERVER_URL
, SDK_CLIENT_RULE
, and SDK_CLIENT_KEY
.
Initialize the connection to Secret Server:
SecretServer.init!
The initialization step requires write access to the current directory.
Once the configuration and initialization are complete, they do not need to be run again. Encrypted configuration files created in the current directory will be used to establish the connection to Secret Server.
Usage
Fetch a secret by ID:
# retrieve the full representation of a secret
secret = SecretServer.secret(1)
# retrieve only the secret fields
secret = SecretServer.secret(1, field: :all)
# retrieve only a single secret field value by slug
password = SecretServer.secret(1, field: 'password')
To acquire an API token to make REST calls as the application account user:
token = SecretServer.token
To remove the connection to Secret Server and delete all configuration:
SecretServer.remove!
Cache Settings
By default, no secret values are stored on the local machine. As such, every call to SecretServer.secret
will result in a round-trip to the server. If the server is unavailable, the call will fail.
To change this behavior, set the cache strategy:
# The default (never cache secrets)
SecretServer.cache_strategy = SecretServer::SdkClient::StrategyNever
# Set the cache age (the maximum time, in minutes, that a cached value will be usable).
SecretServer.cache_age = 10
# Check the server first; if unavailable, use the return the last retrieved
# value, if present. Use this strategy for improved fault tolerance.
SecretServer.cache_strategy = SecretServer::SdkClient::StrategyServerThenCache
# Check the cache first; if no value is present, retrieve it from the server.
# Use this strategy for improved performance.
SecretServer.cache_strategy = SecretServer::SdkClient::StrategyCacheThenServer
# Same as the above mode, but allow an expired cached value to be used if the
# server is unavailable.
SecretServer.cache_strategy = SecretServer::SdkClient::StrategyCacheThenServerAllowExpired
# It is also possible to set the cache strategy and age at the same time:
SecretServer.cache_strategy = [SecretServer::SdkClient::StrategyServerThenCache, 20]
# Clear all cached values immediately
SecretServer.cache_clear!
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/tonygambone/secret-server-ruby.
License
The gem is available as open source under the terms of the MIT License.
TODO
- Automated SDK client installation
- Check if
tss
is a supported version, if it ever supports versioning - Integration testing
- Add links to SDK client documentation where needed
- Release to GitHub official
- Release to Rubygems
tss
TODO
- Report version
- Clear up cache.config on remove