Export (0) Print
Expand All

Configure Server Signaling Settings

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Server signaling settings functions are encapsulated by the IUccServerSignalingSettings interface. With the properties and methods exposed by IUccServerSignalingSettings, a client can configure security related aspects, the server name and transport protocol of the client sign-in process. These settings include user sign-in credentials, user authentication modes, and the signaling server name and transport protocol. An endpoint instance uses the values set in the server signaling settings object to connect to and communicate with Microsoft Office Communications Server.

A server signaling settings object exposes a credential cache that allows a client to maintain multiple sets of user sign-in credentials. Credential cache is useful when a user has access to multiple realms. Each credential in the cache is assigned to a specific realm. Using the credential cache object, a client can find existing credentials based on realm, add new credentials, or remove credentials from the cache. Before signing in to a server, the client must specify the cached credential to be used in authenticating the local user. The chosen credential is passed to Office Communications Server for authentication as part of the sign-in process.

An authentication mode is a standard process that a client and a server use to establish a Security Association. The three authentication mode properties exposed by a server signaling settings object (AllowedAuthenticationModes, AuthenticationMode, and SupportedAuthenticationModes) support authentication mode negotiation between a client and Office Communications Server. For more information, see Negotiating Authentication Modes with Office Communications Server later in this topic.

The following sections discuss how to configure the server signaling settings object.

To configure the server signaling settings, the application must first obtain an IUccServerSignalingSettings interface pointer by calling QueryInterface for IUccServerSignalingSettings on the IUccEndpoint object.

const GUID IID_IUccServerSignalingSettings = __uuidof(_IUccServerSignalingSettings)

IUccEndpoint *pEndpoint = ... // Assume this is already obtained.
...
IUccServerSignalingSettings* pSettings;
HRESULT hr = pEndpoint->QueryInterface(IID_IUccServerSignalingSettings,
                                         (void**)&pSettings);

In the following C# example, the previous C++ approach is equivalent to casting an IUccEndpoint object into the IUccServerSignalingSettings type.

IUccEndpoint endpoint = ... // Assume this is already obtained.

IUccServerSignalingSettings pSettings = endpoint as IUccServerSignalingSettings;

With the IUccServerSignalingSettings object, the client can proceed to specify a server, transport, authentication modes, and user credentials.

The Server property holds an instance of IUccSignalingServer. This instance represents the Office Communications Server instance a local user is to be signed in to when the principal endpoint is enabled. To fill this property, the client can either discover a collection of available Office Communications Server instances or create a server signaling object representing a known instance of Office Communications Server.

Discovering Available Servers

The process of discovering available servers is also known as automatic configuration. A client requests a list of available servers by calling into the FindServer method, passing the domain of the local user as a string. If the domain parameter is set to null (NULL in C++), the current user domain is used. The result is returned in an OnFindServer event raised by the IUccServerSignalingSettings object. To catch this event, the client must advise the IUccServerSignalingSettings object of _IUccServerSignalingSettingsEvents. This can be done when the IUccServerSignalingSettings interface pointer is obtained or when the associated endpoint object is created.

The OnFindServer callback method is a good place to set the value of the Server property. The SignalingServers property is a collection of available servers representing the front-end servers in an enterprise pool of Office Communications Server instances. Normally, a client sets the Server property to the first instance of the collection. If the client cannot sign in to the chosen server, it should iterate on the returned Office Communications Server collection in the OnEnable callback method. With each iteration, an attempt to sign in to the current signaling server collection instance is made. For more information, see Code Listing: Programming Sign-in Function.

The following example requests a list of available servers in the specified domain. The resulting list is returned asynchronously with the OnFindServer event.

Dd170831.note(en-us,office.12).gifNote:
Use the Host property of the UccUri instance representing the local user as the domain string parameter of the FindServer method.

Request list of available Office Communications Server instances:

void GetServerList(IUccEndpoint principalEndpoint, string OCDomain)
{
    // Obtain interface from principal endpoint.
    IUccServerSignalingSettings serverSignalingSettings = principalEndpoint as IUccServerSignalingSettings;

    // Advise for server signaling settings events.
    UCC_Advise<_IUccServerSignalingSettingsEvents>(this._endpoint, this);

    // Request server list.
    serverSignalingSettings.FindServer(OCDomain, null);
}

Handle the event that returns the server list and then sign in to first server in the list:

The following code example references this.servers. This class field is declared as private IEnumerator servers = null;

void _IUccServerSignalingSettingsEvents.OnFindServer(IUccEndpoint pEventSource, UccFindServerEvent pFindServerEventData)
{
    IUccServerSignalingSettings serverSignalingSettings = pEventSource as IUccServerSignalingSettings;

    if (pFindServerEventData.IsComplete)
    {
        if (pFindServerEventData.SignalingServers.Count > 0)
        {
            // Instantiate declared IEnumerator with collection of servers. 
            this.servers = pFindServerEventData.SignalingServers.GetEnumerator();

            // Iterate on collection and set Server property to first server in collection.
            foreach (IUccSignalingServer ss in pFindServerEventData.SignalingServers)
            {
                serverSignalingSettings.Server = ss;
                break;
            }
            // Enable the endpoint to sign in.
            pEventSource.Enable(null);
        }
        else
        {
            MessageBox.Show("An Office Communications Server instance was not found. Sign in will end","Sign In Error");
        }
    }
}

The preceding example attempts to sign in to the first Office Communications Server instance returned in the server collection. The first server in the collection may not allow the client to sign in the local user. For this reason, a client must be prepared to sign the local user in to each of the other servers in the collection until the sign-in process succeeds. To do this, the client iterates on the collection of servers within the OnEnable callback method. The client attempts to sign in to each additional server in the collection until successfully signed in. For more information, see Enable an Endpoint.

Creating a Server

The process of creating a server is also known as manual configuration. If the server address (serverAddr) and transport mode are known, the client can specify the server by first creating an IUccSignalingServer object for the given server address and a specified transport.

Dd170831.note(en-us,office.12).gifTip:
A client may have to fall back to automatic configuration if the server manually configured for the sign-in process does not allow the local client to sign in. We recommend that you design a client to support both methods of setting the Server property.
void CreateSignalingServer(
    IUccEndpoint principalEndpoint, 
    UCC_TRANSPORT_MODE transport, 
    string serverAddr)
{
    IUccServerSignalingSettings serverSignalingSettings = principalEndpoint as IUccServerSignalingSettings;
    IUccServerSignalingServer pServer = 
               serverSignalingSettings.CreateSignalingServer(serverAddr, transport);
    serverSignalingSettings.Server = pServer;

    // Enable the endpoint and sign-in process.
    principalEndpoint.Enable(null);
}

The transport parameter can be one of the UCC_TRANSPORT_MODE values.

This section explains how a custom client examines a credential cache to see if a desired credential exists. When the desired credential does not exist, this section explains how to make a new credential using a default credential or a local user's domain, name, and password.

Get Existing Credential

When a credential is set by a previous call to SetCredential, the client can call TryGetCredential to obtain the credential for a specified realm.

/// <summary>
/// Returns a credential based on realm and matched against
/// desired domain
/// </summary>
/// <param name="cache">IUccCredentialCache the cache holding desired credential</param>
/// <param name="pRealm">string realm associated with desired credential</param>
/// <param name="pDomain">string domain restriction</param>
/// <returns>UccCredential</returns>
public UccCredential GetCredentialForDomain(
    IUccCredentialCache cache,
    string pRealm, 
    string pDomain)
{
    UccCredential credential = null;

    if (cache.TryGetCredential(pRealm, out credential))
    {
        if (credential.Domain == pDomain)
        {
            return credential;
        }
        else
        {
            return null;
        }
    }
    else
    {
        return null;
    }
}

Get New Credential Using Default Credential

The client can use the default credential of the user when the transport uses Transport Layer Security (TLS) encryption. In the following example, to obtain the default credential, the client reads the DefaultCredential property. Normally the default credential is used when the targeted server requires the use of the TLS transport protocol.

The following example references this._credentialCache, a class field declared as private IUccCredentialCache _credentialCache;

/// <summary>
/// Returns default credential
/// </summary>
public UccCredential DefaultCredential
{
    get
    {
        return this._credentialCache.DefaultCredential;
    }
}

Create New Credential with User Domain, Name, and Password

Specifying user credentials amounts to calling the CreateCredential and SetCredential method on the CredentialCache object that is maintained as part of the server signaling settings.

string userName = "john" ;
string password = password ;
string domain = "contoso.com" ;
credential = pSettings.CredentialCache.CreateCredential(
                        userName, password, domain);

Set Credential

After a client application locates an existing credential or obtains a new credential, it must set that credential as the credential to be used when the associated endpoint is enabled. The following example accepts the server signaling settings object obtained from the principal endpoint, the credential to be used during the sign-in process, and a string representing the realm to associate with the credential.

/// <summary>
/// Adds a passed credential to a cache and associates credential
/// to a realm
/// </summary>
/// <param name="serverSignalingSettings">IUccServerSignalingSettings server signaling settings </param>
/// <param name="credential">IUccCredential credential to add to cache.</param>
/// <param name="pRealm">string realm to associate to credential</param>
/// <returns>Boolean</returns>
private Boolean pr_SetCredentialForSignIn(
   IUccServerSignalingSettings serverSignalingSettings,
   UccCredential credential,
   string pRealm)
{
   Boolean returnValue = false;
   // Specify the credential and authentication types.
   try
   {
      serverSignalingSettings.CredentialCache.SetCredential(pRealm, credential);
      returnValue = true;

      // Add credential to application class that wraps credential cache.
       newCache.AddCredentialToCache(credential, "*");
   }
   catch (Exception)
   {
   }
   return returnValue;
}

Remove Credential

The following example removes a credential from a credential cache based on the specified realm. This example references this._credentialCache, a class field declared as private IUccCredentialCache _credentialCache;

/// <summary>
/// Removes a credential from a credential cache based on passed realm as string
/// </summary>
/// <param name="pRealm">string realm of interest</param>
public void RemoveCurrentCredential(string pRealm)
{
    UccCredential c;

    // Test for credential existence.
    if (this._credentialCache.TryGetCredential(pRealm, out c))
    {
        // Remove the credential from the cache.
        this._credentialCache.RemoveCredential(pRealm);
    }
}

Negotiating Authentication Modes with Office Communications Server

To establish a Security Association between a client and Office Communications Server, the two entities must agree on an authentication mode to be used for the sign-in process. An Office Communications Server instance can support one or all possible authentication modes. Office Communications Server provides a client with its supported list of authentication modes. The Office Communications Server supported modes are exposed in the SupportedAuthenticationModes property. The client builds a list of authentication modes it agrees to use and places the choice in the exposed AllowedAuthenticationModes property. The client and Office Communications Server instance negotiate the authentication mode to be used based on the highest mode that exists in both lists. The final mode choice is exposed in the AuthenticationMode property.

Dd170831.note(en-us,office.12).gifImportant:
Office Communications Server supports UCC_AUTHENTICATION_MODES.UCCAM_NTLM for cross-firewall sign-in requests and UCC_AUTHENTICATION_MODES.UCCAM_KERBEROS for intranet sign-in requests. A custom client should always agree to use these two standard authentication modes.

To specify allowed authentication modes, the client sets the AllowedAuthenticationModes property with a value that is a bit-wise combination of the flags defined in UCC_AUTHENTICATION_MODES. In the following example, a client sets Kerberos or NTLM as allowed modes of authentication.

IUccEndpoint endpoint = ...; // Assume an enabled endpoint is created.
IUccServerSignalingSettings settings = endpoint as IUccServerSignalingSettings;
settings.AllowedAuthenticationModes = 
                         (int)UCC_AUTHENTICATION_MODES.UCCAM_KERBEROS 
                        | (int)UCC_AUTHENTICATION_MODES.UCCAM_NTLM;

Community Additions

ADD
Show:
© 2014 Microsoft