Change the security principal and credentials associated with your client session

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

JavaScript

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

.NET

bool result = await session.Security.ChangePrincipalAsync("control", Diffusion.Credentials.Password("password"));

Java and Android

final Session session = Diffusion.sessions().open("ws://localhost:8080");
final Security security = session.feature(Security.class);

security.changePrincipal(
    "principal",
    Diffusion.credentials().password("password"));

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

// 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 are re-evaluated. The session is unsubscribed from any topic the new principal does not have permissions for, and will be subscribed to new topics that it now does have permissions for.