Reconfigure FQDNs and Ports in Windows Azure Pack

Artikkeli
09/07/2016

Applies To: Windows Azure Pack

Windows Azure Pack for Windows Server uses claim-based authentication system to authenticate and authorize users. This authentication is performed by an external Identity Provider Security Token Service (IdP-STS). The system trusts the IdP-STS to verify the identity of users and to provide a trusted set of claims about each user. A two-way trust relationship with the IdP-STS must be established during Windows Azure Pack configuration so the endpoint changes are properly communicated to the affected components.

To establish this trust relationship, the following Windows Azure Pack components expose metadata information.

Management portal for tenants
Management portal for administrators
Tenant authentication site
Admin authentication site

The exposed data includes all the necessary trust information, including the endpoint information of the different components. The endpoint information is used to redirect users to the IdP-STS and back to Windows Azure Pack.

Therefore, every time an endpoint configuration changes for a component, the metadata information must be updated and the trust relationship must be re-established using the updated metadata.

Windows Azure Pack installation and configuration provides default values for the exposed metadata and endpoint information. By default, Windows Azure Pack uses the machine and domain name as the Fully Qualified Domain Name (FQDN) of each component. It also sets pre-defined port numbers for each component.

For example, if your tenant machine hostname is “mytenantmachine” and your domain is “contoso.com”, the default configuration of the Tenant Portal will be https://mytenantmachine.contoso.com:30081.

In some scenarios, the default endpoint values must be changed. For example:

If you update a component's default self-signed SSL certificate to a real certificate, the component's FQDN must match the certificate FQDN.
If you use a load balancer across multiple instances of a component, you must use the load balancer endpoint instead of the endpoint of each component instance.
If you change the pre-defined ports you must update the Windows Azure Pack port settings. For example, changing to the default HTTPS port 443 requires you to update the Windows Azure Pack port settings.

In such cases, the metadata information must be updated and the trust relationship must be re-established as explained in the following steps.

To update the FQDN and port settings

Run the Set–MgmtSvcFqdn cmdlet on the machine you want to update.

Set-MgmtSvcFqdn –Namespace <Namsepace Token> -ConnectionString <Connection String> [-FQDN <FQDN>] [-Port <port>] [-Verbose]

Parameter	Required/optional	Details
-ConnectionString	Required	This parameter defines the connection string to the SQL Server hosting the Windows Azure Pack configuration stores. A database name (Initial Catalog) is not required. Credentials included in the string must have write permissions to the configuration stores. For example: `$connectionString = “Data Source=$server;User ID=$userId;Password=$password”` $server – The address of the SQL Server hosting the management portal configuration databases. $userId – A SQL user with write permissions to the management portal configuration databases. $password – The password for the $userId account.
-FQDN	Optional	This parameter is used to specify the new FQDN for the machine. Replace $fqdn with the new FQDN, not including the protocol prefix. For example, mynewfqdn.contoso.com. You can omit this parameter if you are not changing the FQDN.
-Namespace	Required	This parameter is used to indicate which component to configure. Possible values: 'AdminSite', 'TenantSite', 'AuthSite', 'WindowsAuthSite'.
-Port	Optional	This parameter is used to define the new port. Replace $port with the new port. For example, 443. Note Using the default HTTPS port 443 will remove the port section from the endpoint. You can omit this parameter if you are not changing the port.

In Internet Information Services Manager, ensure that the FQDN and port values have been updated. Also ensure that the FQDN matches the SSL certificate.
The updated FQDN and port values will eventually propagate to the targeted components. To ensure that this happens immediately, restart the website.
Repeat steps 2 and 3 on all machines hosting the component.
If needed, set up your DNS to forward requests to the appropriate location.
Re-establish trust between all the affected components as instructed in the next section.

Re-establish trust

Windows Azure Pack is a claims-aware application that uses tokens and claims to authenticate and authorize end users. Such applications don't use the identity of the token issuer, as long as the token complies with some conditions, such as being signed by a trusted key. For more information, see Claims-aware applications.

With claims-based authentication, a system trusts an STS to issue its tokens. However, that doesn’t necessarily mean that this STS is actually performing the user authentication. It is possible that the STS delegates the user authentication request (or federation) to another STS which is trusted by the first STS. This chain of STSs trusting each other and delegating requests is common and flexible. There are endless possible topologies of trust relationships. System administrators must choose the most appropriate topology to meet business requirements.

For example, you can configure Windows Azure Pack management portals to trust AD FS to authenticate users. Depending on the AD FS configuration, AD FS can then do either of the following:

AD FS can authenticate users directly, using the management portal Active Directory credentials.
AD FS can federate the request to another STS.

In the second case, you can use Windows Azure Access Active Directory Control Service (ACS) as the other STS, for example. ACS can then federate the request again to another STS, such as Windows Live. In this case, Windows Live actually authenticates the user using Windows Live credentials. This is one way to enable Windows Live, Google, or Facebook authentication in Windows Azure Pack.

Important

Because the endpoints are used to redirect users to the next component in the trust chain, all endpoints must be configured correctly in all components to ensure the federation is successful.

If you change a management portal endpoint, you must update the STS that the portal immediately trusts.

Ensure that you update the FQDN and port changes in STS for the relying party federation metadata URL, and then refresh the metadata.

If you change an STS endpoint, you must update all the components directly trusted by it, such as the management portals and other STSs.

The system administrator should be familiar with the trust chain to understand which components must be updated following a configuration change.

Re-establish trust for the management portals

If the STS endpoint immediately trusted by a Windows Azure Pack management portal was changed, you must update the portals with the new endpoint information. You can do this by using the Set-MgmtSvcRelyingPartySettings PowerShell cmdlet on the relevant machines.

Set-MgmtSvcRelyingPartySettings -Target <Targets> –MetadataEndpoint <Metadata Endpoint Full URL> [-ConnectionString <Connection String>] [-DisableCertificateValidation] [-PortalConnectionString <Portal Configuration Store Connection String>] [-ManagementConnectionString <Management Store Connection String>]

Parameter	Required/optional	Details
Target	Required	This parameter defines which set of components to update. Permissible values for <Targets>: Tenant – Use this to configure the management portal for tenants, the tenant API layer, and the admin API layer. Admin – Use this to configure the management portal for administrators and the admin API layer. You can provide a single target or an array of targets.
MetadataEndpoint	Required	This parameter defines the full URL of the trusted IdP-STS metadata endpoint. Permissible values for <Metadata Endpoint Full URL>: A valid URL, for example: http://mysts.contoso.com:1234/FederationMetadata/2007-06/FederationMetadata.xml
ConnectionString	Required, unless PortalConnectionString and ManagementConnectionString are used.	This parameter defines the connection string to the SQL Server hosting the Windows Azure Pack portal configuration stores and management store. A database name (Initial Catalog) is not required. If the portal configuration stores or management store are hosted on different SQL Server instances or use non-default database names, use the PortalConnectionString and ManagementConnectionString parameters instead.
DisableCertificateValidation	Optional Not recommended for production environments	This parameter disables SSL certificate validation. If you don't use this parameter, the cmdlet will fail to retrieve the metadata information if the metadata endpoint uses a self-signed SSL certificate.
PortalConnectionString	Optional, unless ConnectionString is not provided	Use this parameter to override the default connection string just for the configuration store. You should do this when - The portal configuration store is located on a different SQL instance. - The portal configuration store uses different credentials. - You don't want to use the default connection string.
ManagementConnectionString	Optional, unless ConnectionString is not provided	Use this parameter to override the default connection string just for the management store. You should do this when - The WAP management store is located on a different SQL instance. - The management store uses different credentials. - You don't want to use the default connection string.

Example cmdlet:

Set-MgmtSvcRelyingPartySettings –Target Tenant –MetadataEndpoint ‘https://mysts.contoso.com:12345/FederationMetadata/2007-06/FederationMetadata.xml’ -ConnectionString “Data Source=mysqlserver.contoso.com;User ID=myprivilegeduser;Password=mypassword”

Tip

This cmdlet can be used on any machine where the Windows Azure PowerShell updates for Windows Azure Pack are installed.
The updated settings will eventually propagate to all affected components. For faster propagation, manually restart the affected components to immediately fetch the new configuration values. If the target is ‘Tenant’ you should restart all your management portals for tenants, tenant API, and admin API components. If the target is ‘Admin’ you should restart all your management portals for administrators and admin API components.

Re-establish trust for the authentication sites

If the STS endpoint immediately trusted by a Windows Azure Pack authentication site was changed, you must update the authentication sites with the new endpoint information. You can do this by using the PowerShell cmdlet Set-MgmtSvcIdentityProviderSettings PowerShell cmdlet on the relevant machines.

Set-MgmtSvcIdentityProviderSettings -Target <Targets> –MetadataEndpoint <Metadata Endpoint Full URL> [-ConfigureSecondary] [-ConnectionString <Connection String>] [-DisableCertificateValidation] [-PortalConnectionString <Portal Configuration Store Connection String>]

Parameter	Required/optional	Details
Target	Required	This parameter defines which set of components to update. Permissible values for <Targets>: Membership – Use this to configure the tenant (Membership) authentication site. Windows – Use this to configure the admin (Windows) authentication site. You can provide a single target or an array of targets.
MetadataEndpoint	Required	This parameter defines the full URL of the trusted component metadata endpoint. Permissible values for <Metadata Endpoint Full URL>: A valid URL, for example: http://mysts.contoso.com:1234/FederationMetadata/2007-06/FederationMetadata.xml
ConfigureSecondary	Optional	Each authentication site supports up to two trusted relying parties. Include this parameter to configure a second relying party, instead of overwriting the default relying party.
ConnectionString	Required, unless PortalConnectionString is used	This parameter defines the connection string to the SQL Server hosting the Windows Azure Pack portal configuration stores. A database name (Initial Catalog) is not required. If portal configuration store uses a non-default database name, use the PortalConnectionString parameter instead.
DisableCertificateValidation	Optional Not recommended for production environments	This parameter disables SSL certificate validation. If you don't use this parameter, the cmdlet will fail to retrieve the metadata information if the metadata endpoint uses a self-signed SSL certificate.
PortalConnectionString	Optional, unless ConnectionString is not provided	Use this parameter to override the default connection string just for the configuration store. You should do this when - The portal configuration store uses different credentials. - You don't want to use the default connection string.