Merge branch 'master' into CPM-331

Author: meganelepalud-akeneo

.circleci/config.yml

@@ -2,14 +2,14 @@ version: 2
 jobs:
     build:
         machine:
-            image: ubuntu-1604:201903-01
+            image: ubuntu-2004:202111-02
         steps:
             - checkout
             - run: make build
 
     deploy_staging:
         machine:
-            image: ubuntu-1604:201903-01
+            image: ubuntu-2004:202111-02
         steps:
             - checkout
             - add_ssh_keys
@@ -19,7 +19,7 @@ jobs:
 
     deploy_production:
         machine:
-            image: ubuntu-1604:201903-01
+            image: ubuntu-2004:202111-02
         steps:
             - checkout
             - add_ssh_keys
@@ -42,4 +42,9 @@ workflows:
             - deploy_production:
                   filters:
                       branches:
-                          only: master
+                          only: master
+            - deploy_staging?:
+                  type: approval
+            - deploy_staging:
+                  requires:
+                      - deploy_staging?

.github/CODEOWNERS

@@ -0,0 +1 @@
+content/apps/ @akeneo/squad-octopus

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:10-alpine
+FROM node:16-alpine
 RUN apk add yarn
 RUN apk add openssh-client
-RUN apk add rsync
+RUN apk add rsync

Makefile

@@ -20,4 +20,4 @@ build: yarn-install
 	$(DOCKER_RUN) $(DOCKER_IMAGE_TAG) yarn gulp create-dist
 
 deploy: build
-	$(DOCKER_RUN) -v /etc/passwd:/etc/passwd:ro -v $${SSH_AUTH_SOCK}:/ssh-auth.sock:ro -e SSH_AUTH_SOCK=/ssh-auth.sock $(DOCKER_IMAGE_TAG) rsync --no-v -e "ssh -q -p $${PORT} -o StrictHostKeyChecking=no" -az --delete dist/ akeneo@$${HOSTNAME}:/var/www/html
+	$(DOCKER_RUN) -v /etc/passwd:/etc/passwd:ro -v $${SSH_AUTH_SOCK}:/ssh-auth.sock:ro -e SSH_AUTH_SOCK=/ssh-auth.sock $(DOCKER_IMAGE_TAG) rsync --no-v -e "ssh -q -p $${PORT} -o StrictHostKeyChecking=no -o PubkeyAcceptedKeyTypes=+ssh-rsa" -az --delete dist/ akeneo@$${HOSTNAME}:/var/www/html

README.md

@@ -46,3 +46,19 @@ Then click on _Rerun_.
 
 As our YAML Swagger spec uses references and links, it is considered as non-valid.
 During the build, we generate a valid JSON specification that is put under the `content/swagger` folder. Don't forget to version it if you made any change into the YAML Swagger spec.
+
+### Custom properties
+
+Our Swagger spec is extended with [custom properties](https://swagger.io/docs/specification/2-0/swagger-extensions/):
+
+| Property                 | Type                                | Description                                                                                                                                                                          |
+|--------------------------|-------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `x-from-version`         | `string`                            | Indicates the version the property was added to the API. In the user documentation, hides the property from payload descriptions that doesn't match the selected API version.        |
+| `x-examples-per-version` | [[Example object](#example-object)] | Allows to set a payload example for a specific version. Use as a [Response object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responsesObject) property. |
+
+#### Example object
+
+| Property    | Type     | Description                |
+|-------------|----------|----------------------------|
+| `x-version` | `string` | API version of the example |
+| `x-example` | `any`    | Example payload content    |

content/apps/access-scopes.md

@@ -0,0 +1,55 @@
+# Access scopes
+
+::: warning
+This feature is available on all SaaS environments and only since v6 for other types of environments.
+:::
+
+
+Part of the app authorization process requires specifying which parts of Akeneo PIM data the App needs to access.
+An App can request any of the access scopes listed below.
+
+::: warning
+**Akeneo PIM may not grant all requested scopes.**  
+This is up to your App to check which scopes were granted when you receive an Access Token.  
+For example, the Community edition will not be able to grant you scopes related to the Asset Manager because
+it's a feature only available in the Enterprise edition.
+:::
+
+## Available authorization scopes
+
+| Scope                                                                   | Grants access to                                                 |
+|-------------------------------------------------------------------------|------------------------------------------------------------------|
+| `read_products`                                                         | Read products                                                    |
+| `write_products`                                                        | Write products                                                   |
+| `delete_products`                                                       | Remove products                                                  |
+| `read_catalog_structure`                                                | Read attributes, attribute groups, families and family variants  |
+| `write_catalog_structure`                                               | Write attributes, attribute groups, families and family variants |
+| `read_attribute_options`                                                | Read attribute options                                           |
+| `write_attribute_options`                                               | Write attribute options                                          |
+| `read_categories`                                                       | Read categories                                                  |
+| `write_categories`                                                      | Write categories                                                 |
+| `read_channel_localization`                                             | Read locales and currencies                                      |
+| `read_channel_settings`                                                 | Read channels                                                    |
+| `write_channel_settings`                                                | Write channels                                                   |
+| `read_association_types`                                                | Read association types                                           |
+| `write_association_types`                                               | Write association types                                          |
+| `read_asset_families` <span class="label label-ee">EE</span>            | Read asset families                                              |
+| `write_asset_families` <span class="label label-ee">EE</span>           | Write assets families                                            |
+| `read_assets` <span class="label label-ee">EE</span>                    | Read assets                                                      |
+| `write_assets` <span class="label label-ee">EE</span>                   | Write assets                                                     |
+| `delete_assets` <span class="label label-ee">EE</span>                  | Remove assets                                                    |
+| `read_reference_entities` <span class="label label-ee">EE</span>        | Read reference entities                                          |
+| `write_reference_entities` <span class="label label-ee">EE</span>       | Write reference entities                                         |
+| `read_reference_entity_records` <span class="label label-ee">EE</span>  | Read reference entity records                                    |
+| `write_reference_entity_records` <span class="label label-ee">EE</span> | Write reference entity records                                   |
+
+## Available authentication scopes
+
+| Scope     | Grants access to                                           |
+|-----------|------------------------------------------------------------|
+| `openid`  | Read user id                                               |
+| `profile` | Read user first name and last name (from PIM user profile) |
+| `email`   | Read user email (from PIM user profile)                    |
+
+::: panel-link Next step [How to test my App ?](/apps/how-to-test-my-app.html)
+:::

content/apps/create-app.md

@@ -0,0 +1,65 @@
+# Create an App (with code samples)
+
+::: warning
+This feature is available on all SaaS environments and only since v6 for other types of environments.
+:::
+
+In this tutorial, we provide a guide on how to implement the required parts of your App
+for the activation process based on OAuth 2.0 with Authorization Code.
+At the end of this tutorial, your App will receive an Access Token and will be able to call the REST API of a PIM.
+
+::: warning
+Examples in this tutorial use languages without any framework or library and, consequently, don't follow
+all the recommended best practices. We **strongly** encourage you to adapt those examples with the framework or
+library of your choice.
+:::
+
+## Prerequisites
+
+You must have valid [OAuth 2.0 client credentials](/apps/using-oauth2.html#credentials).
+
+## Activation URL
+
+First, your application must expose an activation URL.
+
+In our example, we won't do additional steps (like authentification), so we will launch the Authorization Request
+immediately in this Activation URL.
+
+
+!!!include(content/apps/create-app/activate-php.md)!!!
+!!!include(content/apps/create-app/activate-nodejs.md)!!!
+!!!include(content/apps/create-app/activate-python.md)!!!
+!!!include(content/apps/create-app/activate-java.md)!!!
+
+## Callback URL
+
+Then, your application must expose a callback URL.
+
+
+!!!include(content/apps/create-app/callback-php.md)!!!
+!!!include(content/apps/create-app/callback-nodejs.md)!!!
+!!!include(content/apps/create-app/callback-python.md)!!!
+!!!include(content/apps/create-app/callback-java.md)!!!
+
+
+
+::: info
+The Code Challenge is documented [here](/apps/using-oauth2.html#whats-the-code-challenge).
+:::
+
+And that's it!  
+At the end of this process, you receive the following response with an `access_token`:
+
+```json
+{
+  "access_token": "Y2YyYjM1ZjMyMmZlZmE5Yzg0OTNiYjRjZTJjNjk0ZTUxYTE0NWI5Zm",
+  "token_type": "bearer",
+  "scope": "read_products write_products"
+}
+```
+
+You can use this token to call the Akeneo PIM REST API.
+
+::: tips
+Reminder: our documentation is [open-source](https://github.com/akeneo/pim-api-docs). Feel free to contribute with languages we're not experts at.
+:::

content/apps/create-app/activate-java.md

@@ -0,0 +1,42 @@
+```java [activate:Java Spring]
+import java.security.SecureRandom;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import javax.servlet.http.HttpSession;
+
+import org.apache.tomcat.util.buf.HexUtils;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+public class App {
+    static final String OAUTH_CLIENT_ID = "CLIENT_ID";
+    static final String OAUTH_SCOPES = "read_products write_products";
+    
+    @GetMapping("/activate")
+    public void activate(HttpServletRequest request, HttpSession session, HttpServletResponse response) throws Exception {
+        // Create a random state for preventing cross-site request forgery
+        byte[] randomBytes = new byte[10];
+        new SecureRandom().nextBytes(randomBytes);
+        String state = HexUtils.toHexString(randomBytes);
+    
+        Object pimUrl = request.getParameter("pim_url");
+        if (pimUrl == null) {
+            throw new Exception("Missing PIM URL in the query");
+        }
+    
+        // Store in the user session the state and the PIM URL
+        session.setAttribute("oauth2_state", state);
+        session.setAttribute("pim_url", pimUrl.toString());
+    
+        // Build url for the Authorization Request
+        // https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
+        String authorizeUrl = pimUrl + "/connect/apps/v1/authorize" + "?response_type=code" + "&client_id=" + OAUTH_CLIENT_ID
+                + "&scope=" + OAUTH_SCOPES + "&state=" + state;
+    
+        // Redirect the user to the Authorization URL
+        response.sendRedirect(authorizeUrl);
+    }
+}
+```

content/apps/create-app/activate-nodejs.md

@@ -0,0 +1,38 @@
+```js [activate:NodeJS]
+
+params // data from your request handling
+storage // your own memory system
+
+// Retrieve GET query params from your own framework / http handler
+const { pim_url: pimUrl } = params;
+
+// Retrieve your app's Client ID with your own system
+const clientId = storage.get("CLIENT_ID");
+
+// Set the access scopes, take care of the 254 chars max !
+const scopes = 'read_products write_products'; 
+
+// The activate URL should have the pim_url param
+if (!pimUrl) {
+    // Return a Bad request response via your own framework / http server
+    return response(502, { message: "Bad request" });
+}
+
+// Store the PIM url value with your own system
+storage.set("PIM_URL", pimUrl);
+
+// Set a new security state secret and store the value with your own system
+const state = require('crypto').randomBytes(32).toString("hex");
+storage.set("APP_STATE", state);
+
+// Construct the PIM authorization url, it will be called on "connect" / "open" button
+const redirect_url = `${pimUrl}/connect/apps/v1/authorize` +
+    `?response_type=code` +
+    `&client_id=${clientId}` +
+    `&scope=${scopes}` +
+    `&state=${state}`
+
+// Set the redirection response with your own framework / http server
+return redirect(redirect_url);
+
+```

content/apps/create-app/activate-php.md

@@ -0,0 +1,36 @@
+```php [activate:PHP]
+
+// Let's create an `activate.php` file
+
+const OAUTH_CLIENT_ID = '<CLIENT_ID>';
+const OAUTH_SCOPES = 'read_products write_products';
+
+session_start();
+
+$pimUrl = $_GET['pim_url'];
+if (empty($pimUrl)) {
+    exit('Missing PIM URL in the query');
+}
+
+// create a random state for preventing cross-site request forgery
+$state = bin2hex(random_bytes(10));
+
+// Store in the user session the state and the PIM URL
+$_SESSION['oauth2_state'] = $state;
+$_SESSION['pim_url'] = $pimUrl;
+
+// Build the parameters for the Authorization Request
+// https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.1
+$authorizeUrlParams = http_build_query([
+    'response_type' => 'code',
+    'client_id' => OAUTH_CLIENT_ID,
+    'scope' => OAUTH_SCOPES,
+    'state' => $state,
+]);
+
+// Build the url for the Authorization Request using the PIM URL
+$authorizeUrl = $pimUrl . '/connect/apps/v1/authorize?' . $authorizeUrlParams;
+
+// Redirect the user to the Authorization URL
+header('Location: ' . $authorizeUrl);
+```