< Back to Package Overview
Working with Credentials
- Registering for authentication challenge events
- Responding to authentication challenge requests
- Getting authentication results
- Cancellation of challenge requests
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 the Client SDK through the <CSCredentialProvider> interface.
Registering for authentication challenge events
To register for authentication challenge events create a <CSCredentialProvider> instance per service when defining the configuration data for your CSUser object. Creating a <CSCredentialProvider> 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 the CSCall Service with a SIP provider you would use the following code to define your instance of the <CSCredentialProvider> for the SIP service.
@interface CredentialProvider: NSObject
...
@end
@implementation CredentialProvider
- (void)credentialProviderDidReceiveChallenge:(CSChallenge *)challenge
completionHandler:
(void (^)(CSUserCredential *credential)) completionHandler {
// Called when Client SDK is challenged for credentials
// by the SIP server
}
- (void)credentialProviderDidReceiveCredentialAccepted:
(CSChallenge *)challenge {
// Called when the SIP server has accepted the credentials
// provided during the challenge request
}
- (void)credentialProviderDidReceiveChallengeCancelled:
(CSChallenge *)challenge {
// Can be called at any time to notify the calling
// application that no response should be expected for
// the specified challenge request.
}
@end
You can then assign your instance of the <CSCredentialProvider> to the configuration object for the SIP service:
CredentialProvider *credentialProvider = [[CredentialProvider alloc] init];
CSUserConfiguration *userConfig = [[CSUserConfiguration alloc] init];
userConfig.SIPUserConfiguration.credentialProvider = credentialProvider;
With this configuration in place when you call 'Start()' from your CSUser instance the following sequence of events will occur:
- Client SDK will attempt to register to the SIP server defined in CSSIPUserConfiguration
- The SIP server will challenge the client for credentials
- Client SDK will invoke the callback onAuthenticationChallenge of the <CSCredentialProvider> 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 callback invoked on one of your credential providers you must respond to the CSChallenge request. This is necessary to complete the registration process with the infrastructure service and begin to use the features associated with this service.
The CSChallenge object contains information about the authentication challenge (e.g. realm, host, failureCount).
To respond to the challenge request, create a CSUserCredential object and populate it with the username, domain, and password:
CSUserCredential *userCredential =
[[CSUserCredential alloc] initWithUsername: "name"
password: "password"
domain: "domain"
ha1String: nil];
Once you have the CSUserCredential object created use the completionHandler callback handler to the challenge request:
completionHandler(userCredential);
Note: If it is not possible to immediately respond to the credentialProviderDidReceiveChallenge challenge request you can save the reference to the CSUserCredential 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 completionHandler method 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 credentialProviderDidReceiveCredentialAccepted method of the <CSCredentialProvider> object.
If the infrastructure server rejects the credentials, another challenge is raised using credentialProviderDidReceiveChallenge. The calling application can examine the failure count via the failureCount property of the CSChallenge 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 credentialProviderDidReceiveChallengeCancelled callback on the <CSCredentialProvider> 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.
