DXCDT-429: auth0_resource_server_scope resource

MIGRATION_GUIDE.md

@@ -8,14 +8,13 @@ automated workflows before upgrading.
 ### Deprecations
 
 - [Client Authentication Method](#client-authentication-method)
-
+- [Resource Server Scopes](#resource-server-scopes)
 
 #### Client Authentication Method
 
-
 The `token_endpoint_auth_method` field on the `auth0_client` resource will continue to be available for managing the
-client's authentication method. However, to ensure a smooth transition when we eventually remove the capability to 
-manage the authentication method through this field, we recommend proactively migrating to the newly introduced 
+client's authentication method. However, to ensure a smooth transition when we eventually remove the capability to
+manage the authentication method through this field, we recommend proactively migrating to the newly introduced
 `auth0_client_credentials` resource as this will also give you the possibility of managing the client secret.
 This will help you stay prepared for future changes.
 
@@ -31,7 +30,7 @@ This will help you stay prepared for future changes.
 # Example:
 resource "auth0_client" "my_client" {
   name = "My Client"
-  
+
   token_endpoint_auth_method = "client_secret_post"
 }
 ```
@@ -56,6 +55,68 @@ resource "auth0_client_credentials" "test" {
 </tr>
 </table>
 
+#### Resource Server Scopes
+
+The `scopes` field on the `auth0_resource_server` resource will continue to be available for managing resource server scopes. However, to ensure a smooth transition when we eventually remove the capability to manage scopes through this field, we recommend proactively migrating to the newly introduced `auth0_resource_server_scope` resource. This will help you stay prepared for future changes.
+
+<table>
+<tr>
+<th>Before (v0.47.0)</th>
+<th>After (v0.48.0)</th>
+</tr>
+<tr>
+<td>
+
+```terraform
+resource auth0_resource_server api {
+  name       = "Example API"
+  identifier = "https://api.travel0.com/"
+
+  scopes {
+    value       = "read:posts"
+    description = "Can read posts"
+  }
+
+  scopes {
+    value       = "write:posts"
+    description = "Can write posts"
+  }
+}
+```
+
+</td>
+<td>
+
+```terraform
+resource auth0_resource_server api {
+  name       = "Example API"
+  identifier = "https://api.travel0.com/"
+
+  # Until we remove the ability to operate changes on
+  # the scopes field it is important to have this
+  # block in the config, to avoid diffing issues.
+  lifecycle {
+    ignore_changes = [scopes]
+  }
+}
+
+resource auth0_resource_server_scope read_posts {
+  resource_server_identifier = auth0_resource_server.api.identifier
+  scope       = "read:posts"
+  description = "Can read posts"
+}
+
+resource auth0_resource_server_scope write_posts {
+  resource_server_identifier = auth0_resource_server.api.identifier
+  scope       = "write:posts"
+  description = "Can write posts"
+}
+```
+
+</td>
+</tr>
+</table>
+
 ## Upgrading from v0.46.0 → v0.47.0
 
 There are deprecations in this update. Please ensure you read this guide thoroughly and prepare your potential

docs/resources/resource_server.md

@@ -44,7 +44,7 @@ resource "auth0_resource_server" "my_resource_server" {
 - `allow_offline_access` (Boolean) Indicates whether refresh tokens can be issued for this resource server.
 - `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.
-- `scopes` (Block Set) List of permissions (scopes) used by this resource server. (see [below for nested schema](#nestedblock--scopes))
+- `scopes` (Block Set, Deprecated) 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.

docs/resources/resource_server_scope.md

@@ -0,0 +1,65 @@
+---
+page_title: "Resource: auth0_resource_server_scope"
+description: |-
+  With this resource, you can manage scopes (permissions) associated with a resource server (API).
+---
+
+# Resource: auth0_resource_server_scope
+
+With this resource, you can manage scopes (permissions) associated with a resource server (API).
+
+## Example Usage
+
+```terraform
+resource "auth0_resource_server" "resource_server" {
+  name       = "Example Resource Server (Managed by Terraform)"
+  identifier = "https://api.example.com"
+
+  # Until we remove the ability to operate changes on
+  # the scopes field it is important to have this
+  # block in the config, to avoid diffing issues.
+  lifecycle {
+    ignore_changes = [scopes]
+  }
+}
+
+resource "auth0_resource_server_scope" "read_posts" {
+  resource_server_identifier = auth0_resource_server.resource_server.identifier
+  scope                      = "read:posts"
+}
+
+resource "auth0_resource_server_scope" "write_posts" {
+  resource_server_identifier = auth0_resource_server.resource_server.identifier
+  scope                      = "write:posts"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `resource_server_identifier` (String) Identifier of the resource server that the scope (permission) is associated with.
+- `scope` (String) Name of the scope.
+
+### Optional
+
+- `description` (String) Description of the scope (permission).
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# This resource can be imported by specifying the
+# resource identifier and scope name separated by "::" (note the double colon)
+# <resourceServerIdentifier>::<scope>
+
+#
+# Example:
+terraform import auth0_resource_server_scope.scope "https://api.travel0.com/v1::read:posts"
+```

examples/resources/auth0_resource_server_scope/import.sh

@@ -0,0 +1,7 @@
+# This resource can be imported by specifying the
+# resource identifier and scope name separated by "::" (note the double colon)
+# <resourceServerIdentifier>::<scope>
+
+#
+# Example:
+terraform import auth0_resource_server_scope.scope "https://api.travel0.com/v1::read:posts"

examples/resources/auth0_resource_server_scope/resource.tf

@@ -0,0 +1,21 @@
+resource "auth0_resource_server" "resource_server" {
+  name       = "Example Resource Server (Managed by Terraform)"
+  identifier = "https://api.example.com"
+
+  # Until we remove the ability to operate changes on
+  # the scopes field it is important to have this
+  # block in the config, to avoid diffing issues.
+  lifecycle {
+    ignore_changes = [scopes]
+  }
+}
+
+resource "auth0_resource_server_scope" "read_posts" {
+  resource_server_identifier = auth0_resource_server.resource_server.identifier
+  scope                      = "read:posts"
+}
+
+resource "auth0_resource_server_scope" "write_posts" {
+  resource_server_identifier = auth0_resource_server.resource_server.identifier
+  scope                      = "write:posts"
+}

internal/auth0/resourceserver/resource.go

@@ -43,8 +43,11 @@ func NewResource() *schema.Resource {
 					"for authorization calls. Cannot be changed once set.",
 			},
 			"scopes": {
-				Type:        schema.TypeSet,
-				Optional:    true,
+				Type:     schema.TypeSet,
+				Optional: true,
+				Deprecated: "Managing scopes through the `scopes` attribute is deprecated and it will be changed to read-only in a future version. " +
+					"Migrate to the `auth0_resource_server_scope` resource to manage role scopes instead. " +
+					"Check the [MIGRATION GUIDE](https://github.com/auth0/terraform-provider-auth0/blob/main/MIGRATION_GUIDE.md) for more info.",
 				Description: "List of permissions (scopes) used by this resource server.",
 				Elem: &schema.Resource{
 					Schema: map[string]*schema.Schema{
@@ -198,8 +201,12 @@ func readResourceServer(_ context.Context, d *schema.ResourceData, m interface{}
 
 func updateResourceServer(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
 	api := m.(*config.Config).GetAPI()
+	mutex := m.(*config.Config).GetMutex()
 
 	resourceServer := expandResourceServer(d)
+	mutex.Lock(resourceServer.GetIdentifier())
+	defer mutex.Unlock(resourceServer.GetIdentifier())
+
 	if err := api.ResourceServer.Update(d.Id(), resourceServer); err != nil {
 		return diag.FromErr(err)
 	}