< Back to Package Overview
Working with Credentials
- Providing the login credentials to the Client SDK
- Working with Credentials
- Registering for authentication challenge events
- Responding to authentication challenge requests
- Getting authentication results
- Cancellation of challenge requests
- Integrated Windows Authentication (IWA)
- Workstation registered in Domain
- Workstation not Registered in Domain
- Support by Platform
- Support by Service
Providing the login credentials to the Client SDK
Working with Credentials
All Client SDK services that depend on infrastructure services accessed over a network require login credentials. Applications are responsible for providing the login credentials to Client SDK through the ICredentialProvider interface.
Registering for authentication challenge events
To register for authentication challenge events create a ICredentialProvider instance per service when defining the configuration data for your User object. Creating a ICredentialProvider instance per service will allow your application to respond to different infrastructure challenge requests simultaneously if you support multiple services within your application.
For example, if you are using theCall Service with a SIP provider you would use the following code to define your instance of the ICredentialProvider for the SIP service.
public class UserNamePasswordCredentialProvider : ICredentialProvider
{
public void OnAuthenticationChallenge(Challenge challenge,
CredentialCallback credentialCallback)
{
// Called when Client SDK is challenged for credentials
// by the SIP server
}
public void OnCredentialAccepted(Challenge challenge)
{
// Called when the SIP server has accepted the credentials
// provided during the challenge request
}
public void onAuthenticationChallengeCancelled(Challenge challenge)
{
// Can be called at any time to notify the calling
// application that no response should be expected for
// the specified challenge request.
}
}
You can then assign your instance of the ICredentialProvider to the configuration object for the SIP service:
SipUserConfiguration sipConfiguration = new SipUserConfiguration();
sipConfiguration.CredentialProvider =
new UserNamePasswordCredentialProvider("","","");
With this configuration in place when you call 'Start()' from your User instance the following sequence of events will occur:
- Client SDK will attempt to register to the SIP server defined in SipUserConfiguration
- The SIP server will challenge the client for credentials
- Client SDK will invoke the callback onAuthenticationChallenge of the ICredentialProvider object in response to the server challenge to notify the calling application that credentials are required.
Responding to authentication challenge requests
When your application receives an onAuthenticationChallenge callback invoked on one of your credential providers you must respond to the Challenge request. This is necessary to complete the registration process with the infrastructure service and begin to use the features associated with this service.
The Challenge object contains information about the authentication challenge (e.g. realm, host, failureCount).
To respond to the challenge request, create a UserCredential object and populate it with the username, domain, and password:
UserCredential userCredential =
new UserCredential("","","");
Once you have the UserCredential object created use the CredentialCallback delegate of the CredentialCallback to respond to the challenge request:
credentialCallback(userCredential);
Note: If it is not possible to immediately respond to the onAuthenticationChallenge challenge request you can save the reference to the CredentialCallback and provide the credentials when they are available. This is useful, for example, if this event will result in a popup or notification request to the end user. End users may or may not be able to respond immediately to provide the credentials requested.
Getting authentication results
Once you have responded to the challenge request using the CredentialCallback Client SDK will respond to the infrastructure server with the credentials provided.
If the infrastructure server accepts the credentials your application will be notified via the onCredentialAccepted method of the ICredentialProvider object.
If the infrastructure server rejects the credentials, another challenge is raised using onAuthenticationChallenge. The calling application can examine the failure count via the FailureCount property of the Challenge object. The failure count represents the number of challenge-response attempts that have been rejected for this particular challenge.
Cancellation of challenge requests
Cancellation of challenge requests may occur at any time. The calling application will be notified when a challenge request has been cancelled via the onAuthenticationChallengeCancelled callback on the ICredentialProvider object.
The most common reason for a challenge request to be cancelled is due to a network failure between the client application and infrastructure service.
If you have already responded to the challenge request when you receive the cancellation of the challenge request this indicates that you should not expect a response, positive or negative, to the challenge response.
Integrated Windows Authentication (IWA)
Integrated Windows Authentication (IWA) is a feature that allows applications built on Client SDK to login to network services automatically on Windows devices that are active and logged into the Windows domain.
Client SDK automatically handles Integrated Windows Authentication for the native Windows platform.
When your application configures Client SDK services to use Integrated Windows Authentication, Client SDK will manage CredentialProvider on behalf of your application if Client SDK can successfully initialize the required security content. When the security content cannot be acquired, the challenge will be invoked on the CredentialProvider your application configured in the ServiceProvider configuration. If the ServiceProvider continues to challenge the request, the service request will eventually fail. Client SDK does not provide a fallback for failed IWA interactions.
Workstation registered in Domain
The following sequence diagram shows the interactions with CredentialsProvider when the workstation can successfully establish the security context. This will occur when the workstation is currently registered with the domain, typically when the workstation is on premise, or attached to the enterprise network using a Virtual Private Network (VPN).
![Workstation_registered_in_Domain.png]()
Workstation not Registered in Domain
The following sequence diagram shows the interactions with CredentialsProvider when the workstation cannot successfully establish the security context. This will occur when the workstation is not currently registered with the domain, such as when the user is working remotely. This can flow can happen at any time.
![Workstation_is_not_registered_in_Domain.png]()
| Windows |
MacOS |
Android |
iOS |
| Yes |
No |
No |
No |
Support by Service
| Client SDK Servicwe |
IWA Supported |
| Call Service |
No |
| Conferencing Service |
No |
| Contact Service (PPM) |
No |
| Contact Service (AADS) |
Yes |
| Contact Service (LDAP) |
Yes |
| Presence Service |
No |
| Messaging Service (AMM) |
Yes |
| Collaboration (WCS, BFCP) |
No |
| ESG - Calls |
Yes |
| ESG - Presence |
Yes |
| Portal |
Yes |
