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

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);
}

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("credentials")
   .Open( "url" );

Java and Android

Session session = Diffusion.sessions()
   .principal("principal")
   .credentials("credentials")
   .open("url");

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

//  Copyright (C) 2021 Push Technology Ltd.
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//  http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.

import Foundation
import Diffusion

class ConnectingCredentials {

    func connect_credentials_as_object() {
        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.")
        }
    }


    func connect_with_string_as_credentials() {

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


    func connect_with_data_as_credentials(data: Data) {
        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.")
        }
    }

}

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

Session session = Diffusion.sessions()
   .principal("principal")
   .password("credentials")
   .open("url");

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

Apple

//  Copyright (C) 2021 Push Technology Ltd.
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//  http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.

import Foundation
import Diffusion

class ConnectingCredentials {

    func connect_credentials_as_object() {
        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.")
        }
    }


    func connect_with_string_as_credentials() {

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


    func connect_with_data_as_credentials(data: Data) {
        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.")
        }
    }

}

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(byte_credentials)
   .Open( "url" );

Java and Android

Session session = Diffusion.sessions()
   .principal("principal")
   .customCredentials(byte_credentials)
   .open("url");

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

Apple

//  Copyright (C) 2021 Push Technology Ltd.
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//  http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.

import Foundation
import Diffusion

class ConnectingCredentials {

    func connect_credentials_as_object() {
        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.")
        }
    }


    func connect_with_string_as_credentials() {

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


    func connect_with_data_as_credentials(data: Data) {
        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 the Diffusion server at any time. For more information, see Change the security principal and credentials associated with your client session.