Adds documentation (#65)

.editorconfig

@@ -8,3 +8,7 @@ end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
+
+[*.yml]
+indent_style = tab
+indent_size = 4

.gitignore

@@ -21,3 +21,6 @@ terraform.tfstate*
 # custom user federation example
 custom-user-federation-example/build
 !custom-user-federation-example/build/libs
+
+# docs
+site/

README.md

@@ -3,34 +3,9 @@ Terraform provider for [Keycloak](https://www.keycloak.org/).
 
 [![CircleCI](https://circleci.com/gh/mrparkers/terraform-provider-keycloak.svg?style=svg)](https://circleci.com/gh/mrparkers/terraform-provider-keycloak)
 
-## Features
-
-This project is a work in progress with a short term goal of supporting all of the Keycloak features that I need to manage at my place of employment.
-
-Long term, I'd like to support as much as I can while I tinker with Keycloak in my spare time.
-
-### Supported Resources
-
-- [`keycloak_realm`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_realm.go)
-- [`keycloak_user`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_user.go)
-- [`keycloak_group`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_group.go)
-- [`keycloak_group_memberships`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_group_memberships.go)
-- [`keycloak_openid_client`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_client.go)
-- [`keycloak_openid_client_scope`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_client_scope.go)
-- [`keycloak_openid_client_default_scopes`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_client_default_scopes.go)
-- [`keycloak_ldap_user_federation`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_ldap_user_federation.go)
-- [`keycloak_ldap_user_attribute_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_ldap_user_attribute_mapper.go)
-- [`keycloak_ldap_group_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_ldap_group_mapper.go)
-- [`keycloak_ldap_full_name_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_ldap_full_name_mapper.go)
-- [`keycloak_ldap_msad_user_account_control_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_ldap_msad_user_account_control_mapper.go)
-- [`keycloak_custom_user_federation`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_custom_user_federation.go)
-- [`keycloak_openid_user_attribute_protocol_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_user_attribute_protocol_mapper.go)
-- [`keycloak_openid_user_property_protocol_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_user_property_protocol_mapper.go)
-- [`keycloak_openid_group_membership_protocol_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_group_membership_protocol_mapper.go)
-- [`keycloak_openid_full_name_protocol_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_full_name_protocol_mapper.go)
-- [`keycloak_openid_hardcoded_claim_protocol_mapper`](https://github.com/mrparkers/terraform-provider-keycloak/blob/master/provider/keycloak_openid_hardcoded_claim_protocol_mapper.go)
-
-I will write some docs for each resource once more are supported. For now, please refer to the linked source files.
+## Docs
+
+https://mrparkers.github.io/terraform-provider-keycloak/
 
 ## Building
 

docs/index.css

@@ -0,0 +1,30 @@
+.section h5 {
+	margin-bottom: 15px;
+}
+
+.section p {
+	margin-bottom: 15px;
+}
+
+.section li {
+	line-height: 23px;
+	margin-bottom: 12px;
+}
+
+h1 {
+	font-size: 150%;
+}
+
+@media (min-width: 769px) {
+	.wy-nav-side, .rst-versions {
+		width: 410px;
+	}
+
+	.wy-nav-content-wrap {
+		margin-left: 410px;
+	}
+
+	h1 {
+		font-size: 175%;
+	}
+}

docs/index.md

@@ -0,0 +1,43 @@
+# Installing
+
+You can download the latest version of this provider on the
+[GitHub releases](https://github.com/mrparkers/terraform-provider-keycloak/releases)
+page.
+
+Please follow the [official docs](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins)
+for instructions on installing a third-party provider.
+
+# Keycloak Setup
+
+Currently, this Terraform provider is configured to use the client credentials grant with
+a client configured in the master realm. You can follow the steps below to configure a
+client that the Terraform provider can use:
+
+1. Create a client in the master realm using the `openid-connect` protocol.
+2. Update the following client settings:
+    - Set "Access Type" to "confidential".
+    - Set "Standard Flow Enabled" to "OFF".
+    - Set "Direct Access Grants Enabled" to "OFF".
+    - Set "Service Accounts Enabled" to "ON".
+3. Go to the "Service Account Roles" tab for the client, and grant it any roles that are
+needed to manage your instance of Keycloak. The "admin" role can be assigned to effectively
+manage all Keycloak settings.
+
+# Provider Setup
+
+The provider needs to be configured to use the master realm client configured in the
+previous step. The following provider attributes are supported:
+
+- `client_id` (Required) - The `client_id` for the client in the master realm setup in the previous step. Defaults to the environment variable `KEYCLOAK_CLIENT_ID`.
+- `client_secret` (Required) - The secret for this client, which can be found or changed using the "Credentials" tab in the client settings. Defaults to the environment variable `KEYCLOAK_CLIENT_SECRET`.
+- `url` (Required) - The URL of the Keycloak instance, before `/auth/admin`. Defaults to the environment variable `KEYCLOAK_URL`.
+
+#### Example
+
+```hcl
+provider "keycloak" {
+	client_id     = "terraform"
+	client_secret = "884e0f95-0f42-4a63-9b1f-94274655669e"
+	url           = "http://localhost:8080"
+}
+```

docs/resources/keycloak_custom_user_federation.md

@@ -0,0 +1,44 @@
+# keycloak_custom_user_federation
+
+Allows for creating and managing custom user federation providers within Keycloak.
+
+A custom user federation provider is an implementation of Keycloak's
+[User Storage SPI](https://www.keycloak.org/docs/4.2/server_development/index.html#_user-storage-spi).
+An example of this implementation can be found [here](https://github.com/mrparkers/terraform-provider-keycloak/tree/master/custom-user-federation-example).
+
+### Example Usage
+
+```hcl
+resource "keycloak_realm" "realm" {
+    realm   = "test"
+    enabled = true
+}
+
+resource "keycloak_custom_user_federation" "custom_user_federation" {
+    name        = "custom"
+    realm_id    = "${keycloak_realm.realm.id}"
+    provider_id = "custom"
+
+    enabled     = true
+}
+```
+
+### Argument Reference
+
+The following arguments are supported:
+
+- `realm_id` - (Required) The realm that this provider will provide user federation for.
+- `name` - (Required) Display name of the provider when displayed in the console.
+- `provider_id` - (Required) The unique ID of the custom provider, specified in the `getId` implementation for the `UserStorageProviderFactory` interface.
+- `enabled` - (Optional) When `false`, this provider will not be used when performing queries for users. Defaults to `true`.
+- `priority` - (Optional) Priority of this provider when looking up users. Lower values are first. Defaults to `0`.
+- `cache_policy` - (Optional) Can be one of `DEFAULT`, `EVICT_DAILY`, `EVICT_WEEKLY`, `MAX_LIFESPAN`, or `NO_CACHE`. Defaults to `DEFAULT`.
+
+### Import
+
+Custom user federation providers can be imported using the format `{{realm_id}}/{{custom_user_federation_id}}`.
+The ID of the custom user federation provider can be found within the Keycloak GUI and is typically a GUID:
+
+```bash
+$ terraform import keycloak_custom_user_federation.custom_user_federation my-realm/af2a6ca3-e4d7-49c3-b08b-1b3c70b4b860
+```

docs/resources/keycloak_group.md

@@ -0,0 +1,55 @@
+# keycloak_group
+
+Allows for creating and managing Groups within Keycloak.
+
+Groups provide a logical wrapping for users within Keycloak. Users within a
+group can share attributes and roles, and group membership can be mapped
+to a claim.
+
+Groups can also be federated from external data sources, such as LDAP or Active Directory.
+This resource **should not** be used to manage groups that were created this way.
+
+### Example Usage
+
+```hcl
+resource "keycloak_realm" "realm" {
+    realm   = "my-realm"
+    enabled = true
+}
+
+resource "keycloak_group" "parent_group" {
+    realm_id = "${keycloak_realm.realm.id}"
+    name     = "parent-group"
+}
+
+resource "keycloak_group" "child_group" {
+    realm_id  = "${keycloak_realm.realm.id}"
+    parent_id = "${keycloak_group.parent_group.id}"
+    name      = "child-group"
+}
+```
+
+### Argument Reference
+
+The following arguments are supported:
+
+- `realm_id` - (Required) The realm this group exists in.
+- `parent_id` - (Optional) The ID of this group's parent. If omitted, this group will be defined at the root level.
+- `name` - (Required) The name of the group.
+
+### Attributes Reference
+
+In addition to the arguments listed above, the following computed attributes are exported:
+
+- `path` - The complete path of the group. For example, the child group's path in the example configuration would be `/parent-group/child-group`.
+
+### Import
+
+Groups can be imported using the format `{{realm_id}}/{{group_id}}`, where `group_id` is the unique ID that Keycloak
+assigns to the group upon creation. This value can be found in the URI when editing this group in the GUI, and is typically a GUID.
+
+Example:
+
+```bash
+$ terraform import keycloak_group.child_group my-realm/934a4a4e-28bd-4703-a0fa-332df153aabd
+```

docs/resources/keycloak_group_memberships.md

@@ -0,0 +1,53 @@
+# keycloak_group_memberships
+
+Allows for managing a Keycloak group's members.
+
+Note that this resource attempts to be an **authoritative** source over group members.
+When this resource takes control over a group's members, users that are manually added
+to the group will be removed, and users that are manually removed from the group will
+be added upon the next run of `terraform apply`.  Eventually, a non-authoritative resource
+for group membership will be added to this provider.
+
+This resource **should not** be used to control membership of a group that has its members
+federated from an external source via group mapping.
+
+### Example Usage
+
+```hcl
+resource "keycloak_realm" "realm" {
+    realm   = "my-realm"
+    enabled = true
+}
+
+resource "keycloak_group" "group" {
+    realm_id = "${keycloak_realm.realm.id}"
+    name     = "my-group"
+}
+
+resource "keycloak_user" "user" {
+	realm_id = "${keycloak_realm.realm.id}"
+	username = "my-user"
+}
+
+resource "keycloak_group_memberships" "group_members" {
+	realm_id = "${keycloak_realm.realm.id}"
+	group_id = "${keycloak_group.group.id}"
+
+	members  = [
+		"${keycloak_user.user.username}"
+	]
+}
+```
+
+### Argument Reference
+
+The following arguments are supported:
+
+- `realm_id` - (Required) The realm this group exists in.
+- `group_id` - (Required) The ID of the group this resource should manage memberships for.
+- `members` - (Required) An array of usernames that belong to this group.
+
+### Import
+
+This resource does not support import. Instead of importing, feel free to create this resource
+as if it did not already exist on the server.

docs/resources/keycloak_ldap_full_name_mapper.md

@@ -0,0 +1,61 @@
+# keycloak_ldap_full_name_mapper
+
+Allows for creating and managing full name mappers for Keycloak users federated
+via LDAP.
+
+The LDAP full name mapper can map a user's full name from an LDAP attribute
+to the first and last name attributes of a Keycloak user.
+
+### Example Usage
+
+```hcl
+resource "keycloak_realm" "realm" {
+    realm   = "test"
+    enabled = true
+}
+
+resource "keycloak_ldap_user_federation" "ldap_user_federation" {
+	name                    = "openldap"
+	realm_id                = "${keycloak_realm.realm.id}"
+
+	username_ldap_attribute = "cn"
+	rdn_ldap_attribute      = "cn"
+	uuid_ldap_attribute     = "entryDN"
+	user_object_classes     = [
+		"simpleSecurityObject",
+		"organizationalRole"
+	]
+	connection_url          = "ldap://openldap"
+	users_dn                = "dc=example,dc=org"
+	bind_dn                 = "cn=admin,dc=example,dc=org"
+	bind_credential         = "admin"
+}
+
+resource "keycloak_ldap_full_name_mapper" "ldap_full_name_mapper" {
+	realm_id                 = "${keycloak_realm.realm.id}"
+	ldap_user_federation_id  = "${keycloak_ldap_user_federation.ldap_user_federation.id}"
+	name                     = "full-name-mapper"
+	ldap_full_name_attribute = "cn"
+}
+```
+
+### Argument Reference
+
+The following arguments are supported:
+
+- `realm_id` - (Required) The realm that this LDAP mapper will exist in.
+- `ldap_user_federation_id` - (Required) The ID of the LDAP user federation provider to attach this mapper to.
+- `name` - (Required) Display name of this mapper when displayed in the console.
+- `ldap_full_name_attribute` - (Required) The name of the LDAP attribute containing the user's full name.
+- `read_only` - (Optional) When `true`, updates to a user within Keycloak will not be written back to LDAP. Defaults to `false`.
+- `write_only` - (Optional) When `true`, this mapper will only be used to write updates to LDAP. Defaults to `false`.
+
+### Import
+
+LDAP mappers can be imported using the format `{{realm_id}}/{{ldap_user_federation_id}}/{{ldap_mapper_id}}`.
+The ID of the LDAP user federation provider and the mapper can be found within
+the Keycloak GUI, and they are typically GUIDs:
+
+```bash
+$ terraform import keycloak_ldap_full_name_mapper.ldap_full_name_mapper my-realm/af2a6ca3-e4d7-49c3-b08b-1b3c70b4b860/3d923ece-1a91-4bf7-adaf-3b82f2a12b67
+```