Set-CsWebServiceConfiguration
Topic Last Modified: 2012-04-23
Modifies an existing collection of Web Services configuration settings.
Syntax
Set-CsWebServiceConfiguration [-Identity <XdsIdentity>] [-AllowAnonymousAccessToLWAConference <$true | $false>] [-CASigningKeyLength <UInt64>] [-Confirm [<SwitchParameter>]] [-DefaultValidityPeriodHours <UInt64>] [-EnableCertChainDownload <$true | $false>] [-EnableGroupExpansion <$true | $false>] [-Force <SwitchParameter>] [-InferCertChainFromSSL <$true | $false>] [-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>]]
Set-CsWebServiceConfiguration [-AllowAnonymousAccessToLWAConference <$true | $false>] [-CASigningKeyLength <UInt64>] [-Confirm [<SwitchParameter>]] [-DefaultValidityPeriodHours <UInt64>] [-EnableCertChainDownload <$true | $false>] [-EnableGroupExpansion <$true | $false>] [-Force <SwitchParameter>] [-InferCertChainFromSSL <$true | $false>] [-Instance <PSObject>] [-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>]]
Detailed Description
Many Microsoft Lync Server 2010 components are web-based: these components either use Web Services or webpages 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 Microsoft Lync Server 2010 Control Panel use webpages as the interface between Lync Server 2010 and users.
The CsWebServiceConfiguration cmdlets enable administrators to manage Web Services 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 Web Services service), you can customize Web Services capabilities for different users and different locations. The CsWebServiceConfiguration cmdlets (Get-CsWebServiceConfiguration, New-CsWebServiceConfiguration, Remove-CsWebServiceConfiguration, and Set-CsWebServiceConfiguration) enable administrators to manage Web Services 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 (Web Services service only) you can customize Web Services capabilities for different users and different locations.
Custom settings (for example, custom validity periods for certificates) can be specified at the time you create a new Web Services configuration setting collection. Alternatively, you can modify the property values for an existing collection by using the Set-CsWebServiceConfiguration cmdlet.
Who can run this cmdlet: By default, members of the following groups are authorized to run the Set-CsWebServiceConfiguration cmdlet locally: RTCUniversalServerAdmins. To return a list of all the role-based access control (RBAC) roles this cmdlet has been assigned to (including any custom RBAC roles you have created yourself), run the following command from the Windows PowerShell prompt:
Get-CsAdminRole | Where-Object {$_.Cmdlets –match "Set-CsWebServiceConfiguration"}
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
Identity |
Required |
Xds Identity |
Unique identifier for the Web Services configuration settings to be modified. To modify settings configured at the site scope, use syntax similar to this: -Identity "site:Redmond". To modify settings configured at the service scope, use syntax similar to this: -Identity "service:WebServer:atl-cs-001.litwareinc.com". To modify settings configured at the global scope, you can use this syntax: -identity global. If the Identity parameter is not used then Set-CsWebServiceConfiguration will automatically modify the global collection. |
Instance |
Required |
WebServiceSettings object |
Allows you to pass a reference to an object to the cmdlet rather than set individual parameter values. |
AllowAnonymousAccessToLWAConference |
Optional |
Boolean |
When set to True, anonymous users will be allowed to attend Lync Web App (LWA) conferences. |
CASigningKeyLength |
Optional |
Integer |
Sets the size of the CA signing key, the private key used by a certification authority (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. |
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). |
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 CA. Certificates will not be accepted for authentication unless the certificate’s CA is trusted. |
EnableGroupExpansion |
Optional |
If set to True, group expansion will be enabled in Microsoft Lync 2010. 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 the individual members of a group and their current presence information. |
|
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. |
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. |
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 for a CSR key can be set to any integer value between 1024 and 16384 bytes. The default value is 16384. |
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. |
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. |
MinCSRKeySize |
Optional |
Integer |
Sets the minimum size of the Certificate Signing Request (CSR) key. The minimum size can be set to any integer value between 1024 and 16384 bytes. The default value is 16384. |
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. |
SecondaryLocationSourceUrl |
Optional |
String |
URL for a web service that can process a location request. This service is only used when location requests cannot be resolved locally. |
ShowDownloadCommunicatorAttendeeLink |
Optional |
Boolean |
If set to True (the default value), users joining a meeting by using a client application other than Lync 2010 will see a link that points them to a download for Lync 2010 Attendee. |
ShowJoinUsingLegacyClientLink |
Optional |
Boolean |
If set to True, users joining a meeting by using a client application other than Lync 2010 will be given the opportunity to join the meeting by using their current client application. The default value is False. |
TrustedCACerts |
Optional |
Certificate collection |
Collection of certificates representing certificate chains trusted by the Web Server. New certificates added to the collection must be created by using the New-CsWebTrustedCACertificate cmdlet. This collection is not used if the InferCertChainFromSSL property is set to True. |
UseCertificateAuth |
Optional |
Boolean |
When set to True (the default value), clients can be authenticated using certificates. Set this value to False to disable certificate authentication. |
UsePinAuth |
Optional |
Boolean |
When set to True (the default value), clients can be authenticated using personal identification numbers (PINs). Set this value to False to disable PIN authentication. |
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. |
Force |
Optional |
Switch Parameter |
Suppresses any confirmation prompts or non-fatal error messages that might occur when you run the cmdlet. |
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. |
Input Types
Microsoft.Rtc.Management.WritableConfig.Settings.Web.WebServiceSettings object. Set-CsWebServiceConfiguration accepts pipelined input of the Web Services settings object.
Return Types
Set-CsWebServiceConfiguration does not return a value or object. Instead, the cmdlet configures instances of the Microsoft.Rtc.Management.WritableConfig.Settings.Web.WebServiceSettings object.
Example
-------------------------- Example 1 ------------------------
Set-CsWebServiceConfiguration -Identity site:Redmond -EnableGroupExpansion $True
Example 1 enables group expansion for the Web Services configuration settings applied to the Redmond site (-Identity site:Redmond). This is done by including the EnableGroupExpansion property and setting the parameter value to True.
-------------------------- Example 2 ------------------------
Get-CsWebServiceConfiguration -Filter "site:*" | Set-CsWebServiceConfiguration -MaxValidityPeriodHours 16
In Example 2, the maximum validity period for all the Web Services configuration settings applied at the site scope is changed to 16 hours. To carry out this task, Get-CsWebServiceConfiguration is called along with the Filter parameter; the filter value "site:*" limits the returned data to settings where the Identity begins with the characters "site:". This collection is then piped to Set-CsWebServiceConfiguration, which takes each item in the collection and changes the MaxValidityPeriodHours property to 16.
-------------------------- Example 3 ------------------------
Get-CsWebServiceConfiguration | Where-Object {$_.EnableGroupExpansion -eq $True} | Set-CsWebServiceConfiguration -MaxGroupSizeToExpand 400
In the preceding command, the group expansion size is set to 400 for each collection of Web Services configuration settings that allow group expansion. To do this, Get-CsWebServiceConfiguration is called without any parameters; this returns a collection of all the Web Services configuration settings used in the organization. This collection is then piped to Where-Object, which selects only those settings where the EnableGroupExpansion property is equal to True. In turn, this filtered collection is piped to Set-CsWebServiceConfiguration, which takes each item in the collection and sets the value of the MaxGroupSizeToExpand property to 400.
-------------------------- Example 4 ------------------------
Set-CsWebServiceConfiguration -Identity global -ShowDownloadCommunicatorAttendeeLink $True
The command shown in Example 4 shows how the global Web Services settings can be configured so that any person joining a meeting using a client application other than Lync 2010 will first be shown a link to a site where he or she can download Lync 2010 Attendee. This is done by including the ShowDownloadCommunicatorAttendeeLink parameter and setting the parameter value to $True.
See Also
Other Resources
Get-CsWebServiceConfiguration
New-CsWebServiceConfiguration
Remove-CsWebServiceConfiguration