TOC updates and remove auth/auth overviews

kgremban · web-flow · commit 64940ac79e3f · 2023-09-25T16:17:19.000-07:00
diff --git a/articles/iot-hub/TOC.yml b/articles/iot-hub/TOC.yml
@@ -191,19 +191,28 @@
           href: ../iot-edge/iot-edge-as-gateway.md
     - name: Security
       items:
+        - name: Authentication
+          items:
+          - name: Azure Active Directory
+            displayName: authenticate, authentication, auth, authn
+            href: authenticate-azure-ad.md
+          - name: Shared access signatures
+            displayName: authenticate, authentication, auth, authn
+            href: authenticate-sas.md
+          - name: X.509 certificates
+            displayName: authenticate, authentication, auth, authn
+            href: authenticate-x509.md
+        - name: Authorization
+          items:
+          - name: Authorize with Azure Active Directory
+            displayName: authorization, authorize, auth, authz
+            href: authorize-azure-ad.md
+          - name: Authorize with shared access signatures
+            displayName: authorization, authorize, auth, authz
+            href: authorize-sas.md
         - name: TLS support
           displayName: security, Transport Layer Security
           href: iot-hub-tls-support.md
-        - name: Secure using X.509 CA certificates
-          items:
-            - name: X.509 certificate concepts
-              displayName: Public Key Cryptography, X.509 certificates, public key infrastructure (PKI), certificates, Certification Authorities, encryption, ciphertext 
-              href: iot-hub-x509-certificate-concepts.md
-            - name: X.509 CA certificate security concepts
-              displayName: Device Provisioning Service, DPS, Hardware Secure Modules, HSM, self-signed certificate, Public Key Infrastructure, PKI
-              href: iot-hub-x509ca-concept.md
-            - name: X.509 CA certificates for IoT Hub
-              href: iot-hub-x509ca-overview.md
         - name: Virtual networks support
           displayName: Security, Private Link, network isolation, private endpoint
           href: virtual-network-support.md
diff --git a/articles/iot-hub/authenticate-azure-ad.md b/articles/iot-hub/authenticate-azure-ad.md
@@ -13,7 +13,14 @@ ms.custom: ['Role: Cloud Development', 'Role: IoT Device', 'Role: System Archite
 
 # Authenticate with Azure Active Directory
 
-Intro
+## Authentication in IoT Hub
+
+*Authentication* is the process of proving that you are who you say you are. This is achieved by verification of the identity of a user or device to IoT Hub. It's sometimes shortened to *AuthN*. Authentication is separate from *authorization*, which is the process of confirming permissions for an authenticated user or device on IoT Hub.
+
+This article describes authentication that uses **Azure Active Directory (Azure AD) integration** for service APIs. Azure provides identity-based authentication with AAD and fine-grained authorization with Azure role-based access control (Azure RBAC). Azure AD and RBAC integration is supported for IoT hub service APIs only.
+
+## Azure Active Directory authentication
+
 
 ## Next steps
 
diff --git a/articles/iot-hub/authenticate-overview.md b/articles/iot-hub/authenticate-overview.md
diff --git a/articles/iot-hub/authenticate-sas.md b/articles/iot-hub/authenticate-sas.md
@@ -13,6 +13,14 @@ ms.custom: ['Role: Cloud Development', 'Role: IoT Device', 'Role: System Archite
 
 # Authenticate with a shared access signature
 
+## Authentication in IoT Hub
+
+*Authentication* is the process of proving that you are who you say you are. This is achieved by verification of the identity of a user or device to IoT Hub. It's sometimes shortened to *AuthN*. Authentication is separate from *authorization*, which is the process of confirming permissions for an authenticated user or device on IoT Hub.
+
+This article describes authentication that uses **Shared access signatures** lets you group permissions and grant them to applications using access keys and signed security tokens. You can also use symmetric keys or shared access keys to authenticate a device with IoT Hub.
+
+## Shared access signature authentication
+
 Every IoT hub has an identity registry that stores information about the devices and modules permitted to connect to it. Before a device or module can connect, there must be an entry for that device or module in the IoT hub's identity registry. A device or module authenticates with the IoT hub based on credentials stored in the identity registry.
 
 We support two methods of authentication between the device and the IoT hub. You can use SAS token-based authentication or X.509 certificate authentication.
diff --git a/articles/iot-hub/authenticate-x509.md b/articles/iot-hub/authenticate-x509.md
@@ -13,6 +13,14 @@ ms.custom: ['Role: Cloud Development', 'Role: IoT Device', 'Role: System Archite
 
 # Authenticate with X.509 certificates
 
+## Authentication in IoT Hub
+
+*Authentication* is the process of proving that you are who you say you are. This is achieved by verification of the identity of a user or device to IoT Hub. It's sometimes shortened to *AuthN*. Authentication is separate from *authorization*, which is the process of confirming permissions for an authenticated user or device on IoT Hub.
+
+This article describes authentication that uses **X.509 certificates**. You can use any X.509 certificate to authenticate a device with IoT Hub by uploading either a certificate thumbprint or a certificate authority (CA) to Azure IoT Hub. For other authentication options, see [Authenticate with shared access signatures](authenticate-sas.md) or [Authenticate with X.509 certificates](authenticate-x509.md).
+
+## X.509 authentication
+
 Every IoT hub has an identity registry that stores information about the devices and modules permitted to connect to it. Before a device or module can connect, there must be an entry for that device or module in the IoT hub's identity registry. A device or module authenticates with the IoT hub based on credentials stored in the identity registry.
 
 We support two methods of authentication between the device and the IoT hub. You can use SAS token-based authentication or X.509 certificate authentication.
diff --git a/articles/iot-hub/authorize-azure-ad.md b/articles/iot-hub/authorize-azure-ad.md
@@ -4,24 +4,31 @@ titleSuffix: Azure IoT Hub
 description: Understand how Azure IoT Hub uses Azure Active Directory to authorize access to IoT hubs and devices. 
 author: kgremban
 ms.service: iot-hub
-services: iot-hub
 ms.author: kgremban
 ms.topic: conceptual
-ms.date: 05/01/2023
+ms.date: 09/01/2023
 ms.custom: ['Role: Cloud Development', 'Role: IoT Device', 'Role: System Architecture']
 ---
 
-# Authorize access with Azure Active Directory
+# Control access to IoT Hub by using Azure Active Directory
 
-## Control access to IoT Hub by using Azure Active Directory
 
 You can use Azure Active Directory (Azure AD) to authenticate requests to Azure IoT Hub service APIs, like create device identity and invoke direct method. You can also use Azure role-based access control (Azure RBAC) to authorize those same service APIs. By using these technologies together, you can grant permissions to access IoT Hub service APIs to an Azure AD security principal. This security principal could be a user, group, or application service principal.
 
-Authenticating access by using Azure AD and controlling permissions by using Azure RBAC provides improved security and ease of use over [security tokens](iot-hub-dev-guide-sas.md). To minimize potential security issues inherent in security tokens, we recommend that you [use Azure AD with your IoT hub whenever possible](#azure-ad-access-and-shared-access-policies). 
+Authenticating access by using Azure AD and controlling permissions by using Azure RBAC provides improved security and ease of use over [security tokens](iot-hub-dev-guide-sas.md). To minimize potential security issues inherent in security tokens, we recommend that you use Azure AD with your IoT hub whenever possible.
 
 > [!NOTE]
 > Authentication with Azure AD isn't supported for the IoT Hub *device APIs* (like device-to-cloud messages and update reported properties). Use [symmetric keys](iot-hub-dev-guide-sas.md#use-a-symmetric-key-in-the-identity-registry) or [X.509](iot-hub-x509ca-overview.md) to authenticate devices to IoT Hub.
 
+## Authorization in IoT Hub
+
+*Authorization* is the process of confirming permissions for an authenticated user or device on IoT Hub. It specifies what resources and commands you're allowed to access, and what you can do with those resources and commands. Authorization is sometimes shortened to *AuthZ*. Authorization is separate from *authentication*, which is the process of proving that you are who you say you are. For more information about authentication, see [Authentication overview](authenticate-overview.md).
+
+This article describes authorization using **Azure Active Directory (Azure AD) integration** for service APIs. Azure provides identity-based authentication with AAD and fine-grained authorization with Azure role-based access control (Azure RBAC). Azure AD and RBAC integration is supported for IoT hub service APIs only. For other authorization options, see [Authorize access with shared access signatures](authorize-sas.md). 
+
+> [!TIP]
+> You can enable a lock on your IoT resources to prevent them being accidentally or maliciously deleted. To learn more about Azure Resource locks, please visit, [Lock your resources to protect your infrastructure](../azure-resource-manager/management/lock-resources.md?tabs=json)
+
 ## Authentication and authorization
 
 When an Azure AD security principal requests access to an IoT Hub service API, the principal's identity is first *authenticated*. For authentication, the request needs to contain an OAuth 2.0 access token at runtime. The resource name for requesting the token is `https://iothubs.azure.net`. If the application runs in an Azure resource like an Azure VM, Azure Functions app, or Azure App Service app, it can be represented as a [managed identity](../active-directory/managed-identities-azure-resources/how-managed-identities-work-vm.md). 
diff --git a/articles/iot-hub/authorize-overview.md b/articles/iot-hub/authorize-overview.md
diff --git a/articles/iot-hub/authorize-sas.md b/articles/iot-hub/authorize-sas.md
@@ -26,6 +26,15 @@ This article introduces:
 
 You must have appropriate permissions to access any of the IoT Hub endpoints. For example, a device must include a token containing security credentials along with every message it sends to IoT Hub. However, the signing keys, like the device symmetric keys, are never sent over the wire.
 
+## Authorization in IoT Hub
+
+*Authorization* is the process of confirming permissions for an authenticated user or device on IoT Hub. It specifies what resources and commands you're allowed to access, and what you can do with those resources and commands. Authorization is sometimes shortened to *AuthZ*. Authorization is separate from *authentication*, which is the process of proving that you are who you say you are. For more information about authentication, see [Authentication overview](authenticate-overview.md).
+
+This article describes authorization using **Shared access signatures** lets you group permissions and grant them to applications using access keys and signed security tokens. For other authorization options, see [Authorize access with Azure Active Directory](authorize-azure-ad.md).
+
+> [!TIP]
+> You can enable a lock on your IoT resources to prevent them being accidentally or maliciously deleted. To learn more about Azure Resource locks, please visit, [Lock your resources to protect your infrastructure](../azure-resource-manager/management/lock-resources.md?tabs=json)
+
 ## Access control and permissions
 
 Use shared access policies for IoT hub-level access, and use the individual device credentials to scope access to that device only.
