Skip to content

Commit 75e2198

Browse files
maxlaversemaxlaverse
committed
update documentation
1 parent 77de63d commit 75e2198

File tree

8 files changed

+148
-103
lines changed

8 files changed

+148
-103
lines changed

‎README.md

Lines changed: 3 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -33,43 +33,20 @@ The provider likely works with older versions but those haven't been tested.
3333
The complete documentation for this provider can be found on the [Terraform Registry docs].
3434

3535
```tf
36-
# Setting up the Provider
37-
variable "bw_password" {
38-
type = string
39-
description = "Bitwarden Master Key"
40-
sensitive = true
41-
}
42-
43-
variable "bw_client_id" {
44-
type = string
45-
description = "Bitwarden Client ID"
46-
sensitive = true
47-
}
48-
49-
variable "bw_client_secret" {
50-
type = string
51-
description = "Bitwarden Client Secret"
52-
sensitive = true
53-
}
54-
5536
terraform {
5637
required_providers {
5738
bitwarden = {
5839
source = "maxlaverse/bitwarden"
59-
version = ">= 0.5.0"
40+
version = ">= 0.6.2"
6041
}
6142
}
6243
}
6344
45+
# Configure the Bitwarden Provider
6446
provider "bitwarden" {
65-
master_password = var.bw_password
66-
client_id = var.bw_client_id
67-
client_secret = var.bw_client_secret
68-
email = "test@laverse.net"
69-
server = "https://vault.bitwarden.com"
47+
email = "terraform@example.com"
7048
}
7149
72-
7350
# Managing Folders
7451
resource "bitwarden_folder" "cloud_credentials" {
7552
name = "My Cloud Credentials"

‎docs/data-sources/attachment.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,5 +54,3 @@ data "bitwarden_attachment" "ssh_private_key" {
5454
### Read-Only
5555

5656
- `content` (String) Content of the attachment
57-
58-

‎docs/data-sources/item_login.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,5 +96,3 @@ Read-Only:
9696

9797
- `match` (String)
9898
- `value` (String)
99-
100-

‎docs/data-sources/item_secure_note.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,5 +82,3 @@ Read-Only:
8282
- `linked` (String)
8383
- `name` (String)
8484
- `text` (String)
85-
86-

‎docs/index.md

Lines changed: 74 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -10,64 +10,95 @@ description: |-
1010
Use the Bitwarden provider to interact with Bitwarden logins, secure notes and folders.
1111
You must configure the provider with the proper credentials before you can use it, and have the [Bitwarden CLI] installed.
1212

13-
## API credentials
14-
In order to interact with your Vault using the Bitwarden Provider Terraform plugin, you need to generate an API key:
15-
1. Connect to your Vault on https://vault.bitwarden.com, or your self-hosted instance
16-
2. Click on "Settings" and then "My Account"
17-
3. Scroll down to the "API Key" section
18-
4. Click on "View API Key" (or maybe another label if it's the first time)
19-
5. Save the API credentials
20-
6. Before running `terraform apply`, export the API credentials as environment variable:
21-
22-
```console
23-
export TF_VAR_bw_client_id=<client_id>
24-
export TF_VAR_bw_client_secret=<client_secret>
25-
export TF_VAR_bw_password=<master_password>
26-
```
27-
2813
## Example Usage
2914

3015
```terraform
31-
# Bitwarden Master Password
32-
variable "bw_password" {
33-
type = string
34-
description = "Bitwarden Master Key"
35-
sensitive = true
36-
}
37-
38-
variable "bw_client_id" {
39-
type = string
40-
description = "Bitwarden Client ID"
41-
sensitive = true
42-
}
43-
44-
variable "bw_client_secret" {
45-
type = string
46-
description = "Bitwarden Client Secret"
47-
sensitive = true
48-
}
49-
```
50-
51-
```terraform
52-
# Provider configuration
5316
terraform {
5417
required_providers {
5518
bitwarden = {
5619
source = "maxlaverse/bitwarden"
57-
version = ">= 0.5.0"
20+
version = ">= 0.6.2"
5821
}
5922
}
6023
}
6124
25+
# Configure the Bitwarden Provider
6226
provider "bitwarden" {
63-
master_password = var.bw_password
64-
client_id = var.bw_client_id
65-
client_secret = var.bw_client_secret
66-
email = "test@laverse.net"
67-
server = "https://vault.bitwarden.com"
27+
email = "terraform@example.com"
28+
}
29+
30+
# Create a Bitwarden Login Resource
31+
resource "bitwarden_item_login" "example" {
32+
name = "Example"
33+
username = "service-account"
34+
password = "<sensitive>"
6835
}
6936
```
7037

38+
## Authentication
39+
The Bitwarden provider can use different combinations of credentials to authenticate:
40+
* Email and Password (requires `email` and `master_password`)
41+
* API key (requires `email`, `master_password`, `client_id` and `client_secret`)
42+
* user-provided Session Key (requires `session_key`)
43+
44+
### Generating a Client ID and Secret
45+
The recommended way to interact with your Vault using the Bitwarden Provider Terraform plugin is to generate an API key.
46+
This allows you to easily revoke access to your Vault without having to change your master password.
47+
48+
In order to generate a pair of Client ID and Secret, you need to:
49+
1. Connect to your Vault on https://vault.bitwarden.com, or your self-hosted instance
50+
2. Click on _Settings_ and then _My Account_
51+
3. Scroll down to the _API Key_ section
52+
4. Click on _View API Key_ (or maybe another label if it's the first time)
53+
5. Save the API credentials somewhere safe
54+
55+
### Generating a Session Key
56+
57+
If you don't want to use an API key, you can use a Session Key instead.
58+
When doing so, it's your responsibility to:
59+
* ensure the validity of the Session Key
60+
* keep the Session Key safe
61+
* revoke it when you don't need it anymore
62+
63+
You can generate a Session Key by running the following command in your Terraform Workspace:
64+
```
65+
BITWARDENCLI_APPDATA_DIR=.bitwarden bw login
66+
67+
# or if you use a custom vault path
68+
BITWARDENCLI_APPDATA_DIR=<vault_path> bw login
69+
```
70+
71+
## Configuration
72+
Configuration for the Bitwarden Provider can be derived from two sources:
73+
* Parameters in the provider configuration
74+
* Environment variables
75+
76+
### Parameters
77+
Credentials can be provided by adding a `master_password` and optionally `client_id` and `client_secret` to the bitwarden provider block.
78+
```terraform
79+
provider "bitwarden" {
80+
email = "terraform@example.com"
81+
master_password = "my-master-password"
82+
client_id = "my-client-id"
83+
client_secret = "my-client-secret"
84+
}
85+
```
86+
87+
### Environment variables
88+
Credentials can be provided by using the `BW_PASSWORD` and optionally `BW_CLIENTID` and `BW_CLIENTSECRET` environment variables.
89+
90+
For example:
91+
```bitwarden
92+
provider "bitwarden" {}
93+
```
94+
95+
```console
96+
export BW_EMAIL="terraform@example.com"
97+
export BW_PASSWORD="my-master-password"
98+
export BW_CLIENTID="my-client-id"
99+
export BW_CLIENTSECRET="my-client-secret"
100+
```
101+
71102
<!-- schema generated by tfplugindocs -->
72103
## Schema
73104

‎examples/provider/provider.tf

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎examples/quick/provider.tf

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,20 @@
1-
# Provider configuration
21
terraform {
32
required_providers {
43
bitwarden = {
54
source = "maxlaverse/bitwarden"
6-
version = ">= 0.5.0"
5+
version = ">= 0.6.1"
76
}
87
}
98
}
109

10+
# Configure the Bitwarden Provider
1111
provider "bitwarden" {
12-
master_password = var.bw_password
13-
client_id = var.bw_client_id
14-
client_secret = var.bw_client_secret
15-
email = "test@laverse.net"
16-
server = "https://vault.bitwarden.com"
12+
email = "terraform@example.com"
13+
}
14+
15+
# Create a Bitwarden Login Resource
16+
resource "bitwarden_item_login" "example" {
17+
name = "Example"
18+
username = "service-account"
19+
password = "<sensitive>"
1720
}

‎templates/index.md.tmpl

Lines changed: 61 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,26 +10,73 @@ description: |-
1010
Use the Bitwarden provider to interact with Bitwarden logins, secure notes and folders.
1111
You must configure the provider with the proper credentials before you can use it, and have the [Bitwarden CLI] installed.
1212

13-
## API credentials
14-
In order to interact with your Vault using the Bitwarden Provider Terraform plugin, you need to generate an API key:
13+
## Example Usage
14+
15+
{{tffile "examples/quick/provider.tf"}}
16+
17+
## Authentication
18+
The Bitwarden provider can use different combinations of credentials to authenticate:
19+
* Email and Password (requires `email` and `master_password`)
20+
* API key (requires `email`, `master_password`, `client_id` and `client_secret`)
21+
* user-provided Session Key (requires `session_key`)
22+
23+
### Generating a Client ID and Secret
24+
The recommended way to interact with your Vault using the Bitwarden Provider Terraform plugin is to generate an API key.
25+
This allows you to easily revoke access to your Vault without having to change your master password.
26+
27+
In order to generate a pair of Client ID and Secret, you need to:
1528
1. Connect to your Vault on https://vault.bitwarden.com, or your self-hosted instance
16-
2. Click on "Settings" and then "My Account"
17-
3. Scroll down to the "API Key" section
18-
4. Click on "View API Key" (or maybe another label if it's the first time)
19-
5. Save the API credentials
20-
6. Before running `terraform apply`, export the API credentials as environment variable:
29+
2. Click on _Settings_ and then _My Account_
30+
3. Scroll down to the _API Key_ section
31+
4. Click on _View API Key_ (or maybe another label if it's the first time)
32+
5. Save the API credentials somewhere safe
2133

22-
```console
23-
export TF_VAR_bw_client_id=<client_id>
24-
export TF_VAR_bw_client_secret=<client_secret>
25-
export TF_VAR_bw_password=<master_password>
34+
### Generating a Session Key
35+
36+
If you don't want to use an API key, you can use a Session Key instead.
37+
When doing so, it's your responsibility to:
38+
* ensure the validity of the Session Key
39+
* keep the Session Key safe
40+
* revoke it when you don't need it anymore
41+
42+
You can generate a Session Key by running the following command in your Terraform Workspace:
2643
```
44+
BITWARDENCLI_APPDATA_DIR=.bitwarden bw login
2745

28-
## Example Usage
46+
# or if you use a custom vault path
47+
BITWARDENCLI_APPDATA_DIR=<vault_path> bw login
48+
```
2949

30-
{{tffile "examples/quick/variables.tf"}}
50+
## Configuration
51+
Configuration for the Bitwarden Provider can be derived from two sources:
52+
* Parameters in the provider configuration
53+
* Environment variables
3154

32-
{{tffile "examples/quick/provider.tf"}}
55+
### Parameters
56+
Credentials can be provided by adding a `master_password` and optionally `client_id` and `client_secret` to the bitwarden provider block.
57+
```terraform
58+
provider "bitwarden" {
59+
email = "terraform@example.com"
60+
master_password = "my-master-password"
61+
client_id = "my-client-id"
62+
client_secret = "my-client-secret"
63+
}
64+
```
65+
66+
### Environment variables
67+
Credentials can be provided by using the `BW_PASSWORD` and optionally `BW_CLIENTID` and `BW_CLIENTSECRET` environment variables.
68+
69+
For example:
70+
```bitwarden
71+
provider "bitwarden" {}
72+
```
73+
74+
```console
75+
export BW_EMAIL="terraform@example.com"
76+
export BW_PASSWORD="my-master-password"
77+
export BW_CLIENTID="my-client-id"
78+
export BW_CLIENTSECRET="my-client-secret"
79+
```
3380

3481
{{ .SchemaMarkdown | trimspace }}
3582

0 commit comments

Comments
 (0)