Merge pull request magento#733 from Magento/pubs31_2341

Harper, Kevin(keharper) · Harper, Kevin(keharper) · commit 684fa24b3320 · 2015-06-16T14:46:27.000-05:00
Pubs31 2341 Added section about extension attributes
diff --git a/guides/v1.0/get-started/authentication/gs-authentication.md b/guides/v1.0/get-started/authentication/gs-authentication.md
@@ -118,6 +118,63 @@ Authorization is granted to either an administrator (or an integration) defined
    <p>Similarly, self is a special access used if you already have an authenticated session with the system. Self access enables a user to access resources they own. For example, <code>GET /V1/customers/me</code> fetches the logged-in customer's details. This is typically useful for JavaScript-based widgets. </p>
 </div>
 
+<h3 id="extension_attrs">Extension attribute authentication</h3>
+
+Individual fields that are defined as extension attributes can be restricted, based on existing permissions. This feature allows extension developers to restrict access to data. 
+
+
+The following [code sample](https://github.corp.ebay.com/magento2/magento2ce/blob/develop/app/code/Magento/CatalogInventory/etc/extension_attributes.xml) defines `stock_item` as an extension attribute of the `CatalogInventory` module. `CatalogInventory` is treated as a “3rd-party extension”. Access to the inventory data is restricted because the quantity of in-stock item may be competitive information.
+
+{% highlight XML %}
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/Api/etc/extension_attributes.xsd">
+    <extension_attributes for="Magento\Catalog\Api\Data\ProductInterface">
+        <attribute code="stock_item" type="Magento\CatalogInventory\Api\Data\StockItemInterface">
+            <resources>
+                <resource ref="Magento_CatalogInventory::cataloginventory"/>
+            </resources>
+        </attribute>
+    </extension_attributes>
+</config>
+{% endhighlight %}
+
+In this example, the `stock_item` attribute is restricted to only the users who have the `Magento_CatalogInventory::cataloginventory` permission. As a result, an anonymous or unauthenticated user issuing a `GET http://store/rest/V1/products/<sku>` request will receive product information similar to the following:
+
+<pre>
+{
+    "sku": “tshirt1”,
+    “price”: “20.00”,
+    “description”: “New JSmith design”,
+    “extension_attributes”: {
+        “logo size”: “small”
+    },
+    “custom_attributes”: {
+        “artist”: “James Smith”
+    }
+}
+</pre>
+
+However, an authenticated user with the permission `Magento_CatalogInventory::cataloginventory` receives the additional `stock_item` field:
+
+<pre>
+{
+        "sku": “tshirt1”,
+        “price”: “20.00”,
+        “description”: “New JSmith design”,
+        “extension_attributes”: {
+                “logo size”: “small”,
+                “stock_item” : {
+                        “status” : “in_stock”
+                        “quantity”: 70
+                }
+        },
+        “custom_attributes”: {
+                “artist”: “James Smith”
+        }
+}
+</pre>
+
+This only works for extension attributes (those attributes defined in an `extension_attributes.xml` file). There are no permission restrictions on the rest of the returned data. For example, there is no way to restrict `custom_attributes`.
+
 <h3 id="webapi-clients">Web API clients and authentication methods</h3>
 <p>You use a client, such as a mobile application or an external batch job, to access Magento services using web APIs.</p>
 <p>Each type of client has a preferred authentication method. To authenticate, use the authentication method for your preferred client:</p>
