Authentication

The authentication module does offer you a full authentication service, which you can adapt to your existing application. Simply import the module and start using the functions.

Get started

To install the package on your existing node project, just hit the following command into the terminal.

npm install schmucklicloud_auth

After you have installed the package, initialize now the ˋsCAuthˋ object from the package. Provide also the app ID and secret from the schmuckliCloud console in the constructor.

import { sCAuth } from "schmucklicloud_auth";

var reference = new sCAuth("YOUR_APP_ID", "YOUR_APP_SECRET");

Now you are all set to use all the function to provide a full authentication service for your users.

Get started (without npm)

If you are not using npm, you also can use the unpacked version of the package. Just include the script tag at the end of the body tag.

<script src="https://unpkg.com/schmucklicloud_auth/dist/min.js" type="text/javascript"></script>

After that you are able to access the schmuckliCloud instance. Now you only have to initialize the object sCAuth with your app ID and secret.

var reference = new schmuckliCloud.sCAuth("YOUR_APP_ID", "YOUR_APP_SECRET");

Notice

Please note, that the authentication library is only for the background processing. You have to provide your own UI and send then the data retrieven from the user to the function.

Also before you start, please make sure that you have setup all the configuration in the schmuckliCloud console in order to use the full functionality of this documentation.

Currently, you only can authenticate your users by the given email and a password. In the future, it is planned to authenticate via Google or Microsoft. In this documentation, only the process for the email/password solution is described.

Register a new user

To register a user you have to provide a email and a unhashed password, which was given from your user.

reference.registerEmailPassword(email, password, language).then(function(response){
    if (response.isOK()) {
        //The user has been registered successfully
    } else {
        //There was a problem. Call the response.message property to get more information.
    }
}).catch(function(error){
    //There was an unexpected error
});

You see that you also can provide a language code. By default, it will set the language to English (en). You have to identify the language by yourself, since the package can be used in various projects. If the user is German for example, you have to set the language to 'de'.

The language is also necessary because you can customize the welcome emails in the schmuckliCloud console in different languages. So the user will get then also the email in his language.

Authorize a user

To authenticate the user with email and password, create another UI and forward then the parameters to the following function:

let session_token;

reference.authorizeEmailPassword(email, password).then(function(response){
    if(response.isOK) {
        //The user has been authenticated successfully.
        session token = response.data.session_token;
    } else {
        //An expected error was thrown. Check the error message in the response.message property.
    }
}).catch(function(error){
    //An unexpected error was thrown.
});

If the user has provided correct credentials, then you will get a session token in the data object. This session token lasts forever, until the user decides to sign out manually or removes the session from the account settings for example.

Check the current session

It is sometimes useful in your app, if you check first, if the session, in which the user is logged in, still valid. Call this method for example at the startup of your application. Therefore you can redirect the user directly to the login form, if the session is not valid anymore.

reference.checkSession(token).then(function(response) {
    if(response.isOK) {
        //The session token is still valid and can be used for further operations.
    } else {
        //The token is not valid anymore and the user should be able to relogin.
    }
}).catch(function (error) {
    //There was an unexpected error.
});

Get user detailed information

If you want more information about the user like email, then you just have to call the following line:

reference.getUserDetails(token).then(function(response) {
    if(response.isOK) {
        // Fetch in the response data object the given elements. 
        console.log(response.data.email);
    } else {
        //The token is not valid anymore and the user should be able to relogin.
    }
}).catch(function (error) {
    //There was an unexpected error.
});

Update a password

You have the option to set a new password also, when the user actually is already logged in. You can offer this option for example in the account settings.

reference.updatePassword(email, old_password, new_password).then(function(response) {
    if (response.isOK) {
        //The password for the user has been updated and the old password is not valid anymore.
    } else {
        //There was something missing. The password is still the old password. Nothing has changed.
    }
}).catch(function(error) {
    //There was an unexpected error
});

As the first parameter, provide the email of the user, where the password should be updated. Normally you should pass the currently logged in user. You can get the email address with the ˋgetUserDetailsˋ function. As a second parameter, send the current active password of the user. Let the user type in that password before he can set a new password. As the third parameter pass the new password. For best practices, you should ask the user twice to type in the password. When he wants to change the password, it will be validated if the two new passwords are identical. Only then it calls the function. You have to send the passwords unhashed as a parameter.

Request reset of a password

Sometimes, when the user doesn't know the user password of his account anymore, he usually is able to reset the password by himself. For being able to do that, the authentication solution also provides the reset password mechanism.

reference.requestResetPassword(email).then(function(response) {
    if (response.isOK) {
        //There was an user with this email and the reset mail has been sent.
    } else {
        //There was an expected error
    }
}).catch(function(error) {
    //There was an unexpected error
});

After the request was successful, the user will now receive the reset email, which can also be customized in the schmuckliCloud console. If the user then clicks on the link, he will get redirected to the reset page.

Update a password from a reset request

After an user has clicked the link in the reset email, you have to provide a form where they can define a new password. It's recommended, to place two input fields for the new password. The second should be repetition of the new password. With this you avoid that the user don't forget the password again in the near future.

After he has entered the password, submit the unhashed password together with the hash token, which can be retrieved from the query parameter 'token' in the URL (GET).

reference.updateResetPassword(reset_token, new_password).then(function (response){
    if (response.isOK) {
        //The password has been updated.
    } else {
        //There was an excpected error.
    }
}).catch(function (error) {
    //There was an unexpected error.
});

Activate a new user

Before an user can use his new created account, he first has to activate the account via the link, which was sent with the welcome mail.

reference.activateUser(token).then(function (response) {
    if (response.isOK) {
        //The account has been activated.
    } else {
        //There was an expected error.
    }
}).catch(function (error) {
    //There was an unexpected error.
});

You can get the token like the reset password option via the query parameter 'token'.

Get active sessions

With a simple function call, you can get all the active sessions from the currently signed in user.

reference.getActiveSessions(current_auth_token).then(function(response) {
    if (response.isOK) {
        // You find all the sessions now in response.data;
    } else {
        // There was an expected error.
    }
});

Sign out the current user

It's important to sign out the user correctly when they want to do the action. This is not done just locally! It also has to be done on the server, that the token becomes invalid.

reference.logout(current_auth_token).then(function(response) {
    if (response.isOK) {
        // The session token is now invalid.
    } else {
        // There was an unexpected error
    }
});

Remove a session

When you want to show all the active session for example in the user settings, then the user maybe wants to delete these sessions also remotely, that they can ensure, that they are only signed in on the own devices.

// The session id can be fetched from the getActiveSessions function.
reference.removeSession(current_auth_token, session_id).then(function (response) {
    if (response.isOK) {
        // The session has been deleted.
    } else {
        // There was an unexpected error.
    }
});