diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 0901d3738..5d632585d 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -217,19 +217,17 @@ If you want to [delete your Identity]({% link _docs_integrate/delete-identities. Up until then, the data about the deletion process is stored in an object called IdentityDeletionProcess. It is possible to [cancel an IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) that hasn't reached the end of its grace period, yet. Since cancelled IdentityDeletionProcesses are stored, you can reach a situation in which there are multiple IdentityDeletionProcesses associated with the same Identity. -Note, however, that at all times there can only be at most one **active IdentityDeletionProcess**, i.e. with `"Approved"` as `status`, per Identity. - -| Name | Type | Description | Remarks | -| ----------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | | -| status | `"Approved"` \| `"Cancelled"` | The status of the IdentityDeletionProcess.
{::nomarkdown}{:/} | | -| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | | -| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | | -| approvedAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was approved. | | -| approvedByDevice | `string` \| `undefined` | The ID of the Device that approved the IdentityDeletionProcess. | | -| gracePeriodEndsAt | `string` \| `undefined` | A timestamp that describes when the Identity will be permanently deleted. Up until this moment, it is possible to cancel the IdentityDeletionProcess. | | -| cancelledAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was cancelled. | | -| cancelledByDevice | `string` \| `undefined` | The ID of the Device that cancelled the IdentityDeletionProcess. | | +Note, however, that at all times there can only be at most one **active IdentityDeletionProcess**, i.e. with `"Active"` as `status`, per Identity. + +| Name | Type | Description | Remarks | +| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| id | `string` | {% include descr_id class="IdentityDeletionProcess" prefix="IDP" %} | | +| status | `"Active"` \| `"Cancelled"` | The status of the IdentityDeletionProcess.
{::nomarkdown}{:/} | | +| createdAt | `string` \| `undefined` | {% include descr_createdAt class="IdentityDeletionProcess" %} | | +| createdByDevice | `string` \| `undefined` | {% include descr_createdByDevice class="IdentityDeletionProcess" %} | | +| gracePeriodEndsAt | `string` \| `undefined` | A timestamp that describes when the Identity will be permanently deleted. Up until this moment, it is possible to cancel the IdentityDeletionProcess. | | +| cancelledAt | `string` \| `undefined` | A timestamp that describes when the IdentityDeletionProcess was cancelled. | | +| cancelledByDevice | `string` \| `undefined` | The ID of the Device that cancelled the IdentityDeletionProcess. | | # Local Types diff --git a/_docs_integrate/delete-identities.md b/_docs_integrate/delete-identities.md index 5e7ff1301..3bd038d38 100644 --- a/_docs_integrate/delete-identities.md +++ b/_docs_integrate/delete-identities.md @@ -36,8 +36,8 @@ However, Integrators of Connectors can still delete their Identity by using [Con ## IdentityDeletionProcesses From a technical perspective, the process of Identity deletion is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). It can be uniquely identified by its `id`. -An IdentityDeletionProcess can have `"Approved"` or `"Cancelled"` as its `status`. -If an IdentityDeletionProcess has `"Approved"` as `status`, it is also referred to as an **active IdentityDeletionProcess**. +An IdentityDeletionProcess can have `"Active"` or `"Cancelled"` as its `status`. +If an IdentityDeletionProcess has `"Active"` as `status`, it is also referred to as an **active IdentityDeletionProcess**. There can be at most one active IdentityDeletionProcess per Identity. There are three [use cases]({% link _docs_integrate/use-cases.md %}) for getting one or more already existing [IdentityDeletionProcesses]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess): @@ -55,11 +55,11 @@ Whenever a new [IdentityDeletionProcess]({% link _docs_integrate/data-model-over ### Self-Initiated Identity Deletion An Identity can actively trigger its own process of deletion by executing the [Initiate IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}) use case. -Successful execution leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Approved"` as `status`. +Successful execution leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Active"` as `status`. The Identity is immediately in deletion and will be irreversibly deleted from the Backbone once the end of the associated grace period of the IdentityDeletionProcess specified within its `gracePeriodEndsAt` property has been reached. Within the grace period, the [Cancel IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) use case can be applied by the Identity if it no longer wants to be deleted. In this case, the `status` of the IdentityDeletionProcess changes to `"Cancelled"`. -Trying to cancel an IdentityDeletionProcess that does not have `"Approved"` as `status` causes an error with `error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess` as [error code]({% link _docs_integrate/error-codes.md %}) to be thrown. +Trying to cancel an IdentityDeletionProcess that does not have `"Active"` as `status` causes an error with `error.runtime.identityDeletionProcess.noApprovedIdentityDeletionProcess` as [error code]({% link _docs_integrate/error-codes.md %}) to be thrown. Furthermore, please note that the use of the [Initiate IdentityDeletionProcess]({% link _docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md %}) use case is not permitted if there is already an active IdentityDeletionProcess. The corresponding [error code]({% link _docs_integrate/error-codes.md %}) is given by `error.runtime.identityDeletionProcess.activeIdentityDeletionProcessAlreadyExists`. diff --git a/_docs_integrate/migration-from-v6-to-v7.md b/_docs_integrate/migration-from-v6-to-v7.md index 44422fe2f..a48aa7892 100644 --- a/_docs_integrate/migration-from-v6-to-v7.md +++ b/_docs_integrate/migration-from-v6-to-v7.md @@ -41,6 +41,11 @@ The step-by-step instructions can be consulted to start the migration to version - The `database.dbNamePrefix` field of the [database configuration]({% link _docs_operate/configuration.md %}#database) was removed. Before, it defaulted to `acc-`. If a database called `acc-connector` is to be accessed, the value of the `database.dbName` field must be set to `acc-connector` instead of `connector` only. - To support additional authentication methods beyond API key authentication, the `apiKey` field was replaced by the `authentication.apiKey.keys..key` parameter of the [authentication configuration]({% link _docs_operate/configuration.md %}#authentication). The `authentication.apiKey.keys..scopes` field provides a convenient way to configure the permissions that apply when the API key identified by `` is used. - Additionally, the support for the `API_KEY` [environment variable]({% link _docs_operate/configuration.md %}#environment-variables) has been removed, that could be used to define an API key using a short environment variable. As an alternative, the `authentication.apiKey.keys..key` configuration property can be set using an environment variable. +- It must be ensured that a [Backbone](https://github.com/nmshd/backbone/tags) is used which is compatible with version 7 of the Connector. + Even though a Backbone of version 6 can still be used, it is recommended to update to version 7 of the Backbone due to the new features and bug fixes provided. + Appropriate Backbone credentials can be specified in the fields `transportLibrary.baseUrl`, `transportLibrary.platformClientId` and `transportLibrary.platformClientSecret` of the [Backbone configuration]({% link _docs_operate/configuration.md %}#transportlibrary). + The URL `/api/v2/version` can be accessed to validate the version of the Backbone. + Please note that version 7 of the Backbone only supports version 2 of its API and no longer version 1. ### Removed and Changed Data Structures @@ -60,6 +65,8 @@ The step-by-step instructions can be consulted to start the migration to version The property `reference` was introduced to group the property `truncated` with the additional property `url`, improving structure and better organizing related data. - The `title` property of the [File]({% link _docs_integrate/data-model-overview.md %}#file) became optional and should no longer be relied upon to be set. - The `ownershipToken` property of the [TransferFileOwnershipRequestItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershiprequestitem) became mandatory. This ensures that the ownership of the original File on the Backbone is transferred instead of applying a copy-based workaround. If the ownership of a [File]({% link _docs_integrate/data-model-overview.md %}#file) ought to be transferred, that doesn't have an `ownershipToken` yet, it will need to be [regenerated]({% link _docs_use-cases/use-case-transport-regenerate-file-ownership-token.md %}). +- The properties `approvedAt` and `approvedByDevice` of the [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) have been removed. + Furthermore, renaming `"Approved"` to `"Active"` resulted in a change of an IdentityDeletionProcess `status`. - All data structures around the Attribute listener feature, including the LocalAttributeListener, the RegisterAttributeListenerRequestItem, and the RegisterAttributeListenerAcceptResponseItem, were removed. ### Changed Behavior of Known Features diff --git a/_docs_operate/backbone-security-considerations.md b/_docs_operate/backbone-security-considerations.md index 5862877b0..650a179b5 100644 --- a/_docs_operate/backbone-security-considerations.md +++ b/_docs_operate/backbone-security-considerations.md @@ -91,8 +91,8 @@ There is no authorization set up. So if you have the API-Key, you can access all The Consumer API supports configuring quotas on different write-actions to limit how often a user can execute those. These quotas can be defined per identity. However, there are some endpoints that allow anonymous access and that therefore cannot be rate limited by quotas. These endpoints currently are: -- `POST /api/v1/Challenges` -- `POST /api/v1/Identities` +- `POST /api/v2/Challenges` +- `POST /api/v2/Identities` When operating the Backbone's Consumer API, you should make sure that the endpoints mentioned above are not abused by malicious users by implementing rate limiting on the network level. diff --git a/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md index 2df21a849..50cb4717c 100644 --- a/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md @@ -14,7 +14,7 @@ properties: - layer: Transport - facade: IdentityDeletionProcessFacade - function: cancelIdentityDeletionProcess - - description: Cancel an IdentityDeletionProcess that has status 'Approved' within grace period + - description: Cancel an IdentityDeletionProcess that has status 'Active' within grace period - feature category: Identity handling - tech category: IdentityDeletionProcesses - status: DONE @@ -41,19 +41,19 @@ required_by: {% include properties_list.html %} -The process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Approved"` as `status`. +The process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) leads to the creation of an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) with `"Active"` as `status`. It can be cancelled if the Identity no longer wants to be deleted. This is only possible as long as the end of the associated grace period of the IdentityDeletionProcess specified within its `gracePeriodEndsAt` property has not yet been reached. -This use case allows you to cancel an approved IdentityDeletionProcess for your Identity within the grace period. +This use case allows you to cancel an active IdentityDeletionProcess for your Identity within the grace period. This use case can be utilized by using the [Identity deletion cancellation command]({% link _docs_operate/connector-cli-operations.md %}#identity-deletion-cancellation-command) of the [Connector CLI operations]({% link _docs_operate/connector-cli-operations.md %}), but not by using the [Connector REST API]({% link _docs_integrate/access-the-connector.md %}#hosted-api-tooling-by-the-development-connector). {: .notice--info} ## On Success -- Changes the `status` of the IdentityDeletionProcess from `"Approved"` to `"Cancelled"`. +- Changes the `status` of the IdentityDeletionProcess from `"Active"` to `"Cancelled"`. - Returns the cancelled IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be cancelled if none has `"Approved"` as `status` for this Identity. +- No IdentityDeletionProcess can be cancelled if none has `"Active"` as `status` for this Identity. diff --git a/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md index 2dc780265..1d9a183bd 100644 --- a/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-get-active-identitydeletionprocess.md @@ -14,7 +14,7 @@ properties: - layer: Transport - facade: IdentityDeletionProcessFacade - function: getActiveIdentityDeletionProcess - - description: Get IdentityDeletionProcess that is in status 'Approved' + - description: Get IdentityDeletionProcess that is in status 'Active' - feature category: Identity handling - tech category: IdentityDeletionProcesses - status: DONE @@ -42,7 +42,7 @@ required_by: {% include properties_list.html %} From a technical perspective, the process of [Identity deletion]({% link _docs_integrate/delete-identities.md %}) is described by a data object of type [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess). -An IdentityDeletionProcess is active if it has `"Approved"` as `status`. +An IdentityDeletionProcess is active if it has `"Active"` as `status`. This use case returns the active IdentityDeletionProcess for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) if one exists. At all times, there can only be at most one active IdentityDeletionProcess per Identity. diff --git a/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md b/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md index cf252b559..d21908e52 100644 --- a/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md +++ b/_docs_use-cases/use-case-transport-initiate-identitydeletionprocess.md @@ -14,7 +14,7 @@ properties: - layer: Transport - facade: IdentityDeletionProcessFacade - function: initiateIdentityDeletionProcess - - description: Initiate an IdentityDeletionProcess that has status 'Approved' + - description: Initiate an IdentityDeletionProcess that has status 'Active' - feature category: Identity handling - tech category: IdentityDeletionProcesses - status: DONE @@ -42,16 +42,16 @@ required_by: {% include properties_list.html %} Regarding [self-initiated Identity deletion]({% link _docs_integrate/delete-identities.md %}#self-initiated-identity-deletion), this use case can be utilized to initiate an [IdentityDeletionProcess]({% link _docs_integrate/data-model-overview.md %}#identitydeletionprocess) for your [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). -The generated IdentityDeletionProcess immediately has `"Approved"` as its `status` and describes that the Identity will be deleted after the grace period ends unless the [IdentityDeletionProcess is cancelled]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) by the Identity by then. +The generated IdentityDeletionProcess immediately has `"Active"` as its `status` and describes that the Identity will be deleted after the grace period ends unless the [IdentityDeletionProcess is cancelled]({% link _docs_use-cases/use-case-transport-cancel-identitydeletionprocess.md %}) by the Identity by then. This use case can be utilized by using the [Identity deletion initialization command]({% link _docs_operate/connector-cli-operations.md %}#identity-deletion-initialization-command) of the [Connector CLI operations]({% link _docs_operate/connector-cli-operations.md %}), but not by using the [Connector REST API]({% link _docs_integrate/access-the-connector.md %}#hosted-api-tooling-by-the-development-connector). {: .notice--info} ## On Success -- Creates an IdentityDeletionProcess with `"Approved"` as `status`. +- Creates an IdentityDeletionProcess with `"Active"` as `status`. - Returns the initiated IdentityDeletionProcess. ## On Failure -- No IdentityDeletionProcess can be initiated if there is already an active IdentityDeletionProcess, i.e. an IdentityDeletionProcess with `"Approved"` as `status`, for this Identity. +- No IdentityDeletionProcess can be initiated if there is already an active IdentityDeletionProcess, i.e. an IdentityDeletionProcess with `"Active"` as `status`, for this Identity.