Tuesday 8 April 2014

SEFAUTIL and Lync 2013 Call Pickup Group Tool Permissions

I have had some enquiries from people about issues that they have been having with SEFAUtil  (ie. the Call Forwarding and Group Call Pickup tool from the Lync ResKit). Many of these questions have been about getting no response from SEFAUTIL after running a command. This can be for a few reasons, some of which may have to do with permissions, others to do with configuration. So in this post we’re going to go through the requirements and permissions needed for SEFAUtil as well as the permissions needed for running the Lync 2013 Call Pickup Group Manager. Before we go any further, some background; SEFAUTIL was designed to be run on a server that has Lync server components installed on it. As Jens Trier’s blog post on the tool points out, even if you want to run SEFAUTIL on a separate machine, it still needs to have Lync server base components installed. So it makes sense to choose to run the SEFAUtil on an Front End Server.

How can we run SEFAUtil and the Call Pickup Manger on a server and only give a user accessing it minimum permissions? Well, as we all (may or may not) know, the Lync RBAC role permissions (ie. the Active Directory security groups starting with the prefix “Cs”, example “CsAdministrator”) do not apply to someone that is logged directly into a Lync server. These roles only restrict access to users that are either connecting via Lync Control Panel, or via remote Powershell connection via the “OcsPowershell” webservice that runs on the Front End. When you’re logged into the Lync server directly there are some Active Directory permissions that will affect your ability to access the backend SQL database which will stop you from running some commands. These SQL permissions are tied back to the Active Directory security groups that start with the “RTC” prefix. So, in short, these permissions can still affect a user's ability to access some commands/functions when logged directly into a Lync server.

The SEFAUtil tool documentation doesn't contain any details about what rights are required to use it. However, from testing in the lab I have concluded that you need to be logged in as a user with a minimum of “RTCUniversalReadOnlyAdmins” rights for it to work. Example:


In case you were also wondering which other permissions work for SEFAUTIL, here’s a list:

Permission
SEFAUTIL Works?
RTCUniversalReadOnlyAdmins
Yes
RTCUniversalUserAdmins
Yes
RTCHSUniversalServices
Yes
RTCUniversalSBATechnicians
Yes
RTCSBAUniversalServices
Yes
RTCUniversalServerAdmins
No
RTCUniversalServerReadOnlyGroup
No
RTCUniversalGlobalReadOnlyGroup
No
RTCUniversalUserReadOnlyGroup
No
RTCComponentUniversalServices
No
RTCProxyUniversalServices
No
RTCUniversalConfigReplicator
No
RTCUniversalGlobalWriteGroup
No

Note: These results are from lab testing. If you see any different results in the field, let me know.


Lync 2013 Call Pickup Manager Permissions

As I mentioned earlier, the Call Pickup Manager Tool also needs to query SQL in order to get information about users in the database (this allows for quick retrieval of current user settings). It does this by making direct SQL SELECT calls to the RTCLOCAL databases on each Front End server. When you run the tool you may find that you receive an error that looks like this:

Error running SQL on 2013ENTFE004.domain.com : The SELECT permission was denied on the object 'Resource', database 'rtc', schema 'dbo'.

This error is caused by the user not having sufficient rights to make direct SQL SELECT calls on the database. If you were logged in with Domain Admin rights you would not receive this error, as you would have sufficient permissions on the database (however, not everyone can be given Domain Admin permissions!).

To get around this issue we will need to allow permissions for specific users to be able to make SELECT (read only) calls on the “rtc” database. The simplest way to do this is to Grant “select” permissions to the “RTC Local Read Only Administrators” user within SQL for the “rtc” database. The “RTC Local Read Only Administrators” local machine user maps back to the “RTCUniversalReadOnlyAdmins” security group within Active Directory. So any user that you add to the “RTCUniversalReadOnlyAdmins” will have permission to run SQL SELECT commands on the database. This also works well, as SEFAUtil also requires a minimum of “RTCUniversalReadOnlyAdmins” group permissions to work, so it is a good choice for allowing permissions on the database as well.

Granting SQL Permissions on Tables Example


To be as restrictive as possible, we can grant “Select” permissions only on the tables that the Call Pickup Manager tool needs to read in order to work. The two databases that the Call Pickup Manager Tool needs access to are the dbo.Resources and dbo.PublishedStaticInstance tables. The steps below walk you through applying these permissions:

STEP1: Open SQL Management Studio (you will need to have installed this on a machine to access the database).

STEP 2: From the Object explorer, open the “Databases”->”rtc”->”Tables” tree.

STEP 3:  Right Click on the PublicStaticInstance table, and select Properties



STEP 4: On the Permissions page, click on the Search button:


STEP 5: Click on the Browse Button. Then select the “RTC Local Read Only Administrators” user:


STEP 6: Click OK. You should see the User in the object list:



STEP 7: Now the "RTC Local Read Only Administrators" user will appear in the Users and Roles list. Click on it and Grant it “select” permissions:


STEP 8: Do the same process to give select permission on the “resources” table (STEP 1 - STEP 7):



If you would prefer not to do this manually I’ve also prepared a Powershell script that you could use to speed up the process:



1.00 Initial Release:
  • This script will give RTCUniversalReadOnlyAdmins SELECT permissions on all the Lync Front End Servers RTC PublishedStaticInstance and Resource database tables.
  • Run the script from a Lync server with a user account that has sufficient permissions to make changes to the "rtc" SQL database.
  • This script is designed to give the minimum required permissions to the database for a user to use the Call Pickup Group Manager tool.
  • Ensure that you have opened the Firewall ports for the RTCLOCAL database using the "OpenSQLPortsForCallPickupManager1.00.ps1" script before trying to running this permissions script. If you haven't opened the firewall you will get connection errors when you try and run this script.


SEFAUtil Error Debugging

By default, SEFAUtil does not give you any feedback as to why the tool is not working: when it hits an exception it will stop executing with no error message. However, after doing a bit of detective work, I discovered that SEFAUtil actually has an undocumented “verbose” flag that can be used to help debug why SEFAUtil is not working (this is now baked into the Call Pickup Group ManagerTool version 1.02). Below are two examples of common issues that you might see with SEFAUtil not working: 

User Running SEFAUtil Does Not Have Correct Permissions: 

If the user logged into the Lync Server does not have the correct permissions (ie. one of the “RTC” group permissions I talked about earlier) they will get an error reported in the shell window like this one:

PS C:\Program Files\Microsoft Lync Server 2013\ResKit> .\sefautil.exe /server:melbfepool.domain.com holly.hunt@domain.com /verbose

Starting CollabPlatform...
Microsoft.Rtc.Collaboration.ProvisioningFailureException:One or more values in the configured settings are invalid or unusable. Check inner exception and logs for more details. ---> Microsoft.Rtc.Internal.ServerConfiguration.SettingsInitializationException: The settings wrapper failed to initialize.
Unable to find  the Sqld database: Cannot open database "xds" requested by the login. The login failed.
Login failed for user '2013ENT\testadmin'.
   at Microsoft.Rtc.Internal.ServerConfiguration.UCSettings.InitConsumerWithRole
(RoleName role)
   at Microsoft.Rtc.Internal.ServerConfiguration.UCSettings..ctor(String applicationId, SettingsWrapperOptions options)
   at Microsoft.Rtc.Internal.ServerConfiguration.UCSettings.Get(String applicationId, SettingsWrapperOptions options)
   at Microsoft.Rtc.Collaboration.ProvisioningSourceImpl.GetInitialPlatformData()

--- End of inner exception stack trace ---
   at Microsoft.Rtc.Signaling.SipAsyncResult`1.ThrowIfFailed()
   at Microsoft.Rtc.Signaling.Helper.EndAsyncOperation[T](Object owner, IAsyncResult result)
   at SEFAUtil.SefaTool.Execute()
Detected at System.Environment.GetStackTrace(Exception e, Boolean needFileInfo)
   at System.Environment.get_StackTrace()
   at Microsoft.Rtc.Collaboration.ProvisioningFailureException..ctor(String message, Exception innerException, ProvisioningFailureReason failureReason)
   at Microsoft.Rtc.Collaboration.ProvisioningSourceImpl.GetInitialPlatformData()
   at Microsoft.Rtc.Collaboration.ProvisioningSourceGetInitialPlatformDataAsyncResult.ProcessCoreHelper()
   at Microsoft.Rtc.Collaboration.SipCollaborationAsyncResult.ProcessCore()
   at Microsoft.Rtc.Signaling.AsyncWorkitemQueue.ProcessItems()
   at Microsoft.Rtc.Signaling.SerializationQueue`1.ResumeProcessing()
   at Microsoft.Rtc.Signaling.SerializationQueue`1.ResumeProcessingCallback(Object state)
   at Microsoft.Rtc.Signaling.QueueWorkItemState.ExecuteWrappedMethod(WaitCallback method, Object state)
   at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
   at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
   at System.Threading.QueueUserWorkItemCallback.System.Threading.IThreadPoolWorkItem.ExecuteWorkItem()
   at System.Threading.ThreadPoolWorkQueue.Dispatch()
FailureReason = 2


SEFAUtil Trusted Application Not Configured Properly:

If the Trusted Application has not been configured correctly in Lync you will get an error like the one below:

PS C:\Program Files\Microsoft Lync Server 2013\ResKit> .\sefautil.exe /server:melbfepool.domain.com holly.hunt@domain.com /verbose

Starting CollabPlatform...
Microsoft.Rtc.Collaboration.ProvisioningFailureException:One or more values in the configured settings are invalid or unusable. Check inner exception and logs for more details. ---> Microsoft.Rtc.Internal.ServerConfiguration.SettingsInitializationException: The settings wrapper failed to initialize.
The ExternalServer service is not installed on the machine.
   at Microsoft.Rtc.Internal.ServerConfiguration.UCSettings.InitConsumerWithRole
(RoleName role)
   at Microsoft.Rtc.Internal.ServerConfiguration.UCSettings..ctor(String applicationId, SettingsWrapperOptions options)
   at Microsoft.Rtc.Internal.ServerConfiguration.UCSettings.Get(String applicationId, SettingsWrapperOptions options)
   at Microsoft.Rtc.Collaboration.ProvisioningSourceImpl.GetInitialPlatformData()

--- End of inner exception stack trace ---
   at Microsoft.Rtc.Signaling.SipAsyncResult`1.ThrowIfFailed()
   at Microsoft.Rtc.Signaling.Helper.EndAsyncOperation[T](Object owner, IAsyncResult result)
   at SEFAUtil.SefaTool.Execute()
Detected at System.Environment.GetStackTrace(Exception e, Boolean needFileInfo)
   at System.Environment.get_StackTrace()
   at Microsoft.Rtc.Collaboration.ProvisioningFailureException..ctor(String message, Exception innerException, ProvisioningFailureReason failureReason)
   at Microsoft.Rtc.Collaboration.ProvisioningSourceImpl.GetInitialPlatformData()
   at Microsoft.Rtc.Collaboration.ProvisioningSourceGetInitialPlatformDataAsyncResult.ProcessCoreHelper()
   at Microsoft.Rtc.Collaboration.SipCollaborationAsyncResult.ProcessCore()
   at Microsoft.Rtc.Signaling.AsyncWorkitemQueue.ProcessItems()
   at Microsoft.Rtc.Signaling.SerializationQueue`1.ResumeProcessing()
   at Microsoft.Rtc.Signaling.SerializationQueue`1.ResumeProcessingCallback(Object state)
   at Microsoft.Rtc.Signaling.QueueWorkItemState.ExecuteWrappedMethod(WaitCallba
ck method, Object state)
   at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
   at System.Threading.ExecutionContext.Run(ExecutionContext executionContext, ContextCallback callback, Object state, Boolean preserveSyncCtx)
   at System.Threading.QueueUserWorkItemCallback.System.Threading.IThreadPoolWorkItem.ExecuteWorkItem()
   at System.Threading.ThreadPoolWorkQueue.Dispatch()
FailureReason = 2

The Wrap Up


“Permissions, Permissions everywhere, nor any lock to Lync.” - Samuel Taylor Lyncridge 

So anyway, that may have been slightly long winded, however, hopefully it was edu-taining for you all. In a nutshell you just need to put the user in the “RTCUniversalReadOnlyAdmins” security group, and add the SELECT permissions on the database. After that, you should be about to access SEFAUtil and the Lync Call Pickup Group Manager. 


2 comments:

  1. Excellent stuff, as always. Noticed that RTCUniversalUserAdmins is listed twice in that first table.

    ReplyDelete
    Replies
    1. Thanks Pat, copy paste error.

      For completeness I've updated the table with all the "RTC" groups.

      Delete

Popular Posts