Just a second...

Change the security principal and credentials associated with your client session

A client session can change the credentials it uses to authenticate with Diffusion™ Cloud at any time.

JavaScript
await session.security.changePrincipal('principal', 'password');
console.log('Authenticated as admin');

.NET

security = session.Security;
security.ChangePrincipal( principal, Diffusion.Credentials.Password( password ), callback );
                    
Java and Android
security = session.feature(Security.class);
security.changePrincipal(
    principal,
    Diffusion.credentials().password(password),
    callback);
                    
C
static int principal_change_success(SESSION_T *session, void *context)
{
        // principal has been successfully changed
        return HANDLER_SUCCESS;
}


static int principal_change_failure(SESSION_T *session, void *context)
{
        // principal change has failed
        return HANDLER_SUCCESS;
}


void change_principal_for_session(
        SESSION_T *session,
        const char *new_principal,
        const char *new_password)
{
    CREDENTIALS_T *new_credentials = credentials_create_password(new_password);

    CHANGE_PRINCIPAL_PARAMS_T params = {
            .principal = new_principal,
            .credentials = new_credentials,
            .on_change_principal = principal_change_success,
            .on_change_principal_failure = principal_change_failure
    };
    change_principal(session, params);
    credentials_free(new_credentials);
}
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 ChangingCredentials {

    func change_credentials(session: PTDiffusionSession) {
        // create a credentials object encapsulating a string password
        let credentials = PTDiffusionCredentials(password: "password")

        // use the security feature from your session
        session.security.changePrincipal("principal",
                                         credentials: credentials) { (error) in

            // Check error is `nil`, then use session as required.
            if (error != nil) {
                print("Failed to change principal: %@", error!.localizedDescription)
                return
            }
        }
    }

}
When the principal associated with a session changes, the following happens:
  • The $Principal session property is updated to contain the new principal.
  • The roles associated with the old principal are removed from the session and those roles associated with the new principal are assigned to the session.
  • Topic subscriptions made with the old principal are not re-evaluated. The session remains subscribed to any topics the new principal does not have permissions for.