Expand Collapse
Just a second...

Connecting to Diffusion Cloud with a security principal and credentials

The Diffusion™ Cloud 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 Diffusion Cloud. 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 Diffusion Cloud 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 Diffusion Cloud 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 Diffusion Cloud at any time. For more information, see Change the security principal and credentials associated with your client session.

This page last modified: 2019/11/22