-
Notifications
You must be signed in to change notification settings - Fork 307
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update docs to use Terraform registry format, backfill some missing d…
…ocs (#366)
- Loading branch information
Showing
116 changed files
with
4,359 additions
and
56 deletions.
There are no files selected for viewing
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
# 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 | ||
|
||
This Terraform provider can be configured to use the [client credentials](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) | ||
or [password](https://www.oauth.com/oauth2-servers/access-tokens/password-grant/) grant types. If you aren't | ||
sure which to use, the client credentials grant is recommended, as it was designed for machine to machine authentication. | ||
|
||
## Client Credentials Grant Setup (recommended) | ||
|
||
1. Create a new client using the `openid-connect` protocol. This client can be created in the `master` realm if you would | ||
like to manage your entire Keycloak instance, or in any other realm if you only want to manage that realm. | ||
1. Update the client you just created: | ||
1. Set "Access Type" to "confidential". | ||
1. Set "Standard Flow Enabled" to "OFF". | ||
1. Set "Direct Access Grants Enabled" to "OFF" | ||
1. Set "Service Accounts Enabled" to "ON". | ||
1. Grant required roles for managing Keycloak via the "Service Account Roles" tab in the client you created in step 1. | ||
|
||
## Password Grant Setup | ||
|
||
These steps will assume that you are using the `admin-cli` client, which is already correctly configured for this type | ||
of authentication. Do not follow these steps if you have already followed the steps for the client credentials grant. | ||
|
||
1. Create or identify the user whose credentials will be used for authentication. | ||
1. Edit this user in the "Users" section of the management console and assign roles using the "Role Mappings" tab. | ||
|
||
## Assigning Roles | ||
|
||
There are many ways that roles can be assigned to manage Keycloak. Here are a couple of common scenarios accompanied | ||
by suggested roles to assign. This is not an exhaustive list, and there is often more than one way to assign a particular set | ||
of permissions. | ||
|
||
- Managing the entire Keycloak instance: Assign the `admin` role to a user or service account within the `master` realm. | ||
- Managing the entire `foo` realm: Assign the `realm-admin` client role from the `realm-management` client to a user or service | ||
account within the `foo` realm. | ||
- Managing clients for all realms within the entire Keycloak instance: Assign the `create-client` client role from each of | ||
the realm clients to a user or service account within the `master` realm. For example, given a Keycloak instance with realms | ||
`master`, `foo`, and `bar`, assign the `create-client` client role from the clients `master-realm`, `foo-realm`, and `bar-realm`. | ||
|
||
# Provider Setup | ||
|
||
The following provider attributes are supported: | ||
|
||
- `client_id` (Required) - The `client_id` for the client that was created in the "Keycloak Setup" section. Use the `admin-cli` client if you are using the password grant. Defaults to the environment variable `KEYCLOAK_CLIENT_ID`. | ||
- `url` (Required) - The URL of the Keycloak instance, before `/auth/admin`. Defaults to the environment variable `KEYCLOAK_URL`. | ||
- `client_secret` (Optional) - The secret for the client used by the provider for authentication via the client credentials grant. This can be found or changed using the "Credentials" tab in the client settings. Defaults to the environment variable `KEYCLOAK_CLIENT_SECRET`. This attribute is required when using the client credentials grant, and cannot be set when using the password grant. | ||
- `username` (Optional) - The username of the user used by the provider for authentication via the password grant. Defaults to environment variable `KEYCLOAK_USER`. This attribute is required when using the password grant, and cannot be set when using the client credentials grant. | ||
- `password` (Optional) - The password of the user used by the provider for authentication via the password grant. Defaults to environment variable `KEYCLOAK_PASSWORD`. This attribute is required when using the password grant, and cannot be set when using the client credentials grant. | ||
- `realm` (Optional) - The realm used by the provider for authentication. Defaults to environment variable `KEYCLOAK_REALM`, or `master` if the environment variable is not specified. | ||
- `initial_login` (Optional) - Optionally avoid Keycloak login during provider setup, for when Keycloak itself is being provisioned by terraform. Defaults to true, which is the original method. | ||
- `client_timeout` (Optional) - Sets the timeout of the client when addressing Keycloak, in seconds. Defaults to environment variable `KEYCLOAK_CLIENT_TIMEOUT`, or 5 is the environment variable is not specified. | ||
- `tls_insecure_skip_verify` (Optional) - Allows ignoring insecure certificates when set to true. Defaults to false. Disabling security check is dangerous and should be avoided. | ||
- `root_ca_certificate` (Optional) - Allows x509 calls using an unknown CA certificate (for development purposes) | ||
- `base_path` (Optional) - The base path used for accessing the Keycloak REST API. Defaults to `/auth` | ||
|
||
#### Example (client credentials) | ||
|
||
```hcl | ||
provider "keycloak" { | ||
client_id = "terraform" | ||
client_secret = "884e0f95-0f42-4a63-9b1f-94274655669e" | ||
url = "http://localhost:8080" | ||
} | ||
``` | ||
|
||
#### Example (password) | ||
|
||
```hcl | ||
provider "keycloak" { | ||
client_id = "admin-cli" | ||
username = "keycloak" | ||
password = "password" | ||
url = "http://localhost:8080" | ||
} | ||
``` |
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,47 @@ | ||
--- | ||
page_title: "keycloak_group Data Source" | ||
--- | ||
|
||
# keycloak\_group Data Source | ||
|
||
This data source can be used to fetch properties of a Keycloak group for | ||
usage with other resources, such as `keycloak_group_roles`. | ||
|
||
## Example Usage | ||
|
||
```hcl | ||
resource "keycloak_realm" "realm" { | ||
realm = "my-realm" | ||
enabled = true | ||
} | ||
data "keycloak_role" "offline_access" { | ||
realm_id = keycloak_realm.realm.id | ||
name = "offline_access" | ||
} | ||
data "keycloak_group" "group" { | ||
realm_id = keycloak_realm.realm.id | ||
name = "group" | ||
} | ||
resource "keycloak_group_roles" "group_roles" { | ||
realm_id = keycloak_realm.realm.id | ||
group_id = data.keycloak_group.group.id | ||
role_ids = [ | ||
data.keycloak_role.offline_access.id | ||
] | ||
} | ||
``` | ||
|
||
## Argument Reference | ||
|
||
- `realm_id` - (Required) The realm this group exists within. | ||
- `name` - (Required) The name of the group. If there are multiple groups match `name`, the first result will be returned. | ||
|
||
## Attributes Reference | ||
|
||
- `id` - (Computed) The unique ID of the group, which can be used as an argument to | ||
other resources supported by this provider. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
--- | ||
page_title: "keycloak_openid_client Data Source" | ||
--- | ||
|
||
# keycloak\_openid\_client Data Source | ||
|
||
This data source can be used to fetch properties of a Keycloak OpenID client for usage with other resources. | ||
|
||
## Example Usage | ||
|
||
```hcl | ||
data "keycloak_openid_client" "realm_management" { | ||
realm_id = "my-realm" | ||
client_id = "realm-management" | ||
} | ||
# use the data source | ||
data "keycloak_role" "admin" { | ||
realm_id = "my-realm" | ||
client_id = data.keycloak_openid_client.realm_management.id | ||
name = "realm-admin" | ||
} | ||
``` | ||
|
||
## Argument Reference | ||
|
||
- `realm_id` - (Required) The realm id. | ||
- `client_id` - (Required) The client id (not its unique ID). | ||
|
||
## Attributes Reference | ||
|
||
See the docs for the `keycloak_openid_client` resource for details on the exported attributes. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,83 @@ | ||
--- | ||
page_title: "keycloak_openid_client_authorization_policy Data Source" | ||
--- | ||
|
||
# keycloak\_openid\_client\_authorization\_policy Data Source | ||
|
||
This data source can be used to fetch policy and permission information for an OpenID client that has authorization enabled. | ||
|
||
## Example Usage | ||
|
||
In this example, we'll create a new OpenID client with authorization enabled. This will cause Keycloak to create a default | ||
permission for this client called "Default Permission". We'll use the `keycloak_openid_client_authorization_policy` data | ||
source to fetch information about this permission, so we can use it to create a new resource-based authorization permission. | ||
|
||
```hcl | ||
resource "keycloak_realm" "realm" { | ||
realm = "my-realm" | ||
enabled = true | ||
} | ||
resource "keycloak_openid_client" "client_with_authz" { | ||
client_id = "client-with-authz" | ||
name = "client-with-authz" | ||
realm_id = keycloak_realm.realm.id | ||
access_type = "CONFIDENTIAL" | ||
service_accounts_enabled = true | ||
authorization { | ||
policy_enforcement_mode = "ENFORCING" | ||
} | ||
} | ||
data "keycloak_openid_client_authorization_policy" "default_permission" { | ||
realm_id = keycloak_realm.test.id | ||
resource_server_id = keycloak_openid_client.client_with_authz.resource_server_id | ||
name = "Default Permission" | ||
} | ||
resource "keycloak_openid_client_authorization_resource" "resource" { | ||
resource_server_id = keycloak_openid_client.client_with_authz.resource_server_id | ||
name = "authorization-resource" | ||
realm_id = keycloak_realm.test.id | ||
uris = [ | ||
"/endpoint/*", | ||
] | ||
attributes = { | ||
"foo" = "bar" | ||
} | ||
} | ||
resource "keycloak_openid_client_authorization_permission" "permission" { | ||
resource_server_id = keycloak_openid_client.client_with_authz.resource_server_id | ||
realm_id = keycloak_realm.test.id | ||
name = "authorization-permission" | ||
policies = [ | ||
data.keycloak_openid_client_authorization_policy.default_permission.id, | ||
] | ||
resources = [ | ||
keycloak_openid_client_authorization_resource.resource.id, | ||
] | ||
} | ||
``` | ||
|
||
## Argument Reference | ||
|
||
- `realm_id` - (Required) The realm this authorization policy exists within. | ||
- `name` - (Required) The name of the authorization policy. | ||
- `resource_server_id` - (Required) The ID of the resource server this authorization policy is attached to. | ||
|
||
## Attributes Reference | ||
|
||
- `decision_strategy` - (Computed) Dictates how the policies associated with a given permission are evaluated and how a final decision is obtained. Could be one of `AFFIRMATIVE`, `CONSENSUS`, or `UNANIMOUS`. Applies to permissions. | ||
- `owner` - (Computed) The ID of the owning resource. Applies to resources. | ||
- `logic` - (Computed) Dictates how the policy decision should be made. Can be either `POSITIVE` or `NEGATIVE`. Applies to policies. | ||
- `policies` - (Computed) The IDs of the policies that must be applied to scopes/resources for this policy/permission. Applies to policies and permissions. | ||
- `resources` - (Computed) The IDs of the resources that this permission applies to. Applies to resource-based permissions. | ||
- `scopes` - (Computed) The IDs of the scopes that this permission applies to. Applies to scope-based permissions. | ||
- `type` - (Computed) The type of this policy / permission. For permissions, this could be `resource` or `scope`. For policies, this could be any type of authorization policy, such as `js`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,64 @@ | ||
--- | ||
page_title: "keycloak_openid_client_service_account_user Data Source" | ||
--- | ||
|
||
# keycloak\_openid\_client\_service\_account\_user Data Source | ||
|
||
This data source can be used to fetch information about the service account user that is associated with an OpenID client | ||
that has service accounts enabled. | ||
|
||
## Example Usage | ||
|
||
In this example, we'll create an OpenID client with service accounts enabled. This causes Keycloak to create a special user | ||
that represents the service account. We'll use this data source to grab this user's ID in order to assign some roles to this | ||
user, using the `keycloak_user_roles` resource. | ||
|
||
```hcl | ||
resource "keycloak_realm" "realm" { | ||
realm = "my-realm" | ||
enabled = true | ||
} | ||
resource "keycloak_openid_client" "client" { | ||
realm_id = keycloak_realm.realm.id | ||
client_id = "client" | ||
name = "client" | ||
access_type = "CONFIDENTIAL" | ||
service_accounts_enabled = true | ||
} | ||
data "keycloak_openid_client_service_account_user" "service_account_user" { | ||
realm_id = keycloak_realm.realm.id | ||
client_id = keycloak_openid_client.client.id | ||
} | ||
data "keycloak_role" "offline_access" { | ||
realm_id = keycloak_realm.realm.id | ||
name = "offline_access" | ||
} | ||
resource "keycloak_user_roles" "service_account_user_roles" { | ||
realm_id = keycloak_realm.realm.id | ||
user_id = data.keycloak_openid_client_service_account_user.service_account_user.id | ||
role_ids = [ | ||
data.keycloak_role.offline_access.id | ||
] | ||
} | ||
``` | ||
|
||
## Argument Reference | ||
|
||
- `realm_id` - (Required) The realm that the OpenID client exists within. | ||
- `client_id` - (Required) The ID of the OpenID client with service accounts enabled. | ||
|
||
## Attributes Reference | ||
|
||
`username` - (Computed) The service account user's username. | ||
`email` - (Computed) The service account user's email. | ||
`first_name` - (Computed) The service account user's first name. | ||
`last_name` - (Computed) The service account user's last name. | ||
`enabled` - (Computed) Whether or not the service account user is enabled. | ||
`attributes` - (Computed) The service account user's attributes. | ||
`federated_identities` - (Computed) This attribute exists in order to adhere to the spec of a Keycloak user, but a service account user will never have a federated identity, so this will always be `null`. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
--- | ||
page_title: "keycloak_realm Data Source" | ||
--- | ||
|
||
# keycloak\_realm Data Source | ||
|
||
This data source can be used to fetch properties of a Keycloak realm for | ||
usage with other resources. | ||
|
||
## Example Usage | ||
|
||
```hcl | ||
data "keycloak_realm" "realm" { | ||
realm = "my-realm" | ||
} | ||
# use the data source | ||
resource "keycloak_role" "group" { | ||
realm_id = data.keycloak_realm.realm.id | ||
name = "group" | ||
} | ||
``` | ||
|
||
## Argument Reference | ||
|
||
- `realm` - (Required) The realm name. | ||
|
||
## Attributes Reference | ||
|
||
See the docs for the `keycloak_realm` resource for details on the exported attributes. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,52 @@ | ||
--- | ||
page_title: "keycloak_realm_keys Data Source" | ||
--- | ||
|
||
# keycloak\_realm\_keys Data Source | ||
|
||
Use this data source to get the keys of a realm. Keys can be filtered by algorithm and status. | ||
|
||
Remarks: | ||
|
||
- A key must meet all filter criteria | ||
- This data source may return more than one value. | ||
- If no key matches the filter criteria, then an error will be returned. | ||
|
||
## Example Usage | ||
|
||
```hcl | ||
resource "keycloak_realm" "realm" { | ||
realm = "my-realm" | ||
enabled = true | ||
} | ||
data "keycloak_realm_keys" "realm_keys" { | ||
realm_id = keycloak_realm.realm | ||
algorithms = ["AES", "RS256"] | ||
status = ["ACTIVE", "PASSIVE"] | ||
} | ||
# show certificate of first key: | ||
output "certificate" { | ||
value = data.keycloak_realm_keys.realm_keys.keys[0].certificate | ||
} | ||
``` | ||
|
||
## Argument Reference | ||
|
||
- `realm_id` - (Required) The realm from which the keys will be retrieved. | ||
- `algorithms` - (Optional) When specified, keys will be filtered by algorithm. The algorithms can be any of `HS256`, `RS256`,`AES`, etc. | ||
- `status` - (Optional) When specified, keys will be filtered by status. The statuses can be any of `ACTIVE`, `DISABLED` and `PASSIVE`. | ||
|
||
## Attributes Reference | ||
|
||
- `keys` - (Computed) A list of keys that match the filter criteria. Each key has the following attributes: | ||
- `algorithm` - Key algorithm (string) | ||
- `certificate` - Key certificate (string) | ||
- `provider_id` - Key provider ID (string) | ||
- `provider_priority` - Key provider priority (int64) | ||
- `kid` - Key ID (string) | ||
- `public_key` - Key public key (string) | ||
- `status` - Key status (string) | ||
- `type` - Key type (string) |
Oops, something went wrong.