Connecting to the Diffusion server with a security principal and credentials

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.
proposedProperties: User-defined session properties proposed for the session. If these are supplied, the authenticator can choose to permit or change them.

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

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 authenticator 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.")
}

Re-authenticating a session

The client session can re-authenticate in order to change the principal and credentials it uses to connect to the Diffusion server at any time. The session may also choose to re-authenticate with the same (or different) principal to avoid the session expiring (if its $ExpiryTime property has been set). For more information, see Re-authenticating your client session.