TeamViewer 13 customers can request early access to the Identity Provider Connection feature. 

The TeamViewer Identity Provider Connection aims to reduce the user management effort for large enterprises by connecting TeamViewer with identity providers and Active Directories.

IMPORTANT NOTE: Identity Provider Connection is currently in an early access phase. Some functionality might be missing and, while we are testing all functionality before releasing it, some bugs might occur. Therefore we do not recommend to use Identity Provider Connection a in productive environment during the early access phase.

Requirements

To use TeamViewer Identity Provider Connection, you need

  • to request early access to the Identity Provider Connection feature. Request here.
  • a TeamViewer version 13.1.1548 or newer
  • a SAML 2.0 compatible identity provider (IdP)
  • a TeamViewer account to access the Management Console and add domains
  • access to the DNS management of your domain to verify the domain ownership.

Note: ADFS 3.0, Azure and Okta have been tested and detailed steps to set up one of these IdP can be found in this document.

Note: If you use a different IdP, please use the Technical Information to set up your IdP manually.

Hint: When adding a domain, use a TeamViewer account which does not belong to the domain. The reason for this is a fallback scenario that you keep the access to the domain configuration even if the IdP is not working. Example: Domain „example.com“ is supposed to be added to activate the IdPC for this domain. The TeamViewer account adding this domain should not end on @example.com but on @configure-test.com.

TeamViewer Setup

TeamViewer is compatible to Identity Provider Connection starting from version 13.1.1548.

Previous versions do not support Identity Provider Connection and can not redirect users to your identity provider during the login.

During the Beta phase, the TeamViewer client has disabled Identity Provider Connection by default to not interrupt the workflows of users that are not supposed to test Identity Provider Connection.

Identity Provider Connection is enabled for the TeamViewer client by creating following registry key:

HKEY_CURRENT_USER\Software\TeamViewer\IdPCBetaEnabled = 1 (DWORD)

The TeamViewer client will use an embedded browser for the identity provider authentication by default. If you would prefer to use the system default browser, you can change this behavior with the following registry key:

HKEY_CURRENT_USER\Software\TeamViewer\SsoUseEmbeddedBrowser = 0 (DWORD)

Note: You need to restart the TeamViewer client after creating or changing the registry keys.

Setup using...

...ADFS

The following steps describe the setup procedure for ADFS. Directions and commands have been taken from a machine running Windows Server 2016 Standard (Version 1607).

The configuration basically consists of the following two steps:

  1. Add an ADFS Relying Party Trust for the TeamViewer Single Sign-On service. This step requires metadata of the TeamViewer SSO service to be entered. This can be done in one of the following ways:
    • Automatic: This only requires entering a URL to the metadata XML file. The file gets downloaded by ADFS and all required fields of the relying party trust are filled-out automatically. It requires the ADFS server to have access to the internet.
    • Semi-Automatic: Like the automatic method but instead of providing a URL to the metadata, the file itself is downloaded beforehand and given to ADFS as XML file. This can be useful if the ADFS server does not have internet access.
    • Manual: If none of the above methods are applicable, the metadata can be entered manually to ADFS.
  2. Add a transformation rule to the claim issuance policy of the new relying party trust.

The following sections describe the configuration for all three scenarios using the PowerShell command prompt and the ADFS Management graphical user interface:

Automatic Configuration using PowerShell

Open a new PowerShell command window and enter the following commands to add a new relying party trust with a default claim issuance policy to ADFS:

$customerId = 'Your Generated Customer Identifier'
$claimRules = @'
@RuleTemplate = "LdapClaims"
@RuleName = "TeamViewer Login"
c:[Type ==
"http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types =
("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query =
";objectGUID,mail;{0}", param = c.Value);
@RuleName = "TeamViewer Customer ID"
=> issue(Type = "http://sso.teamviewer.com/saml/claims/customeridentifier",
Value = "
'@ + $customerId + '");'
Add-AdfsRelyingPartyTrust `
-Name TeamViewer `
-MetadataUrl https://sso.teamviewer.com/saml/metadata.xml `
-IssuanceTransformRules $claimRules `
-AccessControlPolicyName "Permit everyone" `
-AutoUpdateEnabled $true `
-MonitoringEnabled $true `
-Enabled $true

Adapt the "-Name" parameter value to your needs. This is the name displayed in the ADFS graphical user interface. Also, the name of the access control policy may differ on your system. All the settings can be changed later via PowerShell or the ADFS graphical user interface.

Semi-Automatic Configuration using PowerShell

This is very similar to the "automatic" method described above. It requires to download the metadata XML file beforehand and to copy it to the ADFS server. The metadata file can be downloaded from the following URL:

https://sso.teamviewer.com/saml/metadata.xml

The following commands assume that the metadata XML file is available in the current directory of the PowerShell command prompt as "metadata.xml".

$customerId = 'Your Generated Customer Identifier'
$claimRules = @'
@RuleTemplate = "LdapClaims"
@RuleName = "TeamViewer Login"
c:[Type ==
"http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types =
("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query =
";objectGUID,mail;{0}", param = c.Value);
@RuleName = "TeamViewer Customer ID"
=> issue(Type = "http://sso.teamviewer.com/saml/claims/customeridentifier",
Value = "
'@ + $customerId + '");'
Add-AdfsRelyingPartyTrust `
-Name TeamViewer `
-MetadataFile metadata.xml `
-IssuanceTransformRules $claimRules `
-AccessControlPolicyName "Permit everyone" `
-Enabled $true

The main difference to the "automatic" method is the use of the "-MetadataFile" parameter (instead of "-MetadataUrl"). The "-AutoUpdateEnabled" and "-MonitoringEnabled" parameters have been omitted as both require a valid metadata URL to be given.

Manual Configuration using Powershell

The manual configuration requires to download and extract the public key of the signature/encryption certificate of the TeamViewer SAML Service Provider. Please find more information at the Technical Information section.

Execute the following commands in a PowerShell command prompt to manually add a relying party trust:

$customerId = 'Your Generated Customer Identifier'
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(".\sso.teamviewer.com - saml.cer", "")
$claimRules = @'
@RuleTemplate = "LdapClaims"
@RuleName = "TeamViewer Login"
c:[Type ==
"http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types =
("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query =
";objectGUID,mail;{0}", param = c.Value);
@RuleName = "TeamViewer Customer ID"
=> issue(Type = "http://sso.teamviewer.com/saml/claims/customeridentifier",
Value = "
'@ + $customerId + '");'
$samlEndpoints = @(
(New-AdfsSamlEndpoint -Binding POST -Protocol SAMLAssertionConsumer -Uri https://sso.teamviewer.com/saml/acs -Index 0),
(New-AdfsSamlEndpoint -Binding Redirect -Protocol SAMLAssertionConsumer -Uri https://sso.teamviewer.com/saml/acs -Index 1)
)
Add-AdfsRelyingPartyTrust `
-Name "TeamViewer" `
-Identifier "https://sso.teamviewer.com/saml/metadata" `
-RequestSigningCertificate $cert `
-EncryptionCertificate $cert `
-SamlEndpoint $samlEndpoints `
-IssuanceTransformRules $claimRules `
-AccessControlPolicyName "Permit everyone" `
-Enabled $true

Please also have a look at the official documentation of the "Add-AdfsRelyingPartyTrust" PowerShell commandlet: https://technet.microsoft.com/en-us/library/ee892322.aspx

(Semi-)Automatic Configuration using ADFS Management Tools (graphical)

  1. Start the ADFS Management tools from the Server Manager.
  2. Navigate to ADFS --> Relying Party Trusts and click on Add Relying Party Trust... in the navigation pane on the right
  3. Select Claims aware and start the wizard by clicking the Start button
  4. Depending on whether you want to have the automatic"or semi-automatic variant, select to import the metadata via URL (first bullet point)
  5. Choose a name for the relying party trust, like TeamViewer or sso.teamviewer.com or choose the pre-filled name if applicable
  6. Select the access control policy for the relying party trust. E.g. choose permit everyone
  7. Click Next on the summary screen to add the relying party trust

Next, the claim issuance policy needs to be configured for the new relying party trust.

  1. Select the relying party trust and click "Edit Claim Issuance Policy..." in the navigation pane on the right.
  2. Click Add Rule and choose Send LDAP Attributes as Claims
  3. Enter a name for the transformation rule, e.g. TeamViewer Login
  4. Select Active Directory as Attribute store.
  5. Add the following two mappings and end the process by clicking Finish afterwards:
LDAP Attribute Outgoing Claim Type Remarks
objectGUID Name ID

Enter the value of the LDAP Attribute field manually.

You may need to click on the dropdown arrow first, before starting to type.

E-Mail-Addresses

E-Mail Address

 

 

Manual Configuration using ADFS Management Tools (graphical)

The manual configuration requires to download and extract the public key of the signature/encryption certificate of the TeamViewer SAML Service Provider.

Please see the Technical Information section below on how to get the certificate.

  1. Start the ADFS Management tools from the Server Manager
  2. Navigate to ADFS - Relying Party Trusts and click on Add Relying Party Trust... in the navigation pane on the right
  3. Select Claims aware and start the wizard by clicking the Start button
  4. Select to enter the data manually (third bullet point)
  5. Choose a name for the relying party trust, like TeamViewer or sso.teamviewer.com or choose the pre-filled name if applicable
  6. Browse to the certificate file (see comment above)
  7. Check the box for Enable support for the SAML 2.0 WebSSO protocol and enter the following service URL: https://sso.teamviewer.com/saml/acs
  8. On the Configure Identifiers page, add https://sso.teamviewer.com/saml/metadata as identifier
  9. Confirm adding the relying party trust.
  10. Configure the claim issuance policy as described for the Automatic procedure above.
  11. Next, configure the signature certificate of the relying party trust. Therefore open the properties (double-click) and navigate to the Signature tab. Browse to the same certificate file as mentioned above
  12. Optionally, add a second SAML endpoint to the relying party trust. Navigate to the Endpoints tab and click Add SAML endpoint

...Azure

To connect TeamViewer with Azure Active Directory as identity provider, it is required to create an application for your Azure AD. The steps to create and configure an enterprise application are described below.

Creating the application

Please follow the instructions from the Microsoft Azure AD documentation to create an Azure AD application for TeamViewer: https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-custom-apps and configure the application for SAML based Sign-On.

Use these values to configure SAML:

Field Value
Issuer URL / Identifier https://sso.teamviewer.com/saml/metadata
Reply URL

https://sso.teamviewer.com/saml/acs

 

Please leave the fields Sign on URL and Relay State empty.

Now please and make sure that the claims issued in the SAML token are configured correctly and don’t forget to assign users and groups to the new application.

TeamViewer requires the SAML claims nameidentifier and emailaddress:

The User Identifier (= nameidentifier) should be a unique identifier of the user. The default setting is usually fine.

The claim emailaddress must return the email address of the user. 

Please note that the email address of the Azure AD user must match with the email ad-dress of the corresponding TeamViewer account.

A generated customer identifier is required to be given in the claim `http://sso.teamviewer.com/saml/claims/customeridentifier’.

The last step is to configure TeamViewer to work with Azure AD.

The easiest way is to download the metadata XML from Azure and upload the file in the TeamViewer Management Console. Please refer to the section Domain Management in MCO.

...Okta

This section describes how to set-up Okta to be used as IdP for the TeamViewer IdPC service. It is recommended to use the automatic configuration via the Okta certified TeamViewer app.

Hint: You need to assign users to the application in Okta, depending on your settings.

Automatic configuration using the TeamViewer Okta app

  1. Login to your Okta Administrator Dashboard
  2. Add the TeamViewer application
  3. Select SAML 2.0
    • Copy and save your metadata URL
  4. Assign users to the application
  5. Activate SAML using your metadata in the Domain Management in MCO

Manual Configuration using the Okta Web User Interface

Go to the administration interface and add a new SAML application. Specify the following values on the SAML Settings page:

Settings  Value
Single sign on URL

https://sso.teamviewer.com/saml/acs

Use this for Recipient URL and Destination URL
Allow this app to request other SSO URLs

Audience URI (SP Entity ID) https://sso.teamviewer.com/saml/metadata
Default RelayState  
Name ID Format

EmailAddress

Application username Email

 

Advanced settings  Value
Response Signed
Assertion Signature Signed
Signature Algorithm

RSA-SHA256

Digest Algorithm

SHA256

Assertion Encryption

Encrypted

Encryption Algorithm

AES256-CBC

Key Transport Algorithm

RSA-OAEP

Encryption Certificate

Upload the public key of the TeamViewer SAML Service Provider.
Please refer to Technical Information for information how to get the certificate.

Enable Single Logout

No

 

Add the following attribute statements:

Name Name Format Value
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress Unspecified

user.email

http://sso.teamviewer.com/saml/claims/customeridentifier Unspecified

Your Generated Customer ID

 

Please note that the value of the emailaddress attribute statement may include more complex mapping rules. Okta therefore provides you with an expression language (see the official documentation about it: https://developer.okta.com/reference/okta_expression_language/index).

An example for a more complex mapping:

Company A has reserved two email address domains for its users - @a1.test and @a2.test. The Okta users have the @a1.test domain associated to their account.

TeamViewer SSO should be enabled for the @a2.test email addresses only.

The value for the emailaddress statement could look like the following:

String.append(String.substringBefore(user.email, "@"), "@a2.test")


This causes the SAML response to include the correct email address.

Domain Management in Management Console (MCO)

Identity Provider Connection (IdPC) is activated on a domain level for all TeamViewer accounts using an email address with this domain. Once activated, all users that sign into a corresponding TeamViewer account are redirected to the identity provider that has been configured for the domain.

For security reasons and to prevent abuse, it is required to verify the domain ownership before the feature is activated.

Add a new domain

To activate IdPC, log in to Management Console and select the Identity Provider Connection menu entry. Click on Add domain and enter the domain you want to activate IdPC for.

You also need to provide you identity provider’s metadata. There are three options available to do so:

  • via URL
    • enter your IdP metadata URL into the corresponding field
  • via XML
    • select and upload your metadata XML
  • Manual configuration
    • manually enter all necessary information. Please note that the public key must be a Base64 encoded string.

Add domain.png

 

Verify domain ownership

After a domain has been added successfully, you need to verify the domain ownership.
Identity Provider Connection will not be activated before the domain verification is completed.

To verify the domain, please create a new TXT record for your domain with the values shown on the verification page.

Note: The verification process can take several hours because of the DNS system.


IdPC_Documentation.png

The dialog to add a TXT record might look similar to: AddDNSrecord.png

Note: Depending on your domain management system, the description of the input fields may vary.

After creating the new TXT record, start the verification process by clicking on the “Start Verification” button.

Please note that the verification process can take several hours because of the DNS system.

Hint: TeamViewer will look for the TXT verification record for 24 hours after starting the verification. In case we cannot find the TXT record within 24 hours, the verification fails and the status is updated accordingly. You need to restart the verification through this dialog in this case. 

Technical information

This section lists the technical details of the TeamViewer SAML Service Provider (SP). This data might be relevant for adding other IdPs than the ones described above.

SAML Service Provider Metadata:

Settings  Value
SP Metdata URL https://sso.teamviewer.com/saml/metadata.xml
Entity ID https://sso.teamviewer.com/saml/metadata
Assertion Consumer Service URL

https://sso.teamviewer.com/saml/acs

Assertion Consumer Service Bindings
HTTP-POST
HTTP-Redirect
SAML Request Signature Algorithm

http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

NameID

Unspecified

 

 Required SAML Response Claims:

Name Remarks
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

This should be mapped to a unique user identifier within the scope of the IdP (and therefore within the scope of the corresponding company).

For example, this can be the Active Directory Object GUID for ADFS or the email address for Okta

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress This attribute should be mapped to the email address of the user that wants to sign-in. The email address needs to be the same as configured for the TeamViewer account. The mapping/comparison is done in a case-in-sensitive way.
http://sso.teamviewer.com/saml/claims/customeridentifier

This attribute should return a customer-specific identifier.

TeamViewer requires a customer identifier as custom claim in the SAML response for the initial configuration of Single Sign-On accounts.
The customer identifier is not stored by TeamViewer. Changing it later will break Single Sign-On and a new setup will be necessary.

Any random string can be used as customer identifier.

 

Signature & Encryption Certificate (Public Key)

The public key of the certificate that is used to sign SAML requests and for the encryption of SAML responses can be obtained by executing the following PowerShell command:

"-----BEGIN PUBLIC KEY-----`n" + `
((Select-Xml `
-Content ((Invoke-WebRequest `
https://sso.teamviewer.com/saml/metadata.xml).Content) `
-xpath "//*[local-name()='X509Certificate']").Node[0].'#text') + `
"`n-----END PUBLIC KEY-----" `
| Out-File -FilePath "sso.teamviewer.com - saml.cer" -Encoding ascii

The command downloads the metadata, extracts the public key and writes it to a file.

Video

 

Version history
Revision #:
23 of 23
Last update:
4 weeks ago
Updated by:
 
Contributors