Expand Collapse
Just a second...

Connecting 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 = session_create(url, principal, credentials, &session_listener, NULL, NULL);

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 API specify the credentials as a credentials object. The principal and credentials are specified when configuring the session before opening it:

Apple 
PTDiffusionCredentials *const credentials =
    [[PTDiffusionCredentials alloc] initWithData:data];

PTDiffusionSessionConfiguration *const configuration =
    [[PTDiffusionSessionConfiguration alloc] initWithPrincipal:@"principal"
                                                   credentials:credentials];

[PTDiffusionSession openWithURL:[NSURL URLWithString:@"wss://push.example.com"]
                  configuration:configuration
              completionHandler:^(PTDiffusionSession *session, NSError *error)
{
    // Check error is `nil`, then use session as required.
    // Ensure to maintain a strong reference to the session beyond the lifetime
    // of this callback, for example by assigning it to an instance variable.
}];
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 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 
// Create a credentials object encapsulating a string password.
PTDiffusionCredentials *const credentials =
    [[PTDiffusionCredentials alloc] initWithPassword:@"password"];

PTDiffusionSessionConfiguration *const configuration =
    [[PTDiffusionSessionConfiguration alloc] initWithPrincipal:@"principal"
                                                   credentials:credentials];

[PTDiffusionSession openWithURL:[NSURL URLWithString:@"url"]
                  configuration:configuration
              completionHandler:^(PTDiffusionSession *session, NSError *error)
{
    // Check error is `nil`, then use session as required.
    // Ensure to maintain a strong reference to the session beyond the lifetime
    // of this callback, for example by assigning it to an instance variable.
}];
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 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(byte_credentials)
						   .open("url");
.NET 
var session = Diffusion.Sessions
					   .Principal("principal")
					   .CustomCredentials(byte_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: 2018/04/06