Back to docs index

How to connect your application with the Vipassana Identity Server

• Benefits of using VIS
• What VIS does NOT handle
• Using the staging server
• Delegating the authentication to VIS
• Migrating existing user accounts to VIS
• Defining the user registration flow
• Handling user account updates and deletions
• Propagating updates from your application to VIS
• Handling user merges
• Integrating the VIS User Credentials Page

You can delegate the authentication of your application to Vipassana Identity Server (VIS), so that you don't have to manage passwords, account recovery, profile update, etc.

When a user logs into your application, they are redirected to VIS for authentication. VIS then returns proof of successful authentication, along with the user's data.

To integrate VIS, follow these steps:

• contact [email protected] or [email protected] to obtain OAuth credentials for your application and access your application OAuth configuration in the VIS UI
• update your codebase to delegate authentication to VIS
• migrate the existing user accounts of your application to VIS
• define the user registration flow
• handle data synchronization between your application and VIS

Benefits of using VIS

• Users with a VIS account don’t need new credentials to access your application
• VIS handles authentication security
• You can customize the authentication experience in several ways, such as:
  • require a multi-factor authentication
  • display custom messages on the VIS login page
  • allow authentication through Office 365, GMail or an Apple account
  • etc. See the OAuth Parameters documentation for all options

What VIS does NOT handle

VIS stores only generic user attributes, see the list here. Your application must store additional attributes in its own database. Your application can also store and duplicate these generic attributes in its own database, but in that case it must handle the syncing of these attributes with VIS (see subsequent sections).

The VIS UI allows users to update only their email, username, and password. All the other generic attributes are managed by the applications connected to VIS. When possible, it is better to let the applications handling student registration (myCourses, dhamma.org) manage these other generic attributes. A user’s preferred registration application depends on their primary_country attribute.

Each VIS user has a UUID. Your application must store it to map its local user records to VIS users.

VIS doesn’t handle authorization. It only confirms whether a user is authenticated.

Using the staging server

Use the VIS staging website to test changes before switching your production application to VIS.

To prevent accidental communication the staging server does not deliver emails triggered by API endpoints.

The staging server delivers emails triggered by end user:

• password reset email: can be sent from https://test.identity.dhamma.org/en/users/password/new
• invitation email: can be resend from https://test.identity.dhamma.org/en/help after entering the email. If the user has a pending invitation, they can click the "Resend invitation instructions" email.
• confirmation email: can be resend from https://test.identity.dhamma.org/en/users/confirmation/new
• account merging confirmation email

Delegating the authentication to VIS

You must use the OAuth 2 Authorization Code Flow. First your application should redirect users to the VIS authorization endpoint https://identity.dhamma.org/oauth/authorize. Here is an URL example:

https://identity.dhamma.org/oauth/authorize?client_id=XXX&locale=en&redirect_uri=YYY&response_type=code&scope=default&state=ZZZ

Major programming languages have online implementation guides and open-source OAuth 2 client librairies (see OAuth librairies). AI assistants can also help implement the OAuth 2 Authorization Code Flow.

At the end of this OAuth flow your application POSTs to the VIS /oauth/token endpoint and receives a JWT token in the JSON response body access_token key. Your application can decode this token to get the user data. Here is how the omniauth_vis gem handles for ruby applications. Alternatively your application can request /api/v1/me.json to get the user data.

Migrating existing user accounts to VIS

You can bulk-create user records in VIS through the bulk_create API endpoint.

Note that users will be emailed to confirm their email address unless you set the API parameter email_confirmed to true.

Defining the user registration flow

You can let users self-register in VIS when they authenticate for the first time. For this, set the allow_sign_up to true (see the OAuth Parameters documentation). They will create their VIS account on the VIS Sign Up page. Once the user is redirected back to your application, it is up to you to create a user record in your application's database and implement further registration steps if needed.

If self-registration doesn’t suit your application, you can implement the user creation in your application codebase. Then use the API Invite endpoint to let the user complete their registration on VIS. This endpoint creates a User record in the VIS database and sends a confirmation to the user, unless the user already has a VIS account. The endpoint returns the VIS user payload to your application, including the VIS user identifier.

Handling in your application the user account updates and deletions which happen in VIS

User Attribute Updates

VIS user attributes can be updated in VIS by the users themselves or by another application. For example, a user can change their email in the VIS UI, or their family name in another application.

After authenticating on VIS, the user is redirected to your application with their attributes in the payload. It is up to your application to compare these attributes with any values stored in its database and update them accordingly.

Sometimes it is better not to wait for the next user authentication to update the attributes stored in your application. For example, if a user updates their email, you may want your application to update the email as soon as it is changed in VIS. See the Webhooks doc to achieve that.

In any case, when your application applies locally updates coming from VIS, make sure your application does not propagate these changes back to VIS.

User Deletions

A VIS user record can be deleted permanently, e.g. on a privacy request. Your application will know about this deletion only if you enable a deletion webhook. See the Webhooks doc.

Propagating User Updates or Deletions from Your Application to VIS

Use the VIS API.

Make sure your application does not propagate user updates to VIS when these updates originally came from VIS.

When you send a user deletion API request, the VIS user record is deleted only if it’s linked exclusively to your application. If the user is mapped to other applications, only the VIS mapping between the user record and your application will be deleted.

Handling User Merges

A user may have multiple VIS user accounts. Each time a user logs into VIS, VIS searches for other VIS user accounts that may belong to the same user. This search compares email addresses, names, birth dates, and other attributes.

If potential duplicates are found, VIS offers the user the option to merge these accounts into a single one. For the merge to proceed, the user must prove they own these accounts through an email challenge. The user can also choose to not merge, and VIS will remember this choice.

Once the merge is completed, the merged accounts are marked as inactive in VIS, and the user is left with a single active account.

VIS notifies your application when such merges happen if you enable the "user merge" webhook. See the Webhooks doc.

Conversely, if your application merges user records and these records are mapped to VIS user records, you should use the Delete User API endpoint to remove the merged records from VIS.

Integrating the VIS User Credentials Page in Your Application

The VIS UI includes a Credentials page where users can update their email and password.

You can integrate this page directly in your application through an iframe:

<iframe scrolling="no" src="https://identity.dhamma.org/en/users/credentials?iframe=true" style="height: 200px;"></iframe>

along with this JavaScript code:

// Listen to some message sent by child iframe (used by VIS)
window.addEventListener('message', (message) => {
  if (message.data.event == 'height') {
    const event = message.data
    const selector = event.iframeName ? `iframe[name="${event.iframeName}"` : 'iframe'
    const iframe = document.querySelector(selector)
    iframe.style.height = `${event.value}px`
  }

  // Some links does not work inside iframe (for external SSO providers)
  // the redirectuon should happen in the main window
  if (message.data.event == 'redirect') {
    window.location.href = message.data.href
  }
})