Creates a new collection of Web service configuration settings.
Syntax
New-CsWebServiceConfiguration -Identity <XdsIdentity> [-CASigningKeyLength <UInt64>] [-Confirm [<SwitchParameter>]] [-DefaultValidityPeriodHours <UInt64>] [-EnableCertChainDownload <$true | $false>] [-EnableGroupExpansion <$true | $false>] [-Force <SwitchParameter>] [-InferCertChainFromSSL <$true | $false>] [-InMemory <SwitchParameter>] [-MACResolverUrl <String>] [-MaxCSRKeySize <UInt64>] [-MaxGroupSizeToExpand <UInt32>] [-MaxValidityPeriodHours <UInt64>] [-MinCSRKeySize <UInt64>] [-MinValidityPeriodHours <UInt64>] [-SecondaryLocationSourceUrl <String>] [-ShowDownloadCommunicatorAttendeeLink <$true | $false>] [-ShowJoinUsingLegacyClientLink <$true | $false>] [-TrustedCACerts <PSListModifier>] [-UseCertificateAuth <$true | $false>] [-UsePinAuth <$true | $false>] [-UseWindowsAuth <None | Negotiate | NTLM>] [-WhatIf [<SwitchParameter>]] |
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
|
Identity |
Required |
Xds Identity |
Unique identifier for the Web service configuration settings to be created. To create settings configured at the site scope, use syntax similar to this: -Identity "site:Redmond". To create settings configured at the service scope, use syntax similar to this: -Identity "service:WebServer:atl-cs-001.litwareinc.com". Note that any settings created at the service scope must be assigned to the Web Server service. |
|
TrustedCACerts |
Optional |
Certificate collection |
Collection of certificates representing certificate chains trusted by the Web server. New certificates added to the collection must be created using the New-CsWebTrustedCACertificate cmdlet. This collection is not used if the InferCertChainFromSSL property is set to true. |
|
EnableGroupExpansion |
Optional |
If set to True, group expansion will be enabled in Communicator. With group expansion, users can configure a distribution group as a contact, then "expand" that group. When a group has been expanded, users can see all the individual members of a group and their current presence information. |
|
|
MaxGroupSizeToExpand |
Optional |
Integer |
Represents the maximum number of people that will be displayed when a group is expanded. For example, if MaxGroupSizeToExpand is set to 75 only the first 75 members of the group will be displayed any time the group is expanded. MaxGroupSizeToExpand can be set to any integer value between 1 and 1000, inclusive. The default value is 100. |
|
UseWindowsAuth |
Optional |
PS List Modifier |
Determines how (and if) users will be authenticated using Windows authentication; that is, using the same credentials they used when they logged on to Windows. Valid values are: Negotiate – The client and server will work together to determine the proper authentication protocol (either Kerberos or NTLM). NTLM – Windows authentication will be allowed, but only using the NTLM protocol. None – Windows authentication will not be allowed. |
|
UseCertificateAuth |
Optional |
Boolean |
When set to True (the default value), clients can be authenticated using certificates. Set this value to False ($False) to disable certificate authentication. |
|
UsePinAuth |
Optional |
Boolean |
When set to True (the default value), clients can be authenticated using PIN numbers. Set this value to False ($False) to disable PIN number authentication. |
|
EnableCertChainDownload |
Optional |
Boolean |
If set to True, servers presented with an authentication certificate will download the certificate chain for that certificate. The certificate chain traces an individual certificate back to the issuing certification authority (CA). Certificates will not be accepted for authentication unless the certificate’s CA is trusted. |
|
InferCertChainFromSSL |
Optional |
Boolean |
If set to True, servers will use the certificate information included in the Secure Sockets Layer (SSL) protocol to determine the issuing CA. Certificates will not be accepted for authentication unless the certificate’s CA is trusted. |
|
CASigningKeyLength |
Optional |
Integer |
Sets the size of the CA signing key, the private key used by a CA to sign digital certificates. The signing key length can be set to any integer value between 2048 and 16384 bytes; the default value is 2048. |
|
MaxCSRKeySize |
Optional |
Integer |
Sets the maximum size of the Certificate Signing Request (CSR) key. (A CSR is a message sent from an applicant to a CA in order to apply for a digital certificate.) The maximum size can be set to any integer value between 1024 and 16384 bytes. The default value is 16384. |
|
MinCSRKeySize |
Optional |
Integer |
Sets the minimum size of the Certificate Signing Request (CSR) key. (A CSR is a message sent from an applicant to a CA in order to apply for a digital certificate.) The minimum size can be set to any integer value between 1024 and 16384 bytes. The default value is 16384. |
|
MaxValidityPeriodHours |
Optional |
Integer |
When using certificate authentication, clients can request the period of time (in hours) that the certificate remains valid. MaxValidityPeriodHours represents the maximum amount of time a client can request. MaxValidityPeriodHours can be any integer value between 8 hours and 8760 hours (365 days). The default value is 8760. |
|
MinValidityPeriodHours |
Optional |
Integer |
When using certificate authentication, clients can request the period of time (in hours) that the certificate remains valid. MinValidityPeriodHours represents the minimum amount of time a client can request. MinValidityPeriodHours can be any integer value between 8 hours and 4320 hours (180 days). The default value is 8. |
|
DefaultValidityPeriodHours |
Optional |
Integer |
When using certificate authentication, clients can request the period of time (in hours) that the certificate remains valid. DefaultValidityPeriodHours represents the amount of time a certificate will remain valid if the client does not request a custom validity period. DefaultValidityPeriodHours can be any integer value between 8 hours and 8760 hours (365 days). The default value is 4320 (180 days). |
|
MACResolverUrl |
Optional |
String |
URL for a Web service capable of performing Media Access Control (MAC) resolution. MAC resolution involves taking an IP address and determining the MAC address of the network card associated with that IP address. |
|
ShowDownloadCommunicatorAttendeeLinks |
Optional |
String |
If set to True (the default value), users joining an online meeting using a client application other than Microsoft Communicator “14” will see a link that points them towards a download for Communicator 2010 Attendee. |
|
ShowJoinusingLegacyClientLink |
Optional |
String |
If set to True, users joining an online meeting using a client application other than Microsoft Communicator “14” will be given the opportunity to join the meeting using their current client application. The default value is False. |
|
SecondaryLocationSourceUrl |
Optional |
String |
URL for a Web service that can process a location request. Used only when location requests cannot be resolved locally. |
|
InMemory |
Optional |
Switch Parameter |
Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet. |
|
Force |
Optional |
Switch Parameter |
Suppresses the display of any non-fatal error message that might arise when running the command. |
|
WhatIf |
Optional |
Switch Parameter |
Describes what would happen if you executed the command without actually executing the command. |
|
Confirm |
Optional |
Switch Parameter |
Prompts you for confirmation before executing the command. |
Detailed Description
Many Microsoft Communications Server 2010components are Web-based: these components either use Web services or Web pages to carry out their tasks. For example, users employ a Web service when searching for new contacts in the Address Book or when using group expansion to view the individual members of a distribution group. Likewise, components ranging from dial-in conferencing to Communications Server Control Panel use Web pages as the interface between Communications Server 2010 and users.
The CsWebServiceConfiguration cmdlets enable administrators to manage Web service configuration settings throughout the organization. This includes managing group expansion, certificate settings, and allowed authentication methods. Because you can configure different settings at the global, site, and service scope (albeit for the only the WebServer service), you can customize Web service capabilities for different users and different locations.
New Web service configuration settings are created using the New-CsWebServiceConfiguration cmdlet. Note that these settings can only be created at the site or service scope (and only for the Web Server service); your command will fail if you try to create a new collection at the global scope. Likewise, your command will fail if you try to create a new collection at, for instance, the Redmond site, and that site already hosts a collection of Web service settings.
Return Types
New-CsWebServiceConfiguration creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Web.WebServiceSettings object.
Examples
-------------------------- Example 1 ------------------------
 Copy Code |
|
|---|---|
New-CsWebServiceConfiguration -Identity site:Redmond -EnableGroupExpansion $False -UseCertAuth $True |
|
The command shown in Example 1 creates a new collection of Web service configuration settings for the Redmond site (-Identity site:Redmond). This example includes two optional parameters: EnableGroupExpansion, which is set to False ($False); and UseCertIDAuth, which is set to True ($True). These two parameters are used to disable group expansion and enable the use of certificates for authentication, respectively.
Note that this command will fail if a collection of Web service configuration settings has already been created for the Redmond site. That’s because sites are limited to a single collection of Web service configuration settings.
-------------------------- Example 2 ------------------------
| Copy Code |
|
|---|---|
$x = New-CsWebServiceConfiguration -Identity site:Redmond -InMemory $x.EnableGroupExpansion = $False $x.UseCertIDAuth = $True Set-CsWebServiceConfiguration $x |
|
Example 2 is a variation of the command shown in Example 1; in this case, however, the new collection of Web service configuration settings is initially created in memory only, and is only later applied to the Redmond site. In order to do this, the first command in the example uses New-CsWebServiceConfiguration to create a collection of settings for the Redmond site; the InMemory parameter is included to ensure that this collection is created in memory only and is not immediately applied to the Redmond site. (Because the settings exist only in memory, they must be stored in a variable. In this case, that’s a variable named $x.)
Commands 2 and 3 in the example take the new virtual Web configuration settings and modify the values of the EnableGroupExpansion and UseCertAuth properties. After these changes have been made, the final command uses the Set-CsWebServiceConfiguration to take the virtual settings and apply them to the Redmond site. If you do not call Set-CsWebServiceConfiguration, no new settings will be assigned to the site. Instead, your virtual Web service configuration settings will disappear as soon as you terminate your Windows PowerShell session or delete the variable $x.