FRW-2426 API Key authorization documentation

docs/scos/dev/glue-api-guides/202307.0/glue-api-guides.md

@@ -26,3 +26,4 @@ This section contains a collection of guides for working with the Old Spryker Gl
 * [Glue Spryks](/docs/scos/dev/glue-api-guides/{{page.version}}/glue-spryks.html)
 * [Glue infrastructure](/docs/scos/dev/glue-api-guides/{{page.version}}/old-glue-infrastructure/glue-infrastructure.html)
 * [Glue API tutorials](/docs/scos/dev/glue-api-guides/{{page.version}}/glue-api-tutorials/glue-api-tutorials.html)
+* [Use API Key authorization](/docs/scos/dev/glue-api-guides/{{page.version}}/use-api-key-authorization.html)

docs/scos/dev/glue-api-guides/202307.0/use-api-key-authorization.md

@@ -0,0 +1,61 @@
+---
+title: Use API Key authorization
+description: This document describes how to use API Key authorization mechanism in Spryker.
+last_updated: October 10, 2023
+template: glue-api-storefront-guide-template
+redirect_from:
+  - /docs/scos/dev/glue-api-guides/202204.0/use-api-key-authorization.html
+  - /docs/scos/dev/glue-api-guides/202212.0/use-api-key-authorization.html
+---
+
+This document describes how to use API Key authorization mechanism in Spryker.
+
+## How authentication works
+
+The API Key authorization mechanism lets users authenticate themselves with their API Key generated from Backoffice. The generated API Key can then be used to access protected resources.
+
+## Prerequisites
+
+Install the required features:
+
+| NAME | VERSION | INTEGRATION GUIDE                                                                                                                                        |
+| --- | --- |----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Glue Application | {{page.version}} | [Integrate the API Key Authorization](/docs/scos/dev/migration-concepts/migrate-to-decoupled-glue-infrastructure/decoupled-glue-infrastructure-integrate-api-key-authorization.html) |
+
+## Create an API Key in Backoffice
+
+To create an API Key in Backoffice, follow these steps:
+1. Log in to Backoffice.
+2. Navigate to **Administration** > **API Keys**.
+3. Click **Create API Key**.
+4. Enter a name for the API Key.
+5. Enter a Valid To date if needed. Note that if you **do not enter a date**, the API Key will be valid indefinitely.
+6. Click **Create**.
+7. Copy the generated API Key and save it in a secure place. Spryker does not store the API Key, so if you lose it, you will need to generate a new one or regenerate the current Key.
+
+## Use the API Key to access protected resources
+
+There are 2 ways to pass the API Key to access protected resources:
+1. Pass the API Key in the `X-Api-Key` header.
+2. Pass the API Key in the `api_key` URL parameter.
+
+<details open>
+<summary markdown='span'>An example of how to pass the API Key in the `X-Api-Key` header:</summary>
+
+```bash
+curl --location 'http://glue-backend.de.spryker.local/dynamic-entity/countries \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json' \
+--header 'X-Api-Key: 6264714260f980fe38c6be2439b0a8e9'
+```
+</details>
+
+<details open>
+<summary markdown='span'>An example of how to pass the API Key in the `api_key` URL parameter:</summary>
+
+```bash
+curl --location 'http://glue-backend.de.spryker.local/dynamic-entity/countries?api_key=6264714260f980fe38c6be2439b0a8e9 \
+--header 'Content-Type: application/json' \
+--header 'Accept: application/json'
+```
+</details>

docs/scos/dev/migration-concepts/migrate-to-decoupled-glue-infrastructure/decoupled-glue-infrastructure-integrate-api-key-authorization.md

@@ -0,0 +1,170 @@
+---
+title: "Decoupled Glue infrastructure: Integrate the API Key Authorization"
+description: Integration of the API Key authorization mechanism into a Spryker project.
+last_updated: October 10, 2023
+template: feature-integration-guide-template
+redirect_from:
+---
+
+This document describes how to integrate API Key authorization to Backend API applications in a Spryker project.
+
+## Install feature core
+
+Follow the steps below to install the API Key authorization feature core.
+
+### Prerequisites
+
+Install the required features:
+
+| NAME           | VERSION           | INTEGRATION GUIDE |
+| -------------- | ----------------- | ----------------- |
+| Glue Backend API Application | {{page.version}} | [Glue Storefront and Backend API applications integration](/docs/scos/dev/migration-concepts/migrate-to-decoupled-glue-infrastructure/decoupled-glue-infrastructure-integrate-storefront-and-backend-glue-api-applications.html) |
+
+### 1) Install the required modules using Composer
+
+Install the required modules:
+
+```bash
+commposer require spryker/api-key:"^2.0.0" \
+spryker/api-key-gui:"^2.0.0" \
+spryker/authorization:"^1.4.0" \
+spryker/api-key-authorization-connector:"^1.0.0" \
+spryker/spryker/glue-backend-api-application-authorization-connector:"^1.4.0"
+```
+
+{% info_block warningBox "Verification" %}
+
+Make sure that the following modules have been installed:
+
+| MODULE                       | EXPECTED DIRECTORY                             |
+|------------------------------|------------------------------------------------|
+| ApiKey                       | vendor/spryker/api-key                         |
+| ApiKeyGui                    | vendor/spryker/api-key-gui                     |
+| Authorization                | vendor/spryker/authorization                   |
+| ApiKeyAuthorizationCOnnector | vendor/spryker/api-key-authorization-connector |
+| GlueBackendApiApplicationAuthorizationConnector                | vendor/spryker/glue-backend-api-application-authorization-connector                   |
+
+{% endinfo_block %}
+
+### 2) Set up database schema and transfer objects
+
+Apply database changes and generate entity and transfer changes:
+
+```bash
+vendor/bin/console transfer:generate
+vendor/bin/console propel:install
+vendor/bin/console transfer:generate
+```
+
+{% info_block warningBox "Verification" %}
+
+Ensure that the following changes have occurred in the database:
+
+| DATABASE ENTITY | TYPE | EVENT |
+|-----------------| --- | --- |
+| spy\_api\_key   | table | created |
+
+Ensure that the following changes have occurred in transfer objects:
+
+| TRANSFER                       | TYPE | EVENT | PATH |
+|--------------------------------| --- | --- | --- |
+| ApiKey                         | class | created | src/Generated/Shared/Transfer/ApiKeyTransfer |
+| ApiKeyCollectionRequest        | class | created | src/Generated/Shared/Transfer/ApiKeyCollectionRequestTransfer |
+| ApiKeyCollectionReqsponse      | class | created | src/Generated/Shared/Transfer/ApiKeyCollectionReqsponseTransfer |
+| ApiKeyCollectionDeleteCriteria | class | created | src/Generated/Shared/Transfer/ApiKeyCollectionDeleteCriteriaTransfer |
+| ApiKeyCollection               | class | created | src/Generated/Shared/Transfer/ApiKeyCollectionTransfer |
+| ApiKeyCriteria                 | class | created | src/Generated/Shared/Transfer/ApiKeyCriteriaTransfer |
+| ApiKeyConditions                  | class | created | src/Generated/Shared/Transfer/ApiKeyConditionsTransfer |
+| CriteriaRangeFilter                  | class | created | src/Generated/Shared/Transfer/CriteriaRangeFilterTransfer |
+| GlueRequest                 | class | created | src/Generated/Shared/Transfer/GlueRequestTransfer |
+| AuthorizationIdentity  | class | created | src/Generated/Shared/Transfer/AuthorizationIdentityTransfer |
+| AuthorizationEntity  | class | created | src/Generated/Shared/Transfer/AuthorizationEntityTransfer |
+| AuthorizationRequest  | class | created | src/Generated/Shared/Transfer/AuthorizationRequestTransfer |
+| AuthorizationResponse  | class | created | src/Generated/Shared/Transfer/AuthorizationResponseTransfer |
+
+{% endinfo_block %}
+
+### 3) Set up behavior
+
+1. Activate the following plugins:
+
+| PLUGIN | SPECIFICATION                                | NAMESPACE |
+| --- |----------------------------------------------| --- |
+| ApiKeyAuthorizationRequestExpanderPlugin | Expands the request by the API Key provided. | Spryker\Glue\ApiKeyAuthorizationConnector\Plugin\GlueBackendApiApplicationAuthorizationConnector\ApiKeyAuthorizationRequestExpanderPlugin |
+| ApiKeyAuthorizationStrategyPlugin | Executes the API Key verification process.         | Spryker\Zed\ApiKeyAuthorizationConnector\Communication\Plugin\Authorization\ApiKeyAuthorizationStrategyPlugin |
+
+<details open>
+<summary markdown='span'>src/Pyz/Glue/GlueBackendApiApplicationAuthorizationConnector/GlueBackendApiApplicationAuthorizationConnectorDependencyProvider.php</summary>
+
+```php
+<?php
+
+namespace Pyz\Glue\GlueBackendApiApplicationAuthorizationConnector;
+
+use Spryker\Glue\ApiKeyAuthorizationConnector\Plugin\GlueBackendApiApplicationAuthorizationConnector\ApiKeyAuthorizationRequestExpanderPlugin;
+use Spryker\Glue\GlueBackendApiApplicationAuthorizationConnector\GlueBackendApiApplicationAuthorizationConnectorDependencyProvider as SprykerGlueBackendApiApplicationAuthorizationConnectorDependencyProvider;
+
+class GlueBackendApiApplicationAuthorizationConnectorDependencyProvider extends SprykerGlueBackendApiApplicationAuthorizationConnectorDependencyProvider
+{
+    protected function getAuthorizationRequestExpanderPlugins(): array
+    {
+        return [
+            new ApiKeyAuthorizationRequestExpanderPlugin(),
+        ];
+    }
+}
+
+```
+</details>
+
+<details open>
+<summary markdown='span'>src/Pyz/Zed/Authorization/AuthorizationDependencyProvider.php</summary>
+
+```php  
+<?php
+
+namespace Pyz\Zed\Authorization;
+
+use Spryker\Zed\ApiKeyAuthorizationConnector\Communication\Plugin\Authorization\ApiKeyAuthorizationStrategyPlugin;
+use Spryker\Zed\Authorization\AuthorizationDependencyProvider as SprykerAuthorizationDependencyProvider;
+
+class AuthorizationDependencyProvider extends SprykerAuthorizationDependencyProvider
+{
+    protected function getAuthorizationStrategyPlugins(): array
+    {
+        return [
+            new ApiKeyAuthorizationStrategyPlugin(),
+        ];
+    }
+}
+
+```
+</details>
+
+2. Add the following configuration:
+
+<details open>
+<summary markdown='span'>src/Pyz/Zed/Authorization/AuthorizationConfig.php</summary>
+
+```php
+<?php
+
+namespace Pyz\Zed\Authorization;
+
+ use Spryker\Zed\Authorization\AuthorizationConfig as SprykerAuthorizationConfig;
+
+ class AuthorizationConfig extends SprykerAuthorizationConfig
+ {
+     /**
+      * {@inheritDoc}
+      *
+      * @return bool
+      */
+     public function isMultistrategyAuthorizationAllowed(): bool
+     {
+         return true;
+     }
+ }
+```
+</details>
+