Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit 09fc630

Browse files
anupdugaranupdugar
committed
Updated Authentication and Authorization details
- Added inline examples for acl and webapi - Updated overview text
1 parent ea67c34 commit 09fc630

File tree

1 file changed

+88
-16
lines changed

1 file changed

+88
-16
lines changed

‎guides/v1.0/get-started/authentication/gs-authentication.md‎

Lines changed: 88 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,20 @@ menu_node: parent
99
github_link: get-started/authentication/gs-authentication.md
1010
---
1111

12-
<h2 id="overview-authenticate">Authentication overview</h2>
13-
14-
Developers define web API resources and their permissions in a <code>webapi.xml</code> configuration file. For details, see <a href="{{ site.gdeurl }}extension-dev-guide/service-contracts/service-to-web-service.html#sample-webapi">Sample webapi.xml file</a>.</p>
15-
16-
<p>Before you can make web API calls, you must authenticate your identity and have requisite permissions (authorization) to access the API resource. Authentication allows Magento to identify the caller's user type. Based on the user's (admin, integration, customer or guest) access rights, resource acessibility is determined.
12+
<h2 id="overview-authenticate">Web API Authentication overview</h2>
13+
<p>
14+
Magento allows developers to define web API resources and their permissions in a configuration file <code>webapi.xml</code>.
15+
Here are more details on exposing <a href="http://devdocs.magento.com/guides/v1.0/extension-dev-guide/service-contracts/service-to-web-service.html">services as Web APIs.</a>
1716

17+
Before you can make web API calls, you must authenticate your identity and have requisite permissions (authorization) to access the API resource. Authentication allows Magento to identify the caller's user type. Based on the user's (admin, integration, customer or guest) access rights, API calls' resource acessibility is determined.
18+
</p>
1819

1920
<h3 id="accessible-resources">Accessible resources</h3>
2021
<p>The resources that you can access depend on your user type and the configured permission of the resource in the <code>webapi.xml</code> file. This table lists the resources that each user type can access:</p>
2122
<table style="width:100%">
2223
<tr bgcolor="lightgray">
2324
<th>User type</th>
24-
<th>Accessible resources</th>
25+
<th>Accessible resources (defined in webapi.xml)</th>
2526
</tr>
2627
<tr>
2728
<td>
@@ -37,7 +38,6 @@ Developers define web API resources and their permissions in a <code>webapi.xml<
3738
</td>
3839
<td>
3940
<p>Resources for which admins or integrations are authorized. For example, if admins are authorized for the <code>Magento_Customer::group</code> resource, they can make a <code>GET&nbsp;/V1/customerGroups/:id</code> call.</p>
40-
<p>The <code>acl.xml</code> file for the module defines the access control list (ACL) for resources. See <a href="#acl-xml-file">Sample acl.xml file</a>.</p>
4141
</td>
4242
</tr>
4343
<tr>
@@ -49,18 +49,90 @@ Developers define web API resources and their permissions in a <code>webapi.xml<
4949
</td>
5050
</tr>
5151
</table>
52-
<div class="bs-callout bs-callout-info" id="info">
53-
<p>A guest user is one that the Magento web API framework cannot authenticate through existing authentication mechanisms.</p>
54-
</div>
55-
<h3 id="acl-xml-file">Sample acl.xml file</h3>
56-
<p>The following <code>acl.xml</code> file defines the access control list (ACL) for the Customer module. It defines available set of permissions to access the customer resources. Ex: account, customer configuration, and customer group resources:</p>
57-
<script src="https://gist.github.com/difleming/6bfb9252b303ee503f55.js"></script>.
58-
acl.xml files across all Magento modules are consolidated to build the ACL tree which is used to select allowed Admin role resources or third party Integration's access (System > Extension > Integration > Add New Integration > Available APIs).
5952

60-
When a developer creates the Web API configuration file : webapi.xml, the permissions defined in acl.xml are referenced to create access rights for each API.
53+
<h3 id="acl-webapi-relation">Relation between acl.xml and webapi.xml</h3>
54+
<p>The acl.xml file defines the access control list (ACL) for a given module. It defines available set of permissions to access the resources. acl.xml files across all Magento modules are consolidated to build an ACL tree which is used to select allowed Admin role resources or third party Integration's access (System > Extension > Integration > Add New Integration > Available APIs).
55+
</p>
56+
<h4 id="acl-webapi-relation">Sample customer acl.xml</h4>
57+
Ex: Account management, customer configuration, and customer group resource permissions are defined in the below customer acl.xml
58+
```xml
59+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../../lib/internal/Magento/Framework/Acl/etc/acl.xsd">
60+
<acl>
61+
<resources>
62+
<resource id="Magento_Adminhtml::admin">
63+
<resource id="Magento_Customer::customer" title="Customers" sortOrder="40">
64+
<resource id="Magento_Customer::manage" title="All Customers" sortOrder="10" />
65+
</resource>
66+
<resource id="Magento_Adminhtml::stores">
67+
<resource id="Magento_Adminhtml::stores_settings">
68+
<resource id="Magento_Adminhtml::config">
69+
<resource id="Magento_Customer::config_customer" title="Customers Section" sortOrder="50" />
70+
</resource>
71+
</resource>
72+
<resource id="Magento_Adminhtml::stores_other_settings">
73+
<resource id="Magento_Customer::group" title="Customer Groups" sortOrder="10" />
74+
</resource>
75+
</resource>
76+
</resource>
77+
</resources>
78+
</acl>
79+
</config>
80+
```
6181

82+
When a developer creates the Web API configuration file : webapi.xml, the permissions defined in acl.xml are referenced to create access rights for each API.
83+
<h4 id="acl-webapi-relation">Sample (truncated) customer webapi.xml</h4>
84+
```xml
85+
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
86+
xsi:noNamespaceSchemaLocation="../../../../../app/code/Magento/Webapi/etc/webapi.xsd">
87+
<!-- Customer Group -->
88+
<route url="/V1/customerGroups/:id" method="GET">
89+
<service class="Magento\Customer\Api\GroupRepositoryInterface" method="getById"/>
90+
<resources>
91+
<resource ref="Magento_Customer::group"/>
92+
</resources>
93+
</route>
94+
............
95+
.......
96+
.....
97+
<!-- Customer Account -->
98+
<route url="/V1/customers/:customerId" method="GET">
99+
<service class="Magento\Customer\Api\CustomerRepositoryInterface" method="getById"/>
100+
<resources>
101+
<resource ref="Magento_Customer::customer"/>
102+
</resources>
103+
</route>
104+
<route url="/V1/customers" method="POST">
105+
<service class="Magento\Customer\Api\AccountManagementInterface" method="createAccount"/>
106+
<resources>
107+
<resource ref="anonymous"/>
108+
</resources>
109+
</route>
110+
<route url="/V1/customers/:id" method="PUT">
111+
<service class="Magento\Customer\Api\CustomerRepositoryInterface" method="save"/>
112+
<resources>
113+
<resource ref="Magento_Customer::manage"/>
114+
</resources>
115+
</route>
116+
<route url="/V1/customers/me" method="PUT">
117+
<service class="Magento\Customer\Api\CustomerRepositoryInterface" method="save"/>
118+
<resources>
119+
<resource ref="self"/>
120+
</resources>
121+
<data>
122+
<parameter name="customer.id" force="true">%customer_id%</parameter>
123+
</data>
124+
</route>
125+
..........
126+
.....
127+
...
128+
```
62129
ex:
63-
In the above webapi.xml, for the "<route url="/V1/customerGroups/:id" method="GET">" API, only a user with a "Magento_Customer::group" can access the API. The user can be an admin (or an Integration) defined in the backend with the customer group selected as one of the resource in the ACL tree.
130+
In the above sample webapi.xml, for the customerGroups resource, only a user with a "Magento_Customer::group" can access the GET /V1/customerGroups/:id API. On the other hand, POST /V1/customers (customer creation) can be accessed anonymously (or by a guest) without a need for presenting the identity.
131+
132+
The user here can be an admin (or an Integration) defined in the backend with the customer group selected as one of the resource in the ACL tree.
133+
<div class="bs-callout bs-callout-info" id="info">
134+
<p>A guest or anonymous is a special permission that doesn't need to be defined in acl.xml (and will not show up in the acl tree in the backend). It just indicates that the current resource in webapi.xml can be accessed without the need for authentication. Similarly self is a special access if you already have an authenticated session with the system and allows the user to access resources they own. ex GET /V1/customers/me will fetch the logged in customer's details. This is typically useful for javascript based widgets. </p>
135+
</div>
64136

65137
<h3 id="webapi-clients">Web API clients and authentication methods</h3>
66138
<p>You use a client, such as a mobile application or an external batch job, to access Magento services through web APIs.</p>

0 commit comments

Comments
 (0)