Expand Collapse
Just a second...

Connect to the Diffusion server with a security principal and credentials

The Diffusion™ server can accept anonymous connections. However, if your clients specify a security principal (for example, a username) and its associated credentials (for example, a password) when they connect, these client sessions can be authenticated and authorized in a more granular way.

Authentication parameters

principal
A string that contains the name of the principal or identity that is connecting to the Diffusion server. If a value is not specified when connecting, the principal defaults to ANONYMOUS.
credentials
Credentials are a piece of information that authenticates the principal. This can be empty or contain a password, a cryptographic key, an image, or any other piece of information.

If you connect to the Diffusion server using a principal and credentials, connect over SSL to ensure that these details are encrypted.

Connecting using any type of credentials

In JavaScript® and C the method that opens a connection to the Diffusion server takes principal and credentials as parameters:

JavaScript 
diffusion.connect({
    host : 'host_name',
    port : 'port', 
	principal: 'principal',
    credentials: 'credentials'						
});
C 
SESSION_T *session = NULL;
session = session_create(url, principal, credentials, &session_listener, NULL, NULL);
session_start(session, &error);

Any form of credentials can be wrapped in a credentials object. This can be empty or contain a password, a cryptographic key, an image, or any other piece of information. The authentication handler is responsible for interpreting the bytes.

In the Apple®, Android™, Java™, and .NET Unified API specify the credentials as a credentials object. The principal and credentials are specified when configuring the session before opening it:

Apple 
    NSData *const credentialsData = [NSData dataWithBytes:(char[]){2,4,6,8} length:4];

    PTDiffusionCredentials *const credentials = [[PTDiffusionCredentials alloc] initWithData:credentialsData];
    PTDiffusionSessionConfiguration *const sessionConfiguration = [[PTDiffusionSessionConfiguration alloc]
                                                                   initWithPrincipal:@"somePrincipalName"
                                                                   credentials:credentials];
    [PTDiffusionSession openWithURL:[NSURL URLWithString:@"ws://push.example.com"]
                      configuration:sessionConfiguration
                  completionHandler:^(PTDiffusionSession *newSession, NSError *error)
     {
         if (newSession) {
             NSLog(@"Session open.");
             self.session = newSession;
         } else {
             NSLog(@"Session Failed to open with error: %@", error);
         }
     }];
Java and Android 
Session session = Diffusion.sessions()
                           .principal("principal")
						   .credentials("credentials")
						   .open("url");
.NET 
var session = Diffusion.Sessions
                       .Principal("principal")
					   .Credentials("credentials")
					   .Open( "url" );

Connecting using a string password as credentials

A string password is the most commonly used type of credentials. The Apple, Android, Java, and .NET Unified API provide a convenience method that enables you to specify credentials as a string password. The principal and credentials are specified when configuring the session before opening it:

Apple 
    PTDiffusionCredentials *const credentials = [[PTDiffusionCredentials alloc] initWithPassword:@"s3cret"];
    PTDiffusionSessionConfiguration *const sessionConfiguration = [[PTDiffusionSessionConfiguration alloc]
                                                                   initWithPrincipal:@"somePrincipalName"
                                                                   credentials:credentials];
    [PTDiffusionSession openWithURL:[NSURL URLWithString:@"ws://push.example.com"]
                      configuration:sessionConfiguration
                  completionHandler:^(PTDiffusionSession *newSession, NSError *error)
     {
         if (newSession) {
             NSLog(@"Session open.");
             self.session = newSession;
         } else {
             NSLog(@"Session Failed to open with error: %@", error);
         }
     }];
Java and Android 
Session session = Diffusion.sessions()
                           .principal("principal")
						   .password("credentials")
						   .open("url");
.NET 
var session = Diffusion.Sessions
                       .Principal("principal")
					   .Password("credentials")
					   .Open( "url" );

Connecting using a byte array as credentials

The Android, Java, and .NET Unified API provide a convenience method that enables you to specify credentials as a byte array. The principal and credentials are specified when configuring the session before opening it:

Java and Android 
Session session = Diffusion.sessions()
						   .principal("principal")
						   .customCredentials(credentials)
						   .open("url");
.NET 
var session = Diffusion.Sessions
					   .Principal("principal")
					   .CustomCredentials(credentials)
					   .Open( "url" );

Changing the principal and credentials a session uses

The client session can change the principal and credentials it uses to connect to the Diffusion server at any time. For more information, see Change the security principal and credentials associated with your client session.

This page last modified: 2017/05/24