Haiku #161
Do you trust that Web
Server? Of course; it has a
Trusted CA cert.
What? The Lync Server what of the day? Haiku?!? What in the world are you –
Oh, right: the Lync Server PowerShell haiku of the day. You'll have to forgive the author of today's haiku: he's a bit out of it today, even more so than usual. Why? Well, as it turns out, today just happens to be TechReady 13, an internal technical conference for Microsoft support personnel.
Note. How exciting is TechReady? Does this answer your question: "[TechReady] is a technical training and readiness event aligning our customer-facing technical field with the SMSG execution strategy."
You know what? That's exactly what we said.
Incidentally, as near as we can tell, SMSG is short for Sales, Marketing, Services, IT & Operations Group. (Well, it's kind of short for that.) Do these people really deserve to be executed? Well, not all of them …
Another note. No, the execution strategy does not involve that kind of execution. That was just a joke.
As you might recall, the author of today's haiku has spoken at TechReady in the past; this time around, however, he wasn't going to even attend the conference, let alone do anything there. At least he didn't intend to until yesterday afternoon, when, thanks to other people being called out of town, he suddenly got pressed into action, being asked to help out with a presentation on Extreme PowerShell for Lync Server. (Cool title, huh?) His reward for agreeing to help out in a pinch like this? He got to stay up until 1:00 in the morning working on the slides for the presentation, and then, as if that wasn't reward enough, got to get up four hours later to continue working on the presentation. Pretty cool, huh?
Note. Yes, that does sound like burning the candle at both ends. The only problem with that analogy is that the author of today's haiku doesn't really have a candle that burns much at all these days. Maybe he was just smoldering a little at both ends.
At any rate, because he didn't get everything finished last night, he got to get up early and head in for work at 5:30 in the morning. You know what's the best thing about going to work at 5:30 in the morning? That's right: absolutely nothing. But, then again, the author of today's haiku would probably say the same thing about going to work at 8:30 in the morning, 11:30 in the morning, 2:30 in the afternoon, etc., etc.
Speaking of today's haiku, and recognizing that the author of said haiku needs to get that haiku done so he can actually go to TechReady, today we're going to talk about the New-CsWebTrustedCACertificate cmdlet, the cmdlet voted Sexiest Cmdlet of 2011 by the editors of People magazine.
Note. Really? Beats us; to be honest, we don't read People all that often. But it probably would be voted Sexiest Cmdlet of 2011 by the editors of People magazine if the editors of People magazine actually voted on things like that. But they probably have a lot of other things to do.
So what exactly is the New-CsWebTrustedCACertificate cmdlet, and what makes it so sexy? Well, each Web Server employed by Microsoft Lync Server 2010 has a property named TrustedCACerts. This property represents a collection of all the certification authorities trusted by Microsoft Lync 2010 Phone Edition: if you've obtained a certificate from one of these certification authorities then your Lync Phone Edition phone is able to make a secure connection to Lync Server. So how do you let Lync Server know that you have a new trusted certification authority (CA)? That's easy. First, you add the certificate chain for that CA to the local computer’s certificate store. After you have verified that the certificate chain has been installed, you then use – tah-dah! – the New-CsWebTrustedCACertificate cmdlet to create a certificate ID object that can be added to a collection of Web Services configuration settings.
In other words, you run a pair of commands similar to these:
$x = New-CsWebTrustedCACertificate -Thumbprint "D543DFF74FEEA425162FD25F342786F1AB453BB3" -CAStore TrustedRootCA
Set-CsWebServiceConfiguration -Identity site:Redmond -TrustedCACerts @{Add=$x}
As you can see, in the first command we call the New-CsWebTrustedCACertificate cmdlet followed by the certificate's thumbprint and its location in the certificate store. (The CAStore can be set to TrustedRootCA, IntermediateCA, or ThirdPartyCA.) As for the thumbprint of the certificate, we recognize that there's an off-chance that you haven't memorized the thumbprints of all your certificates. (Should you have memorized the thumbprints of all your certificates? Well, that's obviously another story.) But that's fine; after all, you can retrieve information (including the thumbprint value) for all your Lync Server certificates simply by running this command:
Get-CsCertificate
Note that, when you call New-CsWebTrustedCACertificate, you need to store the result object in a variable (in this case $x); if you don't, that new trusted CA certificate will disappear just as fast as it gets created. After you've stashed the certificate information in a variable, you can then use command number 2, and the Set-CsWebServiceConfiguration cmdlet, to add the certificate to the specified Web server:
Set-CsWebServiceConfiguration -Identity site:Redmond -TrustedCACerts @{Add=$x}
So what if you change your mind and want to get rid of a trusted CA certificate? Well, there are a couple of ways to do that. Suppose you just want to replace the existing certificate with a new one. That's fine; just repeat the process we showed you a moment ago, but this time use the Replace method instead of the Add method:
$x = New-CsWebTrustedCACertificate -Thumbprint "ZRTEDFFHJT5414251OP9876F342ABGGG6B4P981HZ" -CAStore TrustedRootCA
Set-CsWebServiceConfiguration -Identity site:Redmond -TrustedCACerts @{Replace=$x}
If you want to get rid of all the trusted CA certificates assigned to a Web Server, well, that's even easier: just set the TrustedCACerts property to a null value. You know, like this:
Set-CsWebServiceConfiguration -Identity site:Redmond -TrustedCACerts $Null
Things get a tiny bit tricky if you have multiple certificates stashed in the TrustedCACerts property and want to get rid of just one of those certificates. That doesn't mean it can't be done. Like we said, it's just a tiny bit tricky.
Ah, good point: maybe we should explain what we mean by that. Well, individual certificates are stored in the TrustedCACerts property as an array. For example, if you expand the value of that property you'll see output similar to this:
Thumbprint : D543DFF74FEEA425162FD25F342786F1AB453BB3
CA Store : TrustedRootCA
Thumbprint : ZRTEDFFHJT5414251OP9876F342ABGGG6B4P981HZ
CA Store : TrustedRootCA
Note. How do you "expand" a property value? Like this:
Get-CsWebServiceConfiguration –Identity site:Redmond | Select-Object –ExpandProperty TrustedCACerts
As you can see, we have two certificates here. The first one (D543DFF74FEEA425162FD25F342786F1AB453BB3) has an index number of 0. Why? Because it's the first item in our array, and the first item in an array always has the index number 0. (Well, in Windows PowerShell anyway.) The second item (ZRTEDFFHJT5414251OP9876F342ABGGG6B4P981HZ) has the index number 1, which is the index number the second item in an array always has. Suppose we want to delete that second item, and only that second item. Here's how we can do that:
$x = Get-CsWebServiceConfiguration –Identity site:Redmond
$x.TrustedCACerts.RemoveAt(1)
Set-CsWebServiceConfiguration –Instance $x
See what we did there? We used the Get-CsWebServiceConfiguration cmdlet to retrieve our Web service settings, storing the returned object in a variable named $x. (Hey, we had to get up at 5:00 this morning. We can't come up with a more creative variable name than $x.) After we've done that, we next use the RemoveAt method to remove the second item in the array (the item with the index number of 1). That changes our Web service settings in memory, but doesn't actually write those changes back to Lync Server. As you might have guessed, that's what command number three is for.
And that, as they say, is that. As we said, the author of today's haiku is getting ready to head off to TechReady, but don't worry: he'll take careful and copious notes, and report back on anything interesting that might take place.
Unless, of course, he ends up sleeping through the entire presentation. But, then again, if he has to do much talking, he probably won't be the only one.
See you tomorrow.