Connecting to Diffusion Cloud with a security principal and credentials

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

try {
    const session = await diffusion.connect({
        host : 'host_name',
        port : 'port',
        principal: 'principal',
        // using a string value for the credentials
        credentials: 'credentials'
    });

    // At this point we now have a connected session.
    console.log('Connected');
} catch(error) {
    console.error('Failed to create session!', error);
}

C

CREDENTIALS_T *credentials = credentials_create_none();
SESSION_T *session = session_create(url, principal, credentials, NULL, 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™ , Python, and .NET API specify the credentials as a credentials object. The principal and credentials are specified when configuring the session before opening it:

.NET

var session = Diffusion.Sessions
                   .Principal("principal")
                   .Credentials(Diffusion.Credentials.Password("credentials"))
                   .Open("url");

Java and Android

final Factory factory = Diffusion.credentials();

final Session session = Diffusion.sessions()
    .principal("principal")
    .credentials(factory.password("password"))
    .open("ws://localhost:8080");

Python

# Diffusion server connection information; same for both sessions
# adjust as needed for the server used in practice
server_url = "ws://localhost:8080"
principal = "admin"
credentials = diffusion.Credentials("password")

# creating the session
async with diffusion.Session(
    url=server_url, principal=principal, credentials=credentials
) as session:
    _ = session
    pass

Apple

let credentials = PTDiffusionCredentials(password: "password")

let configuration = PTDiffusionMutableSessionConfiguration(principal: "principal",
                                                           credentials: credentials)

// Use the configuration to open a new session...
PTDiffusionSession.open(with: URL(string: "url")!,
                        configuration: configuration) { (session, error) in

    // 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.

    if (session == nil) {
        print("Failed to open session: %@", error!.localizedDescription)
        return
    }

    // At this point we now have a connected session.
    print("Connected.")
}

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:

.NET

var session = Diffusion.Sessions
                   .Principal("principal")
                   .Password("credentials")
                   .Open("url");

Java and Android

final Session session = Diffusion.sessions()
    .principal("principal")
    .password("credentials")
    .open("ws://localhost:8080");

C

CREDENTIALS_T *credentials = credentials_create_password(password);
SESSION_T *session = session_create(url, principal, credentials, NULL, NULL, NULL);

Apple

let credentials = PTDiffusionCredentials(password: "password")
let configuration = PTDiffusionMutableSessionConfiguration(principal: "principal",
                                                           credentials: credentials)

// Use the configuration to open a new session...
PTDiffusionSession.open(with: URL(string: "url")!,
                        configuration: configuration) { (session, error) in

    // 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.

    if (session == nil) {
        print("Failed to open session: %@", error!.localizedDescription)
        return
    }

    // At this point we now have a connected session.
    print("Connected.")
}

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:

JavaScript

try {
    const session = await diffusion.connect({
        host : 'host_name',
        port : 'port',
        principal: 'principal',
        // using a string value for the credentials
        credentials: Buffer.from(arrayBuffer)
    });

    // At this point we now have a connected session.
    console.log('Connected');
} catch(error) {
    console.error('Failed to create session!', error);
}

.NET

var session = Diffusion.Sessions
                   .Principal("principal")
                   .CustomCredentials(Encoding.Default.GetBytes("mF_9.B5f-4.1JqM"))
                   .Open("url");

Java and Android

final byte[] credentials = "password".getBytes();

final Session session = Diffusion.sessions()
    .principal("principal")
    .customCredentials(credentials)
    .open("ws://localhost:8080");

C

CREDENTIALS_T *credentials = credentials_create_custom(data, data_length);
SESSION_T *session = session_create(url, principal, credentials, NULL, NULL, NULL);

Apple

let credentials = PTDiffusionCredentials(data: data)

let configuration = PTDiffusionMutableSessionConfiguration(principal: "principal",
                                                           credentials: credentials)

// Use the configuration to open a new session...
PTDiffusionSession.open(with: URL(string: "url")!,
                        configuration: configuration) { (session, error) in

    // 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.

    if (session == nil) {
        print("Failed to open session: %@", error!.localizedDescription)
        return
    }

    // At this point we now have a connected session.
    print("Connected.")
}

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.