Merge pull request #184376 from dlepow/apimopen

[APIM] Conceptual updates for subscriptions and products

Author: AnnaMHuff

articles/api-management/api-management-howto-add-products.md

@@ -5,20 +5,21 @@ description: In this tutorial, you create and publish a product in Azure API Man
 author: dlepow
 ms.service: api-management
 ms.topic: tutorial
-ms.date: 12/15/2021
+ms.date: 01/18/2022
 ms.author: danlep
 ms.custom: devdivchpfy22
 
 ---
 # Tutorial: Create and publish a product
 
-In Azure API Management, a [*product*](api-management-terminology.md#term-definitions) contains one or more APIs, a usage quota, and the terms of use. After a product is published, developers can subscribe to the product and begin to use the product's APIs.  
+In Azure API Management, a [*product*](api-management-terminology.md#term-definitions) contains one or more APIs, a usage quota, and the terms of use. After a product is published, developers can [subscribe](api-management-subscriptions.md) to the product and begin to use the product's APIs.  
 
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
 > * Create and publish a product
 > * Add an API to the product
+> * Access product APIs
 
 :::image type="content" source="media/api-management-howto-add-products/added-product-1.png" alt-text="API Management products in portal":::
 
@@ -46,12 +47,12 @@ In this tutorial, you learn how to:
     |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
     | Display name             | The name as you want it to be shown in the [developer portal](api-management-howto-developer-portal.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
     | Description              | Provide information about the product such as its purpose, the APIs it provides access to, and other details.                                                                                                                                               |
-    | Published                    | Select **Published** if you want to publish the product. Before the APIs in a product can be called, the product must be published. By default, new products are unpublished, and are visible only to the  **Administrators** group.                                                                                      |
-    | Requires subscription    | Select if a user is required to subscribe to use the product.                                                                                                                                                                                                                                   |
+    | State                    | Select **Published** if you want to publish the product. Before the APIs in a product can be called, the product must be published. By default, new products are unpublished, and are visible only to the  **Administrators** group.                                                                                      |
+    | Requires subscription    | Select if a user is required to subscribe to use the product (the product is *protected*) and a subscription key must be used to access the product's APIs. If a subscription isn't required (the product is *open*), a subscription key isn't required to access the product's APIs. See [Access to product APIs](#access-to-product-apis) later in this article.                                                                                                                                                                                                   |
     | Requires approval        | Select if you want an administrator to review and accept or reject subscription attempts to this product. If not selected, subscription attempts are auto-approved.                                                                                                                         |
-    | Subscription count limit | Optionally, limit the count of multiple simultaneous subscriptions.                                                                                                                                                                                                                                |
-    | Legal terms              | You can include the terms of use for the product, which subscribers must accept to use the product.                                                                                                                                                                                                             |
-    | APIs                     | Select one or more APIs. You can also add APIs after creating the product. For more information, see [Add APIs to a product](#add-apis-to-a-product) later in this article. |
+    | Subscription count limit | Optionally limit the count of multiple simultaneous subscriptions.                                                                                                                                                                                                                                |
+    | Legal terms              | You can include the terms of use for the product which subscribers must accept in order to use the product.                                                                                                                                                                                                             |
+    | APIs                     | Select one or more APIs. You can also add APIs after creating the product. For more information, see [Add APIs to a product](#add-apis-to-a-product) later in this article. <br/><br/>If the product is open (doesn't require a subscription), you can only add an API that isn't associated with another open product.                |
 
 1. Select **Create** to create your new product.
 
@@ -77,7 +78,7 @@ You can specify various values for your product:
    | `--product-name` | The name as you want it to be shown in the [developer portal](api-management-howto-developer-portal.md). |
    | `--description`  | Provide information about the product such as its purpose, the APIs it provides access to, and other details. |
    | `--state`        | Select **published** if you want to publish the product. Before the APIs in a product can be called, the product must be published. By default, new products are unpublished, and are visible only to the  **Administrators** group. |
-   | `--subscription-required` | Select if a user is required to subscribe to use the product. |
+   | `--subscription-required` | Select if a user is required to subscribe to use the product (the product is *protected*) or a subscription isn't required (the product is *open*). See [Access to product APIs](#access-to-product-apis) later in this article. |
    | `--approval-required` | Select if you want an administrator to review and accept or reject subscription attempts to this product. If not selected, subscription attempts are auto-approved. |
    | `--subscriptions-limit` | Optionally, limit the count of multiple simultaneous subscriptions.|
    | `--legal-terms`         | You can include the terms of use for the product, which subscribers must accept to use the product. |
@@ -115,8 +116,6 @@ Continue configuring the product after saving it. In your API Management instanc
 
 Products are associations of one or more APIs. You can include many APIs and offer them to developers through the developer portal. During the product creation, you can add one or more existing APIs. You can also add APIs to the product later, either from the Products **Settings** page or while creating an API.
 
-Developers must first subscribe to a product to get access to the API. When they subscribe, they get a subscription key that is good for any API in that product. If you created the API Management instance, you're an administrator already, so you're subscribed to every product by default.
-
 ### Add an API to an existing product
 
 ### [Portal](#tab/azure-portal)
@@ -162,8 +161,26 @@ az apim product api delete --resource-group apim-hello-word-resource-group \
 
 ---
 
-> [!TIP]
-> You can create or update a user's subscription to a product with custom subscription keys through a [REST API](/rest/api/apimanagement/current-ga/subscription/create-or-update) or PowerShell command.
+## Access to product APIs
+
+After you publish a product, developers can access the APIs. Depending on how the product is configured, they may need to subscribe to the product for access.
+
+* **Protected product** - Developers must first subscribe to a protected product to get access to the product's APIs. When they subscribe, they get a subscription key that can access any API in that product. If you created the API Management instance, you are an administrator already, so you are subscribed to every product by default. For more information, see [Subscriptions in Azure API Management](api-management-subscriptions.md).
+
+    When a client makes an API request with a valid product subscription key, API Management processes the request and permits access in the context of the product. Policies and access control rules configured for the product can be applied.
+
+    > [!TIP]
+    > You can create or update a user's subscription to a product with custom subscription keys through a [REST API](/rest/api/apimanagement/current-ga/subscription/create-or-update) or PowerShell command.
+
+* **Open product** - Developers can access an open product's APIs without a subscription key. However, you can configure other mechanisms to secure client access to the APIs, including [OAuth 2.0](api-management-howto-protect-backend-with-aad.md), [client certificates](api-management-howto-mutual-certificates-for-clients.md), and [restricting caller IP addresses](./api-management-access-restriction-policies.md#RestrictCallerIPs).
+
+    When a client makes an API request without a subscription key:
+    
+    * API Management checks whether the API is associated with an open product. 
+
+    * If the open product exists, it then processes the request in the context of that open product. Policies and access control rules configured for the open product can be applied. 
+
+For more information, see [How API Management handles requests with or without subscription keys](api-management-subscriptions.md#how-api-management-handles-requests-with-or-without-subscription-keys).
 
 ## Next steps
 
@@ -172,6 +189,7 @@ In this tutorial, you learned how to:
 > [!div class="checklist"]
 > * Create and publish a product
 > * Add an API to the product
+> * Access product APIs
 
 Advance to the next tutorial:
 

articles/api-management/api-management-subscriptions.md

@@ -1,17 +1,13 @@
 ---
 title: Subscriptions in Azure API Management | Microsoft Docs
-description: Learn about the concept of subscriptions in Azure API Management. Consumers get access to APIs by using subscriptions in Azure API Management.
+description: Learn about the concept of subscriptions in Azure API Management. Consumers commonly get access to APIs by using subscriptions in Azure API Management.
 services: api-management
 documentationcenter: ''
 author: dlepow
-manager: cfowler
-editor: ''
 
 ms.service: api-management
-ms.workload: mobile
-ms.tgt_pltfrm: na
-ms.topic: article
-ms.date: 11/22/2021
+ms.topic: conceptual
+ms.date: 01/05/2022
 ms.author: danlep
 ---
 # Subscriptions in Azure API Management
@@ -20,13 +16,14 @@ In Azure API Management, *subscriptions* are the most common way for API consume
 
 ## What are subscriptions?
 
-By publishing APIs through API Management, you can easily secure API access using subscription keys. Consume the published APIs by including a valid subscription key in the HTTP requests when calling to those APIs. Without a valid subscription key, the calls will:
-* Be rejected immediately by the API Management gateway. 
-* Not be forwarded to the back-end services.
+By publishing APIs through API Management, you can easily secure API access using subscription keys. Developers who need to consume the published APIs must include a valid subscription key in HTTP requests when calling those APIs. Without a valid subscription key, the calls are:
+* Rejected immediately by the API Management gateway. 
+* Not forwarded to the back-end services.
 
 To access APIs, you'll need a subscription and a subscription key. A *subscription* is a named container for a pair of subscription keys. 
 
-Regularly regenerating keys is a common security precaution, so most Azure products requiring a subscription key will generate keys in pairs. Each application using the service can switch from *key A* to *key B* and regenerate key A with minimal disruption, and vice versa. 
+> [!NOTE]
+> Regularly regenerating keys is a common security precaution. Like most Azure services requiring a subscription key, API Management  generates keys in pairs. Each application using the service can switch from *key A* to *key B* and regenerate key A with minimal disruption, and vice versa. 
 
 In addition,
 
@@ -41,57 +38,69 @@ In addition,
 
 ## Scope of subscriptions
 
-Subscriptions can be associated with various scopes: product, all APIs, or an individual API.
+Subscriptions can be associated with various scopes: [product](api-management-howto-add-products.md), all APIs, or an individual API.
 
 ### Subscriptions for a product
 
-Traditionally, subscriptions in API Management were associated with a single [API product](api-management-terminology.md) scope. Developers:
+Traditionally, subscriptions in API Management were associated with a single [product](api-management-terminology.md) scope. Developers:
 * Found the list of products on the developer portal. 
 * Submitted subscription requests for the products they wanted to use. 
 * Use the keys in those subscriptions (approved either automatically or by API publishers) to access all APIs in the product. 
-    * You can access APIs with or without the subscription key regardless of subscription scope (product, global, or API).
 
 Currently, the developer portal only shows the product scope subscriptions under the **User Profile** section. 
 
 ![Product subscriptions](./media/api-management-subscriptions/product-subscription.png)
 
-> [!TIP]
-> Under certain scenarios, API publishers might want to publish an API product to the public without the requirement of subscriptions. They can deselect the **Require subscription** option on the **Settings** page of the product in the Azure portal. As a result, all APIs under the product can be accessed without an API key.
-
 ### Subscriptions for all APIs or an individual API
 
-With the addition of the [Consumption](https://aka.ms/apimconsumptionblog) tier of API Management, subscription key management is more streamlined. 
-
-#### Two more subscription scopes
-
-Subscription scopes aren't limited to an API product. You can create keys that grant access to either:
-* a single API, or 
+You can also create keys that grant access to either:
+* A single API, or 
 * All APIs within an API Management instance. 
 
-You don't need to create a product before adding APIs to it. 
+In these cases, you don't need to create a product and add APIs to it first. 
+
+### All-access subscription
 
 Each API Management instance comes with an immutable, all-APIs subscription (also called an *all-access* subscription). This built-in subscription makes it straightforward to test and debug APIs within the test console.
 
 > [!NOTE]
-> If you're using an API-scoped subscription or the all-access subscription, any [policies](api-management-howto-policies.md) configured at the product scope aren't applied to that subscription.
+> If you're using an API-scoped subscription or the all-access subscription, any [policies](api-management-howto-policies.md) configured at the product scope aren't applied to requests from that subscription.
 
-#### Standalone subscriptions
+### Standalone subscriptions
 
-API Management now allows *standalone* subscriptions. You no longer need to associate subscriptions with a developer account. This feature proves useful in scenarios similar to several developers or teams sharing a subscription.
+API Management also allows *standalone* subscriptions, which are not associated with a developer account. This feature proves useful in scenarios similar to several developers or teams sharing a subscription.
 
 Creating a subscription without assigning an owner makes it a standalone subscription. To grant developers and the rest of your team access to the standalone subscription key, either:
 * Manually share the subscription key.
 * Use a custom system to make the subscription key available to your team.
 
-#### Creating subscriptions in Azure portal
+## Create subscriptions in Azure portal
 
 API publishers can [create subscriptions](api-management-howto-create-subscriptions.md) directly in the Azure portal:
 
 ![Flexible subscriptions](./media/api-management-subscriptions/flexible-subscription.png)
 
+## How API Management handles requests with or without subscription keys
+
+By default, a developer can only access a product or API by using a subscription key. Under certain scenarios, API publishers might want to publish a product or a particular API to the public without the requirement of subscriptions. While a publisher could choose to enable unsecured access to certain APIs, configuring another mechanism to secure client access is recommended.
+
+To disable the subscription requirement using the portal:
+
+* **Product** - Disable **Requires subscription** on the **Settings** page of the product.  
+* **API** - Disable **Subscription required** on the **Settings** page of the API. 
+
+After disabling the subscription requirement, the selected API or APIs can be accessed without a subscription key.
+
+When API Management receives an API request from a client without a subscription key, it handles the request according to these rules: 
+
+1. Check first for the existence of a product that includes the API but doesn't require a subscription (an *open* product). If the open product exists, handle the request in the context of the APIs, policies, and access rules configured for the product. 
+1. If an open product including the API isn't found, check whether the API requires a subscription. If a subscription isn't required, handle the request in the context of that API and operation.
+1. If no configured product or API is found, then access is denied.
+
 ## Next steps
 Get more information on API Management:
 
++ Learn how API Management [policies](set-edit-policies.md#configure-scope) get applied at different scopes.
 + Learn other [concepts](api-management-terminology.md) in API Management.
 + Follow our [tutorials](import-and-publish.md) to learn more about API Management.
 + Check our [FAQ page](api-management-faq.yml) for common questions.