From b9c8c4ff8989eaec6cce074e15b0fcec9eda11ff Mon Sep 17 00:00:00 2001
From: Pavol Ipoth <pavol.ipoth@protonmail.com>
Date: Mon, 28 Oct 2024 22:44:42 +0100
Subject: [PATCH] Adding docu for Level of Authentication

---
 docs/content/configuration/_index.md |  1 +
 docs/content/userguide/_index.md     | 16 +++++++++
 pkg/apperrors/apperrors.go           |  1 +
 pkg/keycloak/config/config.go        |  3 ++
 pkg/keycloak/config/config_test.go   | 49 ++++++++++++++++++++++++++++
 5 files changed, 70 insertions(+)

diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md
index 994f9775..e255b676 100644
--- a/docs/content/configuration/_index.md
+++ b/docs/content/configuration/_index.md
@@ -138,6 +138,7 @@ weight: 2
 |    --forwarding-username value              | username to use when logging into the openid provider | | PROXY_FORWARDING_USERNAME
 |    --forwarding-password value              | password to use when logging into the openid provider | | PROXY_FORWARDING_PASSWORD
 |    --forwarding-domains value               | list of domains which should be signed; everything else is relayed unsigned | |
+|    --enable-loa                             | enable level of authentication            | false |
 |    --disable-all-logging                    | disables all logging to stdout and stderr | false | PROXY_DISABLE_ALL_LOGGING
 |    --help, -h                               | show help
 |    --version, -v                            | print the version
diff --git a/docs/content/userguide/_index.md b/docs/content/userguide/_index.md
index 8cb6929b..de49f961 100644
--- a/docs/content/userguide/_index.md
+++ b/docs/content/userguide/_index.md
@@ -1127,6 +1127,22 @@ UNIX socket, `--upstream-url unix://path/to/the/file.sock`.
 
   - **/oauth/discovery** provides endpoint with basic urls gatekeeper provides
 
+## Level Of Authentication (Application Context Class Reference - ACR)
+
+Level Of Authentication or Step up authentication enables to raise required level of authentication while
+accessing certain resources.
+For setting up please first check keycloak documentation https://www.keycloak.org/docs/latest/server_admin/index.html#_step-up-flow.
+To configure it on gatekeeper side you will need to use option `--enable-loa=true` and configure resources:
+
+```yaml
+  --resources=uri=/cats|acr=level1,level2
+  --resources=uri=/pets|acr=level2
+```
+
+This example configures two URIs, first `/cats` accepts two level of authentications level1 or level2, in case
+token doesn't contain any of these levels, it redirects to authentication and uses first one `level1` as default one.
+Second URI `/pets` accepts one level of authentication `level2`. In case token contains level1 it redirets to authentication using `level2` acr value.
+
 ## External Authorization
 
 ### Open Policy Agent (OPA) authorization
diff --git a/pkg/apperrors/apperrors.go b/pkg/apperrors/apperrors.go
index 8415fcf2..494b3c42 100644
--- a/pkg/apperrors/apperrors.go
+++ b/pkg/apperrors/apperrors.go
@@ -159,6 +159,7 @@ var (
 	ErrMissingDefaultQueryParamInAllowed    = errors.New("param is present in default query params but missing in allowed")
 	ErrDefaultQueryParamNotAllowed          = errors.New("default query param is not in allowed query params")
 	ErrLoAWithNoRedirects                   = errors.New("level of authentication is not valid with noredirects=true")
+	ErrLoaWithUMA                           = errors.New("level of authentication is not valid with enable-uma")
 
 	ErrCertSelfNoHostname    = errors.New("no hostnames specified")
 	ErrCertSelfLowExpiration = errors.New("expiration must be greater then 5 minutes")
diff --git a/pkg/keycloak/config/config.go b/pkg/keycloak/config/config.go
index 44db35f8..c089fb8d 100644
--- a/pkg/keycloak/config/config.go
+++ b/pkg/keycloak/config/config.go
@@ -904,5 +904,8 @@ func (r *Config) isEnableLoAValid() error {
 	if r.EnableLoA && r.NoRedirects {
 		return apperrors.ErrLoAWithNoRedirects
 	}
+	if r.EnableLoA && r.EnableUma {
+		return apperrors.ErrLoaWithUMA
+	}
 	return nil
 }
diff --git a/pkg/keycloak/config/config_test.go b/pkg/keycloak/config/config_test.go
index 7ac2e1f8..0222c768 100644
--- a/pkg/keycloak/config/config_test.go
+++ b/pkg/keycloak/config/config_test.go
@@ -2543,3 +2543,52 @@ func TestIsAllowedQueryParamsValid(t *testing.T) {
 		)
 	}
 }
+
+func TestEnableLoa(t *testing.T) {
+	testCases := []struct {
+		Name   string
+		Config *Config
+		Valid  bool
+	}{
+		{
+			Name: "ValidEnabLoA",
+			Config: &Config{
+				EnableLoA:   true,
+				NoRedirects: false,
+			},
+			Valid: true,
+		},
+		{
+			Name: "InvalidWithNoRedirects",
+			Config: &Config{
+				EnableLoA:   true,
+				NoRedirects: false,
+			},
+			Valid: false,
+		},
+		{
+			Name: "InvalidWithEnableUMA",
+			Config: &Config{
+				EnableLoA: true,
+				EnableUma: true,
+			},
+			Valid: false,
+		},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(
+			testCase.Name,
+			func(t *testing.T) {
+				err := testCase.Config.isEnableHmacValid()
+				if err != nil && testCase.Valid {
+					t.Fatalf("Expected test not to fail")
+				}
+
+				if err == nil && !testCase.Valid {
+					t.Fatalf("Expected test to fail")
+				}
+			},
+		)
+	}
+}