https://github.com/cyberark/conjur-api-go
Go client for the CyberArk Conjur API
https://github.com/cyberark/conjur-api-go
api-client conjbot-notify conjur conjur-core conjur-sdk core go golang
Last synced: 5 months ago
JSON representation
Go client for the CyberArk Conjur API
- Host: GitHub
- URL: https://github.com/cyberark/conjur-api-go
- Owner: cyberark
- License: apache-2.0
- Created: 2017-04-06T18:01:24.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2025-04-24T13:11:03.000Z (about 1 year ago)
- Last Synced: 2025-04-24T14:28:00.119Z (about 1 year ago)
- Topics: api-client, conjbot-notify, conjur, conjur-core, conjur-sdk, core, go, golang
- Language: Go
- Homepage:
- Size: 729 KB
- Stars: 20
- Watchers: 21
- Forks: 21
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# CyberArk Secrets Manager API for Go
Programmatic Golang access to the CyberArk Secrets Manager API.
## Certification level
This repo is a **Community** level project. It's a community contributed project that **is not reviewed or supported
by CyberArk**. For more detailed information on our certification levels, see [our community guidelines](https://github.com/cyberark/community/blob/master/Conjur/conventions/certification-levels.md#community).
## Using conjur-api-go with Conjur Open Source
Are you using this project with [Conjur Open Source](https://github.com/cyberark/conjur)? Then we
**strongly** recommend choosing the version of this project to use from the latest [Conjur OSS
suite release](https://docs.conjur.org/Latest/en/Content/Overview/Conjur-OSS-Suite-Overview.html).
Conjur maintainers perform additional testing on the suite release versions to ensure
compatibility. When possible, upgrade your Conjur version to match the
[latest suite release](https://docs.conjur.org/Latest/en/Content/ReleaseNotes/ConjurOSS-suite-RN.htm);
when using integrations, choose the latest suite release that matches your Conjur version. For any
questions, please contact us on [Discourse](https://discuss.cyberarkcommons.org/c/conjur/5).
## Compatibility
The `conjur-api-go` has been tested against the following Go versions:
- 1.24
- 1.25
## Installation
```sh
go get github.com/cyberark/conjur-api-go/conjurapi
```
## Quick Start
This example demonstrates how to retrieve a secret from Conjur.
Suppose there exists a variable `db/secret` with secret value `fde5c4a45ce573f9768987cd`. Create a Go program using `conjur-api-go` to fetch the secret value:
```go
package main
import (
"os"
"fmt"
"github.com/cyberark/conjur-api-go/conjurapi"
"github.com/cyberark/conjur-api-go/conjurapi/authn"
)
func main() {
variableIdentifier := "db/secret"
config, err := conjurapi.LoadConfig()
if err != nil {
panic(err)
}
conjur, err := conjurapi.NewClientFromKey(config,
authn.LoginPair{
Login: os.Getenv("CONJUR_AUTHN_LOGIN"),
APIKey: os.Getenv("CONJUR_AUTHN_API_KEY"),
},
)
if err != nil {
panic(err)
}
// Retrieve a secret into []byte.
secretValue, err := conjur.RetrieveSecret(variableIdentifier)
if err != nil {
panic(err)
}
fmt.Println("The secret value is: ", string(secretValue))
// Retrieve a secret into io.ReadCloser, then read into []byte.
// Alternatively, you can transfer the secret directly into secure memory,
// vault, keychain, etc.
secretResponse, err := conjur.RetrieveSecretReader(variableIdentifier)
if err != nil {
panic(err)
}
secretValue, err = conjurapi.ReadResponseBody(secretResponse)
if err != nil {
panic(err)
}
fmt.Println("The secret value is: ", string(secretValue))
}
```
Build and run the program:
```bash
$ export CONJUR_APPLIANCE_URL=https://eval.conjur.org
$ export CONJUR_ACCOUNT=myorg
$ export CONJUR_AUTHN_LOGIN=mylogin
$ export CONJUR_AUTHN_API_KEY=myapikey
$ go run main.go
The secret value is: fde5c4a45ce573f9768987cd
```
## Usage
### Configuration and Authentication
Connecting to CyberArk Secrets Manager requires two steps:
1. **Configuration** - Specify the CyberArk Secrets Manager endpoint and connection security settings
2. **Authentication** - Provide credentials for authentication
### Credential Storage
The Conjur Go API supports three credential storage options, configurable via the `CredentialStorage` field in the `Config` struct:
#### Storage Options
- **`conjurapi.CredentialStorageKeyring`** - Stores credentials in the system keyring (default when available). This is the most secure option for desktop environments.
- **`conjurapi.CredentialStorageFile`** - Stores credentials in a `.netrc` file (default when keyring is not available). The `.netrc` file location can be customized using the `NetRCPath` config field.
- **`conjurapi.CredentialStorageNone`** - Does not store credentials. **Use this option in environments where there are no file permissions to create a `.netrc` file**, such as restricted containers, read-only filesystems, or ephemeral compute instances.
> **Note:** If no credential storage is specified, the API will automatically select `CredentialStorageKeyring` if available, otherwise it will default to `CredentialStorageFile`.
#### Example: Disabling Credential Storage
```go
config := conjurapi.Config{
ApplianceURL: "https://conjur.example.com",
Account: "myorg",
CredentialStorage: conjurapi.CredentialStorageNone,
}
conjur, err := conjurapi.NewClientFromKey(config,
authn.LoginPair{
Login: "mylogin",
APIKey: "myapikey",
},
)
```
### Authentication Methods
#### API Key Authentication
The Quick Start example above demonstrates API key authentication using `NewClientFromKey()`. This is the most common authentication method for legacy applications.
#### JWT Authentication
You can authenticate using JWT tokens via environment variables. This method is useful for containerized environments and CI/CD pipelines and is more secure than using API keys.
##### Environment Variables Required
- `CONJUR_APPLIANCE_URL` - The URL of your Conjur instance
- `CONJUR_ACCOUNT` - Your Conjur account name
- `CONJUR_AUTHN_JWT_SERVICE_ID` - The JWT authenticator service ID
- `CONJUR_AUTHN_JWT_TOKEN` - The JWT token
- `CONJUR_SECRET_ID` - The identifier of the secret to retrieve
##### Example Code
```go
package main
import (
"fmt"
"log"
"os"
"github.com/cyberark/conjur-api-go/conjurapi"
)
func checkEnvironmentVariables() error {
variables := []string{
"CONJUR_APPLIANCE_URL",
"CONJUR_ACCOUNT",
"CONJUR_AUTHN_JWT_SERVICE_ID",
"CONJUR_AUTHN_JWT_TOKEN",
"CONJUR_SECRET_ID",
}
for _, variable := range variables {
if os.Getenv(variable) == "" {
return fmt.Errorf("environment variable %s is not set", variable)
}
}
return nil
}
func main() {
// Check for required environment variables
if err := checkEnvironmentVariables(); err != nil {
log.Fatalf("%v", err)
}
// Get the secret ID to retrieve
variableIdentifier := os.Getenv("CONJUR_SECRET_ID")
// Load configuration from environment variables
config, err := conjurapi.LoadConfig()
if err != nil {
log.Fatalf("Cannot load configuration: %s", err)
}
// Create a new Conjur client using environment variables
conjur, err := conjurapi.NewClientFromEnvironment(config)
if err != nil {
log.Fatalf("Cannot create client: %s", err)
}
// Retrieve the secret value from Conjur
secretValue, err := conjur.RetrieveSecret(variableIdentifier)
if err != nil {
log.Fatalf("Cannot retrieve secret %s: %s", variableIdentifier, err)
}
// Print the secret value to stdout
fmt.Printf("%s", string(secretValue))
}
```
## Contributing
We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, please see our [contributing
guide][contrib].
[contrib]: https://github.com/cyberark/conjur-api-go/blob/main/CONTRIBUTING.md
## License
Copyright (c) 2022-2025 CyberArk Software Ltd. All rights reserved.
This repository is licensed under Apache License 2.0 - see [`LICENSE`](LICENSE) for more details.