feat: Add support for authentication with provided Keycloak Access Token (#1320)

- Allow users to use a provided access token for authentication
- Add test for authenticating with provided access token
- Add target to generate a current acces-token to the makefile
- Update github ci tests to support
- Add docs

Fixes #1319

Signed-off-by: Thomas Darimont <[email protected]>
Co-authored-by: Christopher Svensson <[email protected]>

Author: thomasdarimont

.github/workflows/test.yml

@@ -149,12 +149,12 @@ jobs:
 
         timeout-minutes: 60
 # Only run mtls test for the later versions
-      - name: Test (mtls client auth)
+      - name: Test (auth with mtls client certificate)
         if: matrix.keycloak-version == '26.3.4' || matrix.keycloak-version == '26.2.5'
         run: |
           terraform version
           go mod download
-          make testacc
+          make testauth
         env:
           KEYCLOAK_CLIENT_ID: terraform
           KEYCLOAK_CLIENT_SECRET: 884e0f95-0f42-4a63-9b1f-94274655669e
@@ -171,6 +171,23 @@ jobs:
 
         timeout-minutes: 60
 
+      - name: Test (auth with provided access token)
+        if: matrix.keycloak-version == '26.3.4' || matrix.keycloak-version == '26.2.5'
+        run: |
+          terraform version
+          go mod download
+          make access-token
+          export KEYCLOAK_ACCESS_TOKEN="$(cat ./keycloak_access_token)"
+          make testauth
+        env:
+          KEYCLOAK_CLIENT_ID: terraform
+          KEYCLOAK_CLIENT_TIMEOUT: 120
+          KEYCLOAK_REALM: master
+          KEYCLOAK_URL: "http://localhost:8080"
+          KEYCLOAK_VERSION: ${{ steps.keycloak-version.outputs.result }}
+
+        timeout-minutes: 60
+
       - name: Print container logs
         if: always()
         run: docker logs keycloak

.gitignore

@@ -36,6 +36,9 @@ site/
 # releases
 *.zip
 
+# Keycloak access token
+keycloak_access_token
+
 .DS_Store
 
 # Custom test_env overrides

README.md

@@ -145,7 +145,7 @@ KEYCLOAK_TLS_CA_CERT="$(cat provider/testdata/tls/server-cert.pem)" \
 make testacc
 ```
 
-#### Test with HTTPS + mTLS
+#### Test Authenticating with HTTPS + mTLS
 You can also run the same tests on Keycloak's https port with the Keycloak Terraform provider authenticating to the server with a mTLS client certificate.
 For this start the env with `make local-mtls`. After that run the following command:
 
@@ -160,7 +160,24 @@ KEYCLOAK_URL="https://localhost:8443" \
 KEYCLOAK_TLS_CLIENT_CERT="$(cat provider/testdata/tls/client-cert.pem)" \
 KEYCLOAK_TLS_CLIENT_KEY="$(cat provider/testdata/tls/client-key.pem)" \
 KEYCLOAK_TLS_CA_CERT="$(cat provider/testdata/tls/server-cert.pem)" \
-make testacc
+make testauth
+```
+
+#### Test Authenticating with provided Access Token
+You can also run the same test with a provided access token.
+For this start the env with `make local`. To obtain an access token for the admin user via the admin-cli client, run `make access-token` to
+store an acess token in the `./keycloak_access_token` file.
+
+After that run the following command:
+
+```
+make access-token
+KEYCLOAK_CLIENT_ID=terraform \
+KEYCLOAK_CLIENT_TIMEOUT=5 \
+KEYCLOAK_ACCESS_TOKEN="$(cat keycloak_access_token)" \
+KEYCLOAK_REALM=master \
+KEYCLOAK_URL="http://localhost:8080" \
+make testauth
 ```
 
 ### Run examples

docs/index.md

@@ -63,7 +63,17 @@ account within the `foo` realm.
 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`.
 
-## Example Usage (client credentials grant - client secret)
+## Authentication
+
+The Terraform Provider currently supports the following authentication methods:
+- Client-Credentials Grant (client_id + client_secret)
+- Password Grant (client_id (+client_secret), username, password)
+- Signed JWT (Private Key JWT)
+- Provided Access Token (pre-provisioned Keycloak Access Token)
+
+Additionally, the Terraform Provider also supports using an mTLS client certificate to access Keycloak.
+
+### Example Usage (client credentials grant - client secret)
 
 ```hcl
 provider "keycloak" {
@@ -73,7 +83,7 @@ provider "keycloak" {
 }
 ```
 
-## Example Usage (client credentials grant - private key signed JWT)
+### Example Usage (client credentials grant - private key signed JWT)
 
 ```hcl
 provider "keycloak" {
@@ -83,7 +93,7 @@ provider "keycloak" {
 }
 ```
 
-## Example Usage (password grant)
+### Example Usage (password grant)
 
 ```hcl
 provider "keycloak" {
@@ -94,6 +104,29 @@ provider "keycloak" {
 }
 ```
 
+### Example Usage (provided Token)
+
+```hcl
+provider "keycloak" {
+	client_id     = "admin-cli"
+	access_token  = "<encoded-access-token-here>"
+	url           = "http://localhost:8080"
+}
+```
+
+### Example Usage (mTLS Certificate)
+```hcl
+provider "keycloak" {
+	client_id     = "terraform"
+	client_secret = "884e0f95-0f42-4a63-9b1f-94274655669e"
+	jwt_signing_key = "<pem-formatted-private-key>"
+	tls_client_certificate = "<pem-formatted-client-certificate>"
+	tls_client_private_key = "<pem-formatted-client-key>"
+	root_ca_certificate = "<pem-formatted-server-certificate>"
+	url             = "https://localhost:8443"
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported:
@@ -104,6 +137,7 @@ The following arguments are supported:
 - `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 the 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 the environment variable `KEYCLOAK_PASSWORD`. This attribute is required when using the password grant, and cannot be set when using the client credentials grant.
+- `access_token` - (Optional) The access token that should be used by the provider for authentication via token. Defaults to the environment variable `KEYCLOAK_ACCESS_TOKEN`.
 - `jwt_signing_key` - (Optional) The PEM-formatted private key used by provider to generate a signed JWT for authentication.
 - `jwt_signing_alg` - (Optional) The signing algorithm used by provider to generate a signed JWT for authentication. Defaults to `RS256`.
 - `realm` - (Optional) The realm used by the provider for authentication. Defaults to the environment variable `KEYCLOAK_REALM`, or `master` if the environment variable is not specified.

helper/helpers.go

@@ -5,8 +5,34 @@ import (
 	"fmt"
 	"log"
 	"os"
+	"testing"
 )
 
+var requiredEnvironmentVariables = []string{
+	"KEYCLOAK_CLIENT_ID",
+	"KEYCLOAK_URL",
+	"KEYCLOAK_REALM",
+}
+
+var requiredEnvironmentVariablesForTokenAuth = []string{
+	"KEYCLOAK_REALM",
+	"KEYCLOAK_URL",
+}
+
+func CheckRequiredEnvironmentVariables(t *testing.T) {
+
+	requiredEnvVars := requiredEnvironmentVariables
+	if os.Getenv("KEYCLOAK_ACCESS_TOKEN") != "" {
+		requiredEnvVars = requiredEnvironmentVariablesForTokenAuth
+	}
+
+	for _, requiredEnvironmentVariable := range requiredEnvVars {
+		if value := os.Getenv(requiredEnvironmentVariable); value == "" {
+			t.Fatalf("%s must be set before running acceptance tests.", requiredEnvironmentVariable)
+		}
+	}
+}
+
 func UpdateEnvFromTestEnvIfPresent() {
 
 	testEnvFile := os.Getenv("TEST_ENV_FILE")