From 22350a822cf1c134a2210b0cf031cce41892ed02 Mon Sep 17 00:00:00 2001
From: Sergiu Ghitea <28300158+sergiught@users.noreply.github.com>
Date: Tue, 18 Oct 2022 09:24:54 +0200
Subject: [PATCH] DXCDT-248: Improve resource server RBAC docs (#371)

Improve resource server RBAC docs
---
 docs/resources/resource_server.md                   |  4 ++--
 internal/provider/resource_auth0_resource_server.go | 13 ++++++++-----
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/resources/resource_server.md b/docs/resources/resource_server.md
index 77759a044..e43c620ba 100644
--- a/docs/resources/resource_server.md
+++ b/docs/resources/resource_server.md
@@ -42,14 +42,14 @@ resource "auth0_resource_server" "my_resource_server" {
 ### Optional
 
 - `allow_offline_access` (Boolean) Indicates whether refresh tokens can be issued for this resource server.
-- `enforce_policies` (Boolean) Indicates whether authorization polices are enforced.
+- `enforce_policies` (Boolean) If this setting is enabled, RBAC authorization policies will be enforced for this API. Role and permission assignments will be evaluated during the login transaction.
 - `name` (String) Friendly name for the resource server. Cannot include `<` or `>` characters.
 - `options` (Map of String) Used to store additional metadata.
 - `scopes` (Block Set) List of permissions (scopes) used by this resource server. (see [below for nested schema](#nestedblock--scopes))
 - `signing_alg` (String) Algorithm used to sign JWTs. Options include `HS256` and `RS256`.
 - `signing_secret` (String) Secret used to sign tokens when using symmetric algorithms (HS256).
 - `skip_consent_for_verifiable_first_party_clients` (Boolean) Indicates whether to skip user consent for applications flagged as first party.
-- `token_dialect` (String) Dialect of access tokens that should be issued for this resource server. Options include `access_token` or `access_token_authz` (includes permissions).
+- `token_dialect` (String) Dialect of access tokens that should be issued for this resource server. Options include `access_token` or `access_token_authz`. If this setting is set to `access_token_authz`, the Permissions claim will be added to the access token. Only available if RBAC (`enforce_policies`) is enabled for this API.
 - `token_lifetime` (Number) Number of seconds during which access tokens issued for this resource server from the token endpoint remain valid.
 - `token_lifetime_for_web` (Number) Number of seconds during which access tokens issued for this resource server via implicit or hybrid flows remain valid. Cannot be greater than the `token_lifetime` value.
 - `verification_location` (String)
diff --git a/internal/provider/resource_auth0_resource_server.go b/internal/provider/resource_auth0_resource_server.go
index aae234d84..56a1ebc0e 100644
--- a/internal/provider/resource_auth0_resource_server.go
+++ b/internal/provider/resource_auth0_resource_server.go
@@ -119,10 +119,11 @@ func newResourceServer() *schema.Resource {
 				Description: "Used to store additional metadata.",
 			},
 			"enforce_policies": {
-				Type:        schema.TypeBool,
-				Computed:    true,
-				Optional:    true,
-				Description: "Indicates whether authorization polices are enforced.",
+				Type:     schema.TypeBool,
+				Computed: true,
+				Optional: true,
+				Description: "If this setting is enabled, RBAC authorization policies will be enforced for this API. " +
+					"Role and permission assignments will be evaluated during the login transaction.",
 			},
 			"token_dialect": {
 				Type:     schema.TypeString,
@@ -132,7 +133,9 @@ func newResourceServer() *schema.Resource {
 					"access_token_authz",
 				}, true),
 				Description: "Dialect of access tokens that should be issued for this resource server. " +
-					"Options include `access_token` or `access_token_authz` (includes permissions).",
+					"Options include `access_token` or `access_token_authz`. " +
+					"If this setting is set to `access_token_authz`, the Permissions claim will be added to the access token. " +
+					"Only available if RBAC (`enforce_policies`) is enabled for this API.",
 			},
 		},
 	}