Merge pull request #216419 from dlepow/access

[APIM] Content access in dev portal

Author: jborsecnik

articles/api-management/api-management-howto-create-groups.md

@@ -96,8 +96,8 @@ Once the association is added between the developer and the group, you can view
 
 ## <a name="next-steps"> </a>Next steps
 
-* Once a developer is added to a group, they can view and subscribe to the products associated with that group. For more information, see [How create and publish a product in Azure API Management][How create and publish a product in Azure API Management],
-* In addition to creating and managing groups in the Azure portal, you can create and manage your groups using the API Management REST API [Group](/rest/api/apimanagement/apimanagementrest/azure-api-management-rest-api-group-entity) entity.
+* Once a developer is added to a group, they can view and subscribe to the products associated with that group. For more information, see [How create and publish a product in Azure API Management][How create and publish a product in Azure API Management].
+* You can control how the developer portal content appears to different users and groups you've configured. Learn more about [customizing the developer portal](api-management-howto-developer-portal-customize.md#customize-the-portals-content). 
 * Learn how to manage the administrator [email settings](api-management-howto-configure-notifications.md#configure-email-settings) that are used in notifications to developers from your API Management instance.
 
 

articles/api-management/api-management-howto-developer-portal-customize.md

@@ -6,8 +6,9 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: tutorial
-ms.date: 08/31/2021
+ms.date: 11/21/2022
 ms.author: danlep
+ms.custom: engagement-fy23
 ---
 
 # Tutorial: Access and customize the developer portal
@@ -25,7 +26,7 @@ In this tutorial, you learn how to:
 
 You can find more details on the developer portal in the [Azure API Management developer portal overview](api-management-howto-developer-portal.md).
 
-:::image type="content" source="media/api-management-howto-developer-portal-customize/cover.png" alt-text="API Management developer portal - administrator mode" border="false":::
+:::image type="content" source="media/api-management-howto-developer-portal-customize/cover.png" alt-text="Screenshot of the API Management developer portal - administrator mode." border="false":::
 
 ## Prerequisites
 
@@ -80,14 +81,14 @@ If you're accessing the portal for the first time, the default content is automa
 
 You can customize the content of the portal with the visual editor. 
 * The menu sections on the left let you create or modify pages, media, layouts, menus, styles, or website settings. 
-* The menu items on the bottom let you switch between viewports (for example, mobile or desktop), view the elements of the portal visible to authenticated or anonymous users, or save or undo actions.
-* Add rows to a page by clicking on a blue icon with a plus sign. 
+* The menu items on the bottom let you switch between viewports (for example, mobile or desktop), view the elements of the portal visible to users in different groups, or save or undo actions.
+* Add sections to a page by clicking on a blue icon with a plus sign. 
 * Widgets (for example, text, images, or APIs list) can be added by pressing a grey icon with a plus sign.
 * Rearrange items in a page with the drag-and-drop interaction. 
 
 ### Layouts and pages
 
-:::image type="content" source="media/api-management-howto-developer-portal-customize/pages-layouts.png" alt-text="Pages and layouts" border="false":::
+:::image type="content" source="media/api-management-howto-developer-portal-customize/pages-layouts.png" alt-text="Screenshot of the visual editor in the developer portal." border="false":::
 
 Layouts define how pages are displayed. For example, in the default content, there are two layouts: one applies to the home page, and the other to all remaining pages.
 
@@ -97,21 +98,21 @@ In the preceding image, content belonging to the layout is marked in blue, while
 
 ### Styling guide
 
-:::image type="content" source="media/api-management-howto-developer-portal-customize/styling-guide.png" alt-text="Styling guide" border="false":::
+:::image type="content" source="media/api-management-howto-developer-portal-customize/styling-guide.png" alt-text="Screenshot of the styling guide in the developer portal." border="false":::
 
 Styling guide is a panel created with designers in mind. It allows for overseeing and styling all the visual elements in your portal. The styling is hierarchical - many elements inherit properties from other elements. For example, button elements use colors for text and background. To change a button's color, you need to change the original color variant.
 
 To edit a variant, select it and select the pencil icon that appears on top of it. After you make the changes in the pop-up window, close it.
 
 ### Save button
 
-:::image type="content" source="media/api-management-howto-developer-portal-customize/save-button.png" alt-text="Save button" border="false":::
+:::image type="content" source="media/api-management-howto-developer-portal-customize/save-button.png" alt-text="Screenshot of the Save button in the developer portal." :::
 
 Whenever you make a change in the portal, you need to save it manually by selecting the **Save** button in the menu at the bottom, or press [Ctrl]+[S]. When you save your changes, the modified content is automatically uploaded to your API Management service.
 
 ## Customize the portal's content
 
-Before you make your portal available to the visitors, you should personalize the automatically generated content. Recommended changes include the layouts, styles, and the content of the home page.
+Before you make your portal available to the visitors, you should personalize the automatically generated content. Recommended changes include the layouts, styles, and the content of the home page. You can also make certain content elements accessible only to selected users or groups.
 
 > [!NOTE]
 > Due to integration considerations, the following pages can't be removed or moved under a different URL: `/404`, `/500`, `/captcha`, `/change-password`, `/config.json`, `/confirm/invitation`, `/confirm-v2/identities/basic/signup`, `/confirm-v2/password`, `/internal-status-0123456789abcdef`, `/publish`, `/signin`, `/signin-sso`, `/signup`.
@@ -162,6 +163,35 @@ Although you don't need to adjust any styles, you may consider adjusting particu
 1. Select outside the pop-up windows to exit the container settings.
 1. Click **Save**.
 
+### Visibility and access controls
+
+You can control which portal content appears to different users, based on their identity. For example, you might want to display certain pages only to users who have access to a specific product or API. Or, make a section of a page appear only for certain [groups of users](api-management-howto-create-groups.md). The developer portal has built-in controls for these needs.
+
+> [!NOTE]
+> Visibility and access controls are supported only in the managed developer portal. They are not supported in the [self-hosted portal](developer-portal-self-host.md).
+
+* When you add or edit a page, select the **Access** tab to control the users or groups that can access the page
+    
+    :::image type="content" source="media/api-management-howto-developer-portal-customize/page-access-control.png" alt-text="Screenshot of the page access control settings in the developer portal.":::
+
+* When you customize page content such as a page section, menu, or button, select the **Change visibility** icon to control the users or groups that can see the element on the page
+
+    :::image type="content" source="media/api-management-howto-developer-portal-customize/change-visibility-button.png" alt-text="Screenshot of the change visibility button in the developer portal.":::
+
+    * You can change the visibility of the following page content: sections, menus, buttons, and sign-in for OAuth authorization.    
+
+    * Media files such as images on a page inherit the visibility of the elements that contain them.
+
+When a user visits the developer portal with visibility and access controls applied:
+
+* The developer portal automatically hides buttons or navigation items that point to pages that a user doesn't have access to.
+
+* An attempt by a user to access a page they aren't authorized to will result in a 404 Not Found error.
+
+> [!TIP]
+> Using the administrative interface, you can preview pages as a user associated with any built-in or custom group by selecting the **Impersonate** icon in the menu at the bottom. 
+> 
+
 ### Customization example
 
 In the following video, we demonstrate how to edit the content of the portal, customize the website's look, and publish the changes.
@@ -177,7 +207,7 @@ To make your portal and its latest changes available to visitors, you need to *p
 1. Make sure you saved your changes by selecting the **Save** icon.
 1. In the **Operations** section of the menu, select **Publish website**. This operation may take a few minutes.  
 
-    :::image type="content" source="media/api-management-howto-developer-portal-customize/publish-portal.png" alt-text="Publish portal" border="false":::
+    :::image type="content" source="media/api-management-howto-developer-portal-customize/publish-portal.png" alt-text="Screenshot of the Publish website button in the developer portal." border="false":::
 
 ### Publish from the Azure portal
 
@@ -205,4 +235,5 @@ Learn more about the developer portal:
 
 - [Azure API Management developer portal overview](api-management-howto-developer-portal.md)
 - [Migrate to the new developer portal](developer-portal-deprecated-migration.md) from the deprecated legacy portal.
+- Configure authentication to the developer portal with [usernames and passwords](developer-portal-basic-authentication.md), [Azure AD](api-management-howto-aad.md), or [Azure AD B2C](api-management-howto-aad-b2c.md).
 - Learn more about [customizing and extending](developer-portal-extend-custom-functionality.md) the functionality of the developer portal.

articles/api-management/api-management-howto-developer-portal.md

@@ -8,7 +8,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 02/10/2022
+ms.date: 10/28/2022
 ms.author: danlep 
 ms.custom: devx-track-azurepowershell
 ---
@@ -23,14 +23,14 @@ As introduced in this article, you can customize and extend the developer portal
 
 [!INCLUDE [premium-dev-standard-basic.md](../../includes/api-management-availability-premium-dev-standard-basic.md)]
 
-## Migration from the legacy portal
+## Migrate from the legacy portal
 
 > [!IMPORTANT]
 > The legacy developer portal is now deprecated and it will receive security updates only. You can continue to use it, as per usual, until its retirement in October 2023, when it will be removed from all API Management services.
 
 Migration to the new developer portal is described in the [dedicated documentation article](developer-portal-deprecated-migration.md).
 
-## Customization and styling of the managed portal
+## Customize and style the managed portal
 
 Your API Management service includes a built-in, always up-to-date, **managed** developer portal. You can access it from the Azure portal interface.
 
@@ -40,12 +40,14 @@ Your API Management service includes a built-in, always up-to-date, **managed**
 
 * Take advantage of built-in widgets to add text, images, buttons, and other objects that the portal supports out-of-the-box. 
 
+* Control how the portal content appears to different [users and groups](api-management-howto-create-groups.md) configured in your API Management instance. For example, display certain pages only to groups that are associated with particular products, or to users that can access specific APIs. 
+
 > [!NOTE]
 > The managed developer portal receives and applies updates automatically. Changes that you've saved but not published to the developer portal remain in that state during an update.
 
 ## <a name="managed-vs-self-hosted"></a> Options to extend portal functionality
 In some cases you might need functionality beyond the customization and styling options provided in the managed developer portal. If you need to implement custom logic, which isn't supported out-of-the-box, you have [several options](developer-portal-extend-custom-functionality.md):
-* [Add custom HTML](developer-portal-extend-custom-functionality.md#use-custom-html-code-widget) directly through a developer portal widget designed for small customizations - for example, add HTML for a form or to embed a video player. The custom code is rendered in an inline frame (iframe).
+* [Add custom HTML](developer-portal-extend-custom-functionality.md#use-custom-html-code-widget) directly through a developer portal widget designed for small customizations - for example, add HTML for a form or to embed a video player. The custom code is rendered in an inline frame (IFrame).
 * [Create and upload a custom widget](developer-portal-extend-custom-functionality.md#create-and-upload-custom-widget) to develop and add more complex custom portal features.
 * [Self-host the portal](developer-portal-self-host.md), only if you need to make modifications to the core of the developer portal [codebase](https://github.com/Azure/api-management-developer-portal). This option requires advanced configuration. Azure Support's assistance is limited only to the basic setup of self-hosted portals.
 

articles/api-management/developer-portal-self-host.md

@@ -19,6 +19,9 @@ This tutorial describes how to self-host the [API Management developer portal](a
 > * Maintaining and managing hosting infrastructure
 > * Manual updates, including for security patches, which may require you to resolve code conflicts when upgrading the codebase
 
+> [!NOTE]
+> The self-hosted portal does not support visibility and access controls that are available in the managed developer portal.
+
 If you have already uploaded or modified media files in the managed portal, see [Move from managed to self-hosted](#move-from-managed-to-self-hosted-developer-portal), later in this article.
 
 [!INCLUDE [premium-dev-standard-basic.md](../../includes/api-management-availability-premium-dev-standard-basic.md)]