User Management

Registration

User registration is a 3 step process and only a part of it is done through the SDK. Here we only discuss the SDK related parts, the full registration flow is documented in detail in Common flows.

Registration iframe

This iframe contains two input fields to enter and confirm the user's password. It should be included in the registration form, either added dynamically by the SDK, or insert it manually into the HTML document and then wrapped by the SDK. The SDK wrapper handles the communication with the code running in the iframe and provides the methods below. This wrapped object provides a strict interface to make sure no code running on your site can access the actual password, only some meta-information about it. Through it, the application can register the user on the Tenant Server.

var zkitReg = zkitSdk.getRegistrationIframe(document.getElementById('parentElement'));

or

<iframe src="${serviceUrl}/static/v4/embedded-register.html" id="zkitRegIframe"></iframe>
<script type="text/javascript">
    var zkitRegSDK = ZkitSdk.wrapRegistrationIframe(document.getElementById('zkitRegIframe'));
</script>

Methods of the RegistrationIframeObject:

register(regSessionId: string, userId: string): Promise<{RegValidationVerifier: string}>

This method will read the password fields inside the iframe and check if they match, then registers the user with the provided userId. The regSessionId is used to make sure that your application started the registration process and that the user matches the one that the application started the registration for. The returned promise resolves to the regValidationVerifier which is used during user validation, so it should be saved on the application server.

Parameters:

• regSessionId: The regSessionId provided by the InitUserRegistration API call for the given alias (see Administrative API for details)
• userId: The userId provided by the InitUserRegistration API call for the given alias

Returns:

Promise<{RegValidationVerifier: string}>: This method returns a Promise, that resolves to an object, with a RegValidationVerifier property.

Rejections:

checkPasswordsMatch(): Promise<bool>

This methods check if the passwords match.

Parameters:

Returns:

Promise<bool>: True if the passwords entered in the iframes input fields match.

getPasswordStrength(): Promise<PasswordMetric>

This methods gives meta-information about the password the user entered. Currently returns the length of the password.

Parameters:

Returns:

Promise<PasswordMetric>: Part of the result of running zxcvbn on the password.

login(userId, function(userId: string): Promise<string>

This method is completely analogous to the login method of the LoginIframe and it is provided so that the user could log in after registration, but it has to be noted, that the user has to be validated before it is able to log in. It tries to log the given user in with the password entered into the iframe. This method returns a promise that will resolve to the userId of the logged in user.

Parameters:

• userId: The userId or alias of the user to log in.
• callback: This callback will be called after the user successfully logs in. It's function is described in the summary.

Returns:

Promise<string>: Resolves to the userId of the logged in user. Important: will never resolve if this is done as a part of the IDP login flow, the SDK will redirect instead.

Rejections:

PasswordMetric

The result of the getPasswordStrength method of the registration, password change and link creation iframes. It shows the length, the strength of the passwords and gives estimates of time number of guesses and time required to crack the password. We calculate this by running zxcvbn (https://github.com/dropbox/zxcvbn).

Fields:

• length: Integer showing the length of the password entered
• score: The zxcvbn score of the password: integer from 0 to 4, for exact definitions see the link above
• guesses_log10: The log10 of the estimated number of guesses needed to crack the password.
• crack_times_seconds: The time required to crack the password in different scenarios, based on the above estimate.
• feedback: Some feedback provided by the library.

.

Login

There are multiple types of login, here we only discuss the SDK related parts. Login through IDP and an overview of the different login flows available is provided in Common flows

LoginIframe

The login iframe contains a password input field. It should be included in the login page, either added dynamically by the SDK, or inserted manually into the HTML document and then wrapped by the SDK. The SDK wrapper will handle communication with the code running in the iframe and provide the methods below. Through this object the application can start the client login process. This login will persist across tabs and refreshes.

var zkitLogin = zkitSdk.getloginIframe(document.getElementById('parentElement'));

or

<iframe src="${serviceUrl}/static/v4/embedded-register.html" id="zkitLoginIframe"></iframe>
<script type="text/javascript">
    var zkitLogin = zkitSdk.wrapLoginIframe(document.getElementById('zkitLoginIframe'));
</script>

Methods of the LoginIframe object

login(userId: string, callback: (userId: string, willRedirect: bool) => any): Promise<string>

This method tries to log the given user in with the password entered into the iframe. If the login is a part of the IDP login flow, the SDK will redirect the user back to the IDP login process, then, after a few steps back to the page that requested the login. The callback parameter is a function that will always be called after the user successfully logs in. It will get the userId of the user and a bool value indicating if the SDK will redirect as parameters. If it returns a promise, the redirection will be delayed until that Promise resolves, otherwise it redirects immediately after the function returns. The login method returns a promise that will resolve to the userId of the logged in user if and only if there is no need for a redirection.

Parameters:

• userId: The userId or alias of the user to log in.
• callback: This callback will be called after the user successfully logs in. It's function is described in the summary.

Returns:

Promise.<string>: Resolves to the userId of the logged in user. Important: it will never resolve if this is done as a part of the IDP login flow, the SDK will redirect instead.

Rejections:

.

Password change

Changing the password needs a completely freshly entered password along with the new password and a confirmation.

ChangePasswordIframe

The password change iframe contains a password input field to for the current password and two for the new password and the confirmation. It can either be added dynamically by the SDK, or inserted manually into the HTML document and then wrapped by the SDK. The SDK wrapper will handle communication with the code running in the iframe and provide the methods below. Through this object the application can start the password change process.

var zkitChangePassword = zkitSdk.getChangePasswordIframe(document.getElementById('parentElement'));

or

<iframe src="${serviceUrl}/static/v4/embedded-changePassword.html" id="zkitChangePasswordIframe"></iframe>
<script type="text/javascript">
    var zkitChangePassword = zkitSdk.wrapChangePasswordIframe(document.getElementById('zkitChangePasswordIframe'));
</script>

Methods of the ChangePasswordIframe object

changePassword(userId): Promise<string>

This method logs into a security session and changes the password of the user.

Parameters:

• userId: Optional parameter to specify the id of the user changing password. This is only required if the user is not logged in.

Returns:

Promise<string>: Resolves to the id of the user.

Rejections:

checkPasswordsMatch(): Promise<bool>

This methods check if the passwords match.

Parameters:

Returns:

Promise<bool>: True if the passwords entered in the iframes input fields match.

getPasswordStrength(): Promise<PasswordMetric>

This methods gives meta-information about the password the user entered. Currently returns the length of the password.

Parameters:

Returns:

Promise<PasswordMetric>: Part of the result of running zxcvbn on the password. The result type is defined in the registration section.