Povratne informacije Uredi

Set up custom domain

  • Članak
  • 4 min. za čitanje

This sample script sets up custom domain on proxy and portal endpoint of the API Management service.

Note

This article uses the Azure Az PowerShell module, which is the recommended PowerShell module for interacting with Azure. To get started with the Az PowerShell module, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article, without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Screenshot that shows how to launch Cloud Shell in a new window.
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Screenshot that shows the Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux, or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

If you choose to install and use the PowerShell locally, this tutorial requires the Azure PowerShell module version 1.0 or later. Run Get-Module -ListAvailable Az to find the version. If you need to upgrade, see Install Azure PowerShell module. If you are running PowerShell locally, you also need to run Connect-AzAccount to create a connection with Azure.

Sample script

##########################################################
#  Script to setup custom domain on proxy and portal endpoint
#  of api management service.
###########################################################

$random = (New-Guid).ToString().Substring(0,8)

#Azure specific details
$subscriptionId = "my-azure-subscription-id"

# Api Management service specific details
$apimServiceName = "apim-$random"
$resourceGroupName = "apim-rg-$random"
$location = "Japan East"
$organisation = "Contoso"
$adminEmail = "admin@contoso.com"

# Set the context to the subscription Id where the cluster will be created
Select-AzSubscription -SubscriptionId $subscriptionId

# Create a resource group.
New-AzResourceGroup -Name $resourceGroupName -Location $location

# Create the Api Management service. Since the SKU is not specified, it creates a service with Developer SKU. 
New-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apimServiceName -Location $location -Organization $organisation -AdminEmail $adminEmail

# Certificate related details
$proxyHostname = "proxy.contoso.net"
# Certificate containing Common Name CN="proxy.contoso.net" or CN=*.contoso.net
$proxyCertificatePath = "C:\proxycert.pfx"
$proxyCertificatePassword = "certPassword"

$portalHostname = "portal.contoso.net"
# Certificate containing Common Name CN="portal.contoso.net" or CN=*.contoso.net
$portalCertificatePath = "C:\portalcert.pfx"
$portalCertificatePassword = "certPassword"

# Upload the custom ssl certificate to be applied to Proxy endpoint / Api Gateway endpoint
$proxyCertUploadResult = Import-AzApiManagementHostnameCertificate -Name $apimServiceName -ResourceGroupName $resourceGroupName `
                        -HostnameType "Proxy" -PfxPath $proxyCertificatePath -PfxPassword $proxyCertificatePassword

# Upload the custom ssl certificate to be applied to Portal endpoint
$portalCertUploadResult = Import-AzApiManagementHostnameCertificate -Name $apimServiceName -ResourceGroupName $resourceGroupName `
                        -HostnameType "Portal" -PfxPath $portalCertificatePath -PfxPassword $portalCertificatePassword

# Create the HostnameConfiguration object for Portal endpoint
$PortalHostnameConf = New-AzApiManagementHostnameConfiguration -Hostname $proxyHostname -CertificateThumbprint $proxyCertUploadResult.Thumbprint

# Create the HostnameConfiguration object for Proxy endpoint
$ProxyHostnameConf = New-AzApiManagementHostnameConfiguration -Hostname $portalHostname -CertificateThumbprint $portalCertUploadResult.Thumbprint

# Apply the configuration to API Management
Set-AzApiManagementHostnames -Name $apimServiceName -ResourceGroupName $resourceGroupName `
        -PortalHostnameConfiguration $PortalHostnameConf -ProxyHostnameConfiguration $ProxyHostnameConf

Clean up resources

When no longer needed, you can use the Remove-AzResourceGroup command to remove the resource group and all related resources.

Remove-AzResourceGroup -Name myResourceGroup

How API Management proxy server responds with SSL certificates in the TLS handshake

When configuring a custom domain for the Gateway endpoint, you can set additional properties that determine how API Management responds with a server certificate, depending on the client request.

Clients calling with Server Name Indication (SNI) header

If you have one or multiple custom domains configured for the Gateway endpoint, API Management can respond to HTTPS requests from either:

  • Custom domain (for example, contoso.com)
  • Default domain (for example, apim-service-name.azure-api.net).

Based on the information in the SNI header, API Management responds with the appropriate server certificate.

Clients calling without SNI header

If you are using a client that does not send the SNI header, API Management creates responses based on the following logic:

  • If the service has just one custom domain configured for Gateway, the default certificate is the certificate issued to the Gateway's custom domain.

  • If the service has configured multiple custom domains for Gateway (supported in the Developer and Premium tier), you can designate the default certificate by setting the defaultSslBinding property to true ("defaultSslBinding":"true"). In the portal, select the Default SSL binding checkbox.

    If you do not set the property, the default certificate is the certificate issued to the default Gateway domain hosted at *.azure-api.net.

Support for PUT/POST request with large payload

API Management proxy server supports requests with large payloads (>40 KB) when using client-side certificates in HTTPS. To prevent the server's request from freezing, you can set the negotiateClientCertificate property to true ("negotiateClientCertificate": "true") on the Gateway hostname. In the portal, select the Negotiate client certificate checkbox.

If the property is set to true, the client certificate is requested at SSL/TLS connection time, before any HTTP request exchange. Since the setting applies at the Gateway hostname level, all connection requests ask for the client certificate. You can work around this limitation and configure up to 20 custom domains for Gateway (only supported in the Premium tier).

Next steps

For more information on the Azure PowerShell module, see Azure PowerShell documentation.

Additional Azure PowerShell samples for Azure API Management can be found in the PowerShell samples.