Teams PowerShell Module - Certificate Authentication

There are several ways to get the Teams PowerShell module to authenticate against Azure in order to get access to running Teams PowerShell in your Tenancy. Most people will be used to using the interactive method, where you just run the basic Connect-MicrosoftTeams command and get an interactive Azure auth screen that pops up and you enter your user account details into. This is fine if you are manually connecting and doing this by hand. However, what if you want to run an Azure Function that needs to authenticate automatically each time it executes? Well, for that you want to use an application authentication method.

Currently as of the module version 4.9.1, Microsoft officially supports two methods for application authentication when connecting to the Teams PowerShell module:

• Certificate based authentication – In this method you have a certificate with private and public keys. The PC connecting to Azure needs to have a copy of the private key and Azure needs to have a stored copy of the public key. As part of the connection the private key will be used to sign the connection and if Azure can decrypt the information with the public key then the PC is trusted to connect. This essentially makes the private key like a password that you need to ensure that no one else has access to.
• Token based authentication – The token-based method requires that you set up a Client Secret in Azure. When you connect to Azure using the PowerShell module, you authenticate against the Token Service using the Client Secret and get Tokens back that you can use to connect to the service. In the case of the Teams module, you need to get two tokens to be able to run all the commands. You can find out more about this option here: Token Auth Post

In this post we are going to focus on the certificate-based authentication method. Here are the steps for setting up and connecting using certificate-based authentication:

 

Step 1: Generate a Certificate:

The good news here is that the certificate you need does not need to be signed by an internet-based Certificate Authority. You can simply create a self-signed certificate on a PC and use this for connection. Below is a PowerShell command you can run (you must run the PowerShell window as Administrator to execute it). The most important flag in the command is the KeySpec flag which tells it to generate a certificate that can be used for Key Exchange.

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -Subject TeamsAppTestCertificate01 -KeySpec KeyExchange

 

Step 2: Export the Certificate:

In order to export the certificate you can either run PowerShell or do it by hand with the Certificate Snap-in. Both options will be detailed below. Choose the one that you’re most comfortable with.

Export the Private Key (This step is only needed if you want to run PowerShell from a different machine that you have created the certificate on, for example, a Function App, etc):

PowerShell:

$password = ConvertTo-SecureString -String "SpecialPassword123!" -Force –AsPlainText

Export-PfxCertificate -Cert "cert:\LocalMachine\My\8E4CKSHDUSG873F66D99AC7935F53" -FilePath "C:\temp\AuthPrivateKey.pfx" -Password $password

Note: The thumbprint to be used here will be output from the New-SelfSignedCertificate command you previously ran.

 

Or Windows UI:

Once again, this is is only needed if you want to run PowerShell from a different machine that you have created the certificate on, for example, a Function App, etc.

Search PC for mmc.exe > File Menu > Add or Remove Snap-in > Certificates > Add > Computer Account > Personal > Certificates Folder > Right Click on the Certificate > Export…

Export Certificate Wizard:

Click Next...

Select: "Yes, export the private key":

Go with the default export options:

Enter a password for the PFX file and ensure that you select TripleDES-SHA1 (I have found that importing on some platforms is not supported with AES):

Enter a name and location for the pfx file to be output to:

Export the Public Key (to be uploaded to the App Registration in Azure)

PowerShell:

Export-Certificate -Cert "Cert:\LocalMachine\My\8E4CKSHDUSG873F66D99AC7935F53" -FilePath "C:\temp\AuthPublicKey.cer"

Or Windows UI:

Click Next... 

Do not export private key:

Select the format of the file (DER is okay in this case) and click next:

Select the name of the file and click next:

Step 3: Configure the App Registration:

Open the Azure AD Portal and select the Azure Active Directory > App Registration section:

 Click the "New Registration" Button:

 

Fill in a name for the application and click the Register button:

The App Registration will now be created, however, there is still more config to do:

Go to the “Certificates & secrets” blade:

Select the location of the public key certificate that you exported earlier. Add a description and click OK:

The certificate should now show up in the certificates area:

Now open the API Permissions tab within the App Registration, Click "Add a permission":

You will need to add the following Graph API permissions to the App Registration:

User.Read.All

Group.ReadWrite.All

AppCatalog.ReadWrite.All

TeamSettings.ReadWrite.All

Channel.Delete.All

ChannelSettings.ReadWrite.All

ChannelMember.ReadWrite.All

These permissions are documented by Microsoft here, so you may want to check to see if there have been any updates for the PowerShell version you're using: https://learn.microsoft.com/en-us/microsoftteams/teams-powershell-application-authentication

Click the "Microsoft Graph" option:

Select "Application Permissions":

Select the permissions that were listed above:

Ensure that you have added all the permissions. If you missed any then repeat the above steps for all the permissions in the list…

 

After adding all the permissions, you need to click the “Grant admin consent for <tenant id>” button on the main Permissions screen:

At the end of this procedure, you should have the following permissions all assigned with admin consent granted:

In a final twist in this adventure, you also need to make sure you assign Teams Administrator privileges to the App Registration in order for it to be able to run CS commands. You do this by going to the Active Directory tab > Roles and Administrators > Teams Administrator Role:

 

Assign the Service Permission that is named the same as your App Registration to the RBAC Role:

Connecting To Teams PowerShell

 

Now that all the backend work has been done we can get down to doing some connecting. When you connect it needs to be from a machine that has access to the certificate. On a PC this means it has to be in the certificate store. If it’s from a machine in Azure there are various methods for doing this too (which I may well get to in another post…).

You will need to know the ApplicationId that was given to the App Registration in Azure. You can find this out by looking going to the Overview tab and looking for the GUID that has the title “Application (client) ID”. The TenantId is the base domain name that was first given to your tenancy when it was created or alternatively can be the GUID that’s in the Overview tab named as “Directory (tenant) ID” (both options will work).

 

Teams Module Connect Command:

Connect-MicrosoftTeams -CertificateThumbprint "3ab0e057bc3278ecb2a33123042e5a7a8001ff8c" -ApplicationId "319d0a47-9a48-45b0-b416-14aca00e7ece" -TenantId contoso.onmicrosoft.com

 

When connection is successful, you’ll get back an object displayed in the PowerShell window that tells you the Account, Environment, Tenant and TenantId values. From here you should be able to run almost all of the commands from the module, with the following exclusions:

As of 4.9.1; All cmdlets are supported now, except for the cmdlets mentioned below:

• New-Team
• [Get|Set|New|Sync]-CsOnlineApplicationInstance
• *-CsUserCallingSettings
• *-CsUserCallingDelegate
• *PolicyPackage*
• *-CsTeamsShiftsConnection*
• *-CsBatchTeamsDeployment*

  

The Wrap Up

 

Congratulations, you’re now an expert at certificate-based authentication with the Teams PowerShell module. If you are interested in Token Based Authentication using the Teams Module, then you can check out my post on that over here: Token Auth Post.

Read more →

Skype4B / Lync Certificate Checker Tool

If you’ve ever installed Skype for Business or Lync before, you will know that the system requires PKI Infrastructure and Certificates to function. The reason for this is that all SIP and Web communications within the Skype for Business environment is secure by design and uses certificates for encrypting data. These communications span between servers, clients, phones, PSTN Gateways, Third Party Video equipment and most other integrations you can think of. So without your certificates being deployed properly, you are going to have a lot of trouble getting your environment up and running.

Skype for Business/Lync Edge servers communicate with each other over Mutual Transport Layer Security (MTLS). When using MTLS connections the server originating a message and the server receiving it exchange certificates from mutually trusted Certificate Authorities. The public certificates presented in either direction prove the identity of each server by being signed by a trusted certificate authority. The main thing here to note here is that both servers need to have root certificates installed from each other’s trusted root certificate authority in order for TLS connections to negotiate successfully. This is also the case for federated connections to other organisations via the Skype for Business Edge server. These connections all rely on MTLS for the successful communication between the servers.

Encryption Used in Skype for Business

Traffic type	Protected by
Server-to-server	MTLS
Client-to-server	TLS
Instant messaging and presence	TLS
Audio and video and desktop sharing of media	SRTP (No Certificates Used)
Desktop sharing (signaling)	TLS
Web conferencing	TLS
Meeting content download, address book download, distribution group expansion	HTTPS
Mobile Clients (UCWA)	TLS

In many cases you may not have direct access to the other system you are connecting to in order to check whether the certificate it is using is valid, or has been signed by a trusted root certificate Authority. As a result, you may have issues connecting to the server and need to use complex tools like Wireshark to determine what the certificate being presented by the far end looks like. This can take time and involve installing software on servers, so I wanted to create a simple tool that doesn’t require any installation and can be run straight from a Powershell prompt. After doing some coding, that’s exactly what I created, introducing the Skype for Business Certificate Checker Tool…

Skype4B / Lync Certificate Checker Tool

Features:

• Check the certificate being used by a server using the FQDN/IP and Port number of the server.
• Check the certificate of a Federation SRV record (_sipfederationtls._tcp.domain.com) simply by entering the SIP domain name and ticking the “FED SRV” checkbox.
• Check the SIP SRV record (_sip._tls.domain.com) by simply entering the SIP domain name and ticking the “SIP SRV” checkbox.
• Check the SIP Internal SRV record (_sipinternaltls._tcp.domain.com) by simply entering the SIP domain name and ticking the “SIP INT SRV” checkbox.
• Select the DNS server you would like to use to resolve DNS from by entering a DNS Server IP address in the “DNS Server” field.
• “Show Advanced” checkbox will show all of the information in the certificate.
• The “Show Root Chain” will display the root certificate and all of the intermediate certificates that are applicable in the trust chain for the certificate.
• The “Test DNSLB Pool” checkbox is on by default and will instruct to the tool to test all of the IP Addresses that are resolved for a DNS Name. In the case of Skype for Business, we nearly always have multiple DNS records per A record for the purposes of DNS load balancing.  Rather than having to look all of the servers yourself, the tool will do this for you. Other servers in pool will be displayed in the Information text box in blue colour and will be tested directly via their IP Address rather than the DNS name.
• Import multiple DNS name records from a CSV file. This is useful if you want to check a lot of servers in one sitting. See the “Import File Format” section for more details.
• Save certificate information out to a CSV file. This will save all of the certificate information out in table format that you can open in Excel for record keeping purposes. Note: This export format is different than the one used in conjunction with the “Import” button.
• Comments section – The comments section will have information in it about things that may be wrong with the certificate to help you troubleshoot your issues.

DOWNLOAD HERE

Import File Format

You can import a CSV file containing many domains and servers to test if you choose (for example, this may be useful for checking a large list of federated domains). To do this you will first need to create a CSV file with all of the servers and/or domains that you want to test in it. The format of the CSV for each of the record types will look like:

·        

Header row: Domain,Type,Port

Example Federation Record: "microsoft.com","FED","",

Example SIP Record: "microsoft.com","SIP","",
Example SIP Record: "microsoft.com","SIPINT","",

Example direct Record: "sip.microsoft.com","DIR","5061",

Example file:

Domain,Type,Port

"microsoft.com","FED","",

"microsoft.com","SIP","",
"microsoft.com","SIPINT","",

"sip.microsoft.com","DIR","5061"

The Anatomy of a Certificate

The Certificate Checker Tool can display a few different levels of information about the certificate presented by the server. The default basic view of the certificate will be displayed in the tool as follows:

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Checking FQDN:  sipfed.microsoft.com:5061 Checking IP Address: 167.220.67.163:5061 Certificate Response: Subject: CN=sipfed.microsoft.com, OU=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=WA, C=US Issuer: CN=Microsoft IT SSL SHA2, OU=Microsoft IT, O=Microsoft Corporation, L=Redmond, S=Washington, C=US Not Before: 30/04/2015 2:26:22 PM Not After: 29/04/2017 2:26:22 PM Serial Number: 5A0000F5B0C7CABB89E4624D1E00010000F5B0 Signature Algorithm: sha256RSA Thumbprint: 9E1736ACA8C9731798E7FD3496E7D78454A02E80 Version: 3 HasPrivateKey: False ---------------------------------------------------------------------------------- Comments: - Common Name Match found - FQDN is in SAN list. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

For a Skype for Business or Lync deployment the most important components here are the Subject name, the Not Before and Not After dates. The “Comments” section is provided by the tool to help you troubleshoot issues with the certificate being displayed. This section will automatically check things like the certificate being out of date, the common name/subject alternate names being correct, if there is a Server EKU, and if the certificate has a CLR list included. These comments should help speed up your troubleshooting of certificate issues. Note: the comments will actually be based on all the advanced certificate details, even though the Advanced checkbox is not ticked by default.

Advanced Settings

All certificate details are displayed when the “Advanced” check box is ticked. When you tick this check box and run the tool you will see information as shown below:

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Checking FQDN:  sipfed.microsoft.com:5061 Checking IP Address: 167.220.67.163:5061 Certificate Response: Subject: CN=sipfed.microsoft.com, OU=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=WA, C=US Issuer: CN=Microsoft IT SSL SHA2, OU=Microsoft IT, O=Microsoft Corporation, L=Redmond, S=Washington, C=US Not Before: 30/04/2015 2:26:22 PM Not After: 29/04/2017 2:26:22 PM Serial Number: 5A0000F5B0C7CABB89E4624D1E00010000F5B0 Signature Algorithm: sha256RSA Thumbprint: 9E1736ACA8C9731798E7FD3496E7D78454A02E80 Version: 3 HasPrivateKey: False Archived: False Extension Type: Certificate Policies Oid Value: 2.5.29.32 Data: [1]Certificate Policy:      Policy Identifier=1.3.6.1.4.1.311.42.1      [1,1]Policy Qualifier Info:           Policy Qualifier Id=CPS           Qualifier:                http://www.microsoft.com/pki/mscorp/cps Extension Type: Application Policies Oid Value: 1.3.6.1.4.1.311.21.10 Data: [1]Application Certificate Policy:      Policy Identifier=Server Authentication [2]Application Certificate Policy:      Policy Identifier=Client Authentication Extension Type: Key Usage Oid Value: 2.5.29.15 Data: Digital Signature, Key Encipherment, Data Encipherment (b0) Extension Type: Enhanced Key Usage Oid Value: 2.5.29.37 Data: Server Authentication (1.3.6.1.5.5.7.3.1) Client Authentication (1.3.6.1.5.5.7.3.2) Extension Type: Subject Key Identifier Oid Value: 2.5.29.14 Data: df 62 d3 a8 ef 49 3d 2f ed 10 aa 6a 30 3a 6f f9 54 1b 33 39 Extension Type: Authority Key Identifier Oid Value: 2.5.29.35 Data: KeyID=51 af 24 26 9c f4 68 22 57 80 26 2b 3b 46 62 15 7b 1e cc a5 Extension Type: CRL Distribution Points Oid Value: 2.5.29.31 Data: [1]CRL Distribution Point      Distribution Point Name:           Full Name:                URL=http://mscrl.microsoft.com/pki/mscorp/crl/msitwww2.crl                URL=http://crl.microsoft.com/pki/mscorp/crl/msitwww2.crl Extension Type: Authority Information Access Oid Value: 1.3.6.1.5.5.7.1.1 Data: [1]Authority Info Access      Access Method=Certification Authority Issuer (1.3.6.1.5.5.7.48.2)      Alternative Name:           URL=http://www.microsoft.com/pki/mscorp/msitwww2.crt [2]Authority Info Access      Access Method=On-line Certificate Status Protocol (1.3.6.1.5.5.7.48.1)      Alternative Name:           URL=http://ocsp.msocsp.com Extension Type: Subject Alternative Name Oid Value: 2.5.29.17 Data: DNS Name=sipfed.microsoft.com DNS Name=sipalt.microsoft.com DNS Name=sip.microsoft.com DNS Name=ra30.sbweb.microsoft.com DNS Name=web3.sbweb.microsoft.com DNS Name=web30.sbweb.microsoft.com DNS Name=web31.sbweb.microsoft.com ---------------------------------------------------------------------------------- Comments: - Common Name Match found - FQDN is in SAN list. ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

You will have a full view of all attributes contained within the certificate. Using this information you should be able to troubleshoot most certificate related issues. However, there is one more important piece of information that you might need and that is the certificate chain…

The Certificate Chain

The certificate chain is the hierarchy of Certificate Authority servers from the CA server that issued the certificate through the Intermediate Certificate Authorities to the Root Certificate Authority server. The tool will display the certificate chain as follows:

Certificate Chain: Certificate Chain Item 1 Chain Subject Name: CN=sipfed.microsoft.com, OU=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=WA, C=US Chain Issuer name: CN=Microsoft IT SSL SHA2, OU=Microsoft IT, O=Microsoft Corporation, L=Redmond, S=Washington, C=US Chain Not Before: 11/12/2015 05:36:48 Chain Not After: 11/11/2017 05:36:48 Chain Serial Number: 5A000233C22F738FDBCE9CF8B50001000233C2 Chain Signature Algorithm: sha256RSA Chain Thumbprint: A710B806065C2187E387635A9F8D7863A63D702A Chain Version: 3 Chain is valid: True Certificate Chain Item 2 Chain Subject Name: CN=Microsoft IT SSL SHA2, OU=Microsoft IT, O=Microsoft Corporation, L=Redmond, S=Washington, C=US Chain Issuer name: CN=Baltimore CyberTrust Root, OU=CyberTrust, O=Baltimore, C=IE Chain Not Before: 05/08/2014 03:04:09 Chain Not After: 05/08/2018 03:03:30 Chain Serial Number: 0727AA47 Chain Signature Algorithm: sha256RSA Chain Thumbprint: 97EFF3028677894BDD4F9AC53F789BEE5DF4AD86 Chain Version: 3 Chain is valid: True Certificate Chain Item 3 Chain Subject Name: CN=Baltimore CyberTrust Root, OU=CyberTrust, O=Baltimore, C=IE Chain Issuer name: CN=Baltimore CyberTrust Root, OU=CyberTrust, O=Baltimore, C=IE Chain Not Before: 05/13/2000 04:46:00 Chain Not After: 05/13/2025 09:59:00 Chain Serial Number: 020000B9 Chain Signature Algorithm: sha1RSA Chain Thumbprint: D4DE20D05E66FC53FE1A50882C78DB2852CAE474 Chain Version: 3 Chain is valid: True ---------------------------------------------------------------------------------- Root Certificates: - Get Root Certs here: http://cybertrust.omniroot.com/support/sureserver/rootcert_iis.cfm - Download Root Cert: http://cacert.omniroot.com/bc2025.crt ----------------------------------------------------------------------------------

The tool will show you the Subject Name, Issuer Name (which will be the next server in the list/chain), Element Signature Algorithm (can be important, see below), and whether or not the chain is valid.

In addition to displaying the certificate chain the tool will also, where possible, provide a link to a copy of the root certificate for the root CA being used. The tool knows about the major certificate authorities supported by Microsoft for use with Skype for Business and in most cases will give you a direct link to the root certificate for download.

Root Certificates

One very important thing when configuring external federation with partners or public providers is that MTLS is used for these connections. This means that both ends of the connection need to trust the other’s root certificates. You need to ensure that your edge servers have the root certificates of your partners installed. Fortunately, the Cert Checker Tool has you covered here by showing you where you can download the root certificates for common public certificate authorities. This will appear like shown below:

- Get Root Certs here: http://cybertrust.omniroot.com/support/sureserver/rootcert_iis.cfm - Download Root Cert: http://cacert.omniroot.com/bc2025.crt

Before you configure a new partner for federation, you can you use the tool to check what certificate authority they are using for their certificates and as a result which root certificates you need installed on your edge servers.

There is also neat trick you can do to automagically install root certificates on a Windows server or PC (post Windows Vista). Note there is a caveat with this process whereby the third party server must be using a Root Certificate Authority that is trusted by Microsoft as part of their Trusted Root Certificate Program (Microsoft supported root CAs can be confirmed on this list). If this is the case then you just need to browse to a web server that is signed by the root certificate authority of choice and Windows will automatically install the root certificate for you! These root certificates are pushed to Window through Windows Update and will be installed only when you try to connect to a website requiring a particular certificate. So connecting to a federated partner's "dialin.domain.com" web page from all of your Edge servers may be enough to download the root certificates for MTLS trust purposes. There is a lot of documentation about this process on TechNet if you would like to know more. A few Skype for Business community have also written about this phenomenon - Chris and Pat.

The Wrap Up

I hope that this new tool finds you well, and I hope that you have many long years of troubleshooting together. Remember, whilst the flame may flicker from time to time, you must stay strong and think fondly of those times in the early days when you hired the car, threw the work laptop in the boot, and drove to the cabin in the woods; not even one bar of 3G internet access could stop you from fixing that server certificate problem. It’s the memory of those times that will keep you on the straight and narrow when that younger and fancier tool with the sexy universal windows app GUI comes along. Your Powershell Certificate Checker will always be faithful, remember that… now get testing!

Read more →