Vim Docs

Appearance

Authentication implementation guide ​

This guide provides step-by-step instructions for implementing authentication in your Vim OS application. For detailed explanations of concepts and architecture, see the Authentication deep dive.

Prerequisites ​

Before implementing authentication, ensure you have:

  1. An app configured in Vim Console
  2. Your Client ID and Secret from your account page
  3. A backend server ready to handle authentication endpoints

For a detailed overview of the authentication process and its components, see the Authentication Overview.

Implementation options ​

There are two main ways to implement authentication:

  1. Full backend implementation: Recommended for most applications. Provides complete control over the authentication flow and user authorization. See the Authentication sequence for details.

  2. Social login integration: For applications using an Identity Provider. Simplifies the flow by leveraging existing IdP connections. See our guides for Auth0, Okta, Azure AD, and Generic OAuth2.

Full backend implementation ​

1. Set up backend endpoints ​

Your server needs to handle two endpoints. For detailed endpoint specifications, see OAuth 2.0 endpoints.

Launch endpoint ​

js
app.get('/api/launch-app', (req, res) => {
  const launchId = req.query.launch_id;
  const authorizationUrl = new URL('https://api.getvim.com/v1/oauth/authorize');
  authorizationUrl.searchParams.set('launch_id', launchId);
  authorizationUrl.searchParams.set('client_id', clientId);
  authorizationUrl.searchParams.set('redirect_uri', redirectUri);
  authorizationUrl.searchParams.set('response_type', 'code');
  res.redirect(authorizationUrl.toString());
});

Token endpoint ​

js
app.post('/api/generate-token', async (req, res) => {
  const { code } = req.body;
  const vimResponse = await fetch('https://api.getvim.com/v1/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ 
      client_id: clientId, 
      code, 
      client_secret: secret, 
      grant_type: 'authorization_code' 
    }),
  });

  /**
    * At this point, the backend server can use the received id token
    * in order to verify that the Vim user is authorized to use the application.
    * Returning a 403 error code will let the Vim SDK know that the user is not authorized to use the application.
    * In such a case the application will not load.
  **/
  if (!(await isAuthorized(vimResponse))) {
    return res.status(403).send('Forbidden');
  }

  const tokenData = await vimResponse.json();
  res.json(tokenData);
});

For token response format and validation, see ID token contents.

2. Configure CORS ​

CORS configuration is only required if your frontend application and backend server are hosted on different domains. If they're on the same domain, you can skip this step.

If you do need CORS, configure your backend to accept requests from your application's domain:

js
app.use(cors({
  // Allow requests from your application's domain
  origin: process.env.APP_DOMAIN || 'https://your-app-domain.com',
  credentials: true
}));

WARNING

In production:

  1. Always specify the exact domain(s) your application will be served from
  2. Never use origin: * as it allows requests from any domain
  3. Keep your CORS configuration up to date as you add or change frontend domains

3. Initialize the SDK ​

Using script tag ​

js
const vimOS = await window.vimSdk.initializeVimSDK();

Using NPM package ​

js
import { loadSdk } from 'vim-os-js-browser';

async function init() {
  const vimOS = await loadSdk();
}
init();

Social login implementation ​

For applications using an Identity Provider (IdP):

  1. Configure your IdP OAuth 2.0 connection with:

    • Authorize URL: https://api.getvim.com/v1/oauth/authorize
    • Token URL: https://api.getvim.com/v1/oauth/token
    • Required scopes: openid profile email

  2. Implement login in your frontend using your IdP's SDK:

js
// Example using a generic OAuth2 client
async function login(launch_id) {
  const authClient = await createAuthClient({
    authorizeEndpoint: 'https://api.getvim.com/v1/oauth/authorize',
    tokenEndpoint: 'https://api.getvim.com/v1/oauth/token',
    clientId: YOUR_CLIENT_ID,
    redirectUri: YOUR_REDIRECT_URI
  });

  return authClient.authorize({
    login_hint: launch_id,
    scope: 'openid profile email'
  });
}
  1. Initialize SDK with token:

Using script tag ​

js
const vimOs = await window.vimSdk.initializeVimSDK({ 
  accessToken: idpAccessToken 
});

Using NPM package ​

js
import { loadSdk } from 'vim-os-js-browser';

async function initWithToken(idpAccessToken) {
  const vimOs = await loadSdk({
    accessToken: idpAccessToken
  });
  return vimOs;
}

TIP

For detailed implementation guides with specific Identity Providers, see:

Testing ​

Use our Postman collection to test your implementation.

  1. Configure environment variables:

    • authToken: Access token from sandbox EHR
    • appId: Your app ID
    • appVersion: Your app version
    • clientId: Your client ID
    • clientSecret: Your client secret
    • launchEndpoint: Your launch endpoint
    • appTokenEndpoint: Your token endpoint

  2. Run the requests in order:

    • Create App Launch ID
    • Launch
    • Vim OS Authorize Endpoint
    • App Token Endpoint
    • UserInfo Endpoint

For detailed testing guidelines, see Testing in deep dive.

Security best practices ​

  1. Store secrets in environment variables
  2. Implement client secret rotation
  3. Validate ID tokens
  4. Use CORS protection
  5. Implement proper error handling

For detailed security guidelines and architecture explanations, see the Security considerations section in the deep dive.