Invitation Links

Invitation links are used to invite someone into a tresor who is not a registered user. This method of invitation is made this way to communicate a best-practice. Using the link format below (placing the secret inside the fragment identifier of the url) you can ensure that the credentials necessary to get access to the tresor doesn't travel to your server and subsequently through the network. We advise, that you don't store any of the invitation links on your server unencrypted as it is a security critical information, which, in case of a breach, can be used to get access to user data. Even so, to achieve the best security you should use only password protected links and ask the users to transfer the password and the link to the invitee through different channels (e.g.: email the link and text/phone the password).

You can create an invitation link with no password through the basic api, but password protected links have to be created through an iframe, since the user has to enter a password. You can load and wrap the iframe by calling getCreateInvitationLinkPasswordIframe or just wrap a manually loaded one with wrapCreateInvitationLinkPassword both of which return a wrapper object described below.

createInvitationLinkNoPassword(linkBase: string, tresorId: string, message: string): Promise<{url: string, id: string}>

Creates an invitation link that can be used by anyone to gain access to the tresor. The secret that can be used to open the invitation link is concatenated to the end of the link after a '#'. We recommend that you use password protected links. This operation needs administrative approval.

Parameters:

  • linkBase: the base of the link. The link secret is appended to this after a '#'
  • tresorId: the id of the tresor
  • message: optional arbitrary string data that can be retrieved without a password or any other information

Returns:

Promise<{url: string, id: string}>: Resolves to the operation id and the url of the created link. The operation must be approved before the link is enabled.

var createLinkIframe = zkitSdk.getCreateLinkPasswordIframe(document.getElementById('placeholder'));

or

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

Methods of the iframe

createInvitationLink(linkBase:string, tresorId:string, message:string?): Promise<{url: string, id: string}>

This method creates an invitation link with the password entered into the iframe.

Parameters:

  • linkBase: the base of the link. The link secret is appended to this after a '#'
  • tresorId: the id of the tresor
  • message: optional arbitrary string data that can be retrieved without a password or any other information

Returns:

Promise<{url: string, id: string}>: Resolves to the operation id and the url of the created link. The operation must be approved before the link is enabled.

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 at the end of the registration section.

You can get some information about the link by calling getInvitationLinkInfo with the link secret. The secret is in the fragment identifier of the link. The returned object contains a token necessary to accept the invitation. This also is a client side secret, that should never be uploaded to your site as that would compromise the zero knowledge nature of the system by providing ways to open the tresor if the link was not password protected.

class InvitationLinkPublicInfo

This represents the information that can be retrieved by the sdk without the password of the link, public in a sense that anyone in possession of the link can view it.

Fields:

  • creatorUserId: the user id of the creator of this link
  • isPasswordProtected: bool value indicating if the link is password protected
  • message: arbitrary string data set at the time of creation of the link
  • $token: link information for internal use, used as a parameter for acceptInvitationLink

getInvitationLinkInfo(secret: string): Promise<LinkPublicInfo>

Retrieves information about the link.

Parameters:

  • secret: The secret is the one that was concatenated to the end of the url in createInvitationLink.

Returns:

Promise<LinkPublicInfo>: Resolves to all the information available.

A link with no password can be accepted by any logged in user that has access to the token returned by getInvitationLinkInfo through the basic sdk. Passworded links work the same way, but the user has to enter the password into an iframe. Loading and wrapping this iframe is done in much the same way as the others.

acceptInvitationLinkNoPassword(token: LinkToken): Promise<string>

This method will add the user to the tresor of the link.

Parameters:

  • token: The token is the $token field of the InvitationLinkPublicInfo of the link returned by getInvitationLinkInfo.

Returns:

Promise<string>: Resolves to the operation id that must be approved for the operation to be effective.

var acceptLinkIframe = zkitSdk.getAcceptLinkPasswordIframe(document.getElementById('placeholder'));

or

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

Methods of the iframe

acceptInvitationLink(token: Object): Promise<string>

This method will add the user to the tresor of the link using the password entered into the iframe. This operation need administrative approval.

Parameters:

  • token: The token is the $token field of the InvitationLinkPublicInfo of the link returned by getInvitationLinkInfo.

Returns:

Promise<string>: Resolves to the operation id that must be approved for the operation to be effective.

Invitation links can be revoked, but to do this the user has to be both a member of the tresor and have the link secret.

revokeInvitationLink(tresorId: string, secret: string): Promise<string>

Revokes the link from the tresor with the secret provided

Parameters:

  • tresorId: the id of the tresor
  • secret: The secret is the one that was concatenated to the end of the url in createInvitationLink.

Returns:

Promise<string>: Resolves to the operation id that must be approved for the operation to be effective.

results matching ""

    No results matching ""