Authentication deep dive

This document provides a detailed explanation of authentication concepts and architecture in Vim OS. For implementation instructions, see the Authentication implementation guide.

Overview

The authentication process in Vim OS has three key objectives:

Secured EHR access: Ensure applications can only access authorized Electronic Health Records (EHR) resources.
Third-party authentication: Enable Single Sign-On (SSO) through trusted Identity Providers.
SDK authorization: Delegate authorization to applications through secure token exchange.

OAuth 2.0 in Vim OS

Vim OS implements OAuth 2.0 with the following roles:

Resource owner

The healthcare provider or organization that owns the EHR data
Controls access to protected resources through permissions and scopes

Resource server

The Vim OS API that hosts protected resources
Validates access tokens and enforces scope-based permissions

Client

Your application that needs access to Vim OS resources
Requests authorization and manages tokens

Authorization server

Vim's OAuth 2.0 server that issues tokens
Handles authentication and authorization flows
Supports OpenID Connect for identity verification

OpenID Connect integration

Vim OS extends OAuth 2.0 with OpenID Connect to provide:

ID tokens: JWT tokens containing user identity information
UserInfo endpoint: Additional user profile data
Standard claims: Normalized user attributes

ID token contents

json

{
  "https://getvim.com/ehrUsername": "[email protected]",
  "https://getvim.com/organizationId": "123",
  "https://getvim.com/applicationContext": "vim-os-app",
  "nickname": "johndoe",
  "name": "John Doe",
  "picture": "https://s.gravatar.com/avatar/example123?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fjd.png",
  "updated_at": "2025-04-03T06:35:19.890Z",
  "email": "[email protected]",
  "email_verified": true,
  "iss": "https://auth.getvim.com/",
  "aud": "{{yourClientId}}",
  "sub": "auth0|123456789abcdef",
  "iat": 1743662119,
  "exp": 1743698119
}

The ID token contains the following claims:

Vim-specific claims:
- ehrUsername: The username in the EHR system
- organizationId: The unique identifier for the organization
- applicationContext: The context in which the token is being used. This can be either vim-os-app or app-settings.
User profile claims:
- nickname: User's nickname
- name: User's full name
- picture: URL to user's profile picture
- email: User's email address
- email_verified: Whether the email has been verified
Standard JWT claims:
- iss (Issuer): The token issuer URL - will always be https://auth.getvim.com
- aud (Audience): The client ID the token is intended for - will always be the client ID from your Vim account
- sub (Subject): Unique identifier for the user
- iat (Issued At): Timestamp when the token was issued
- exp (Expiration): Timestamp when the token expires

UserInfo response

json

{
  "sub": "user123",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "email": "[email protected]",
  "email_verified": true,
  "organization": {
    "id": "org123",
    "name": "Medical Group Inc",
    "type": "provider"
  }
}

Authentication sequence

Pre-conditions

User authenticates to Vim and Vim OS loads
Application registered in Vim Console
Client ID and Secret obtained
Redirect URI configured
Backend endpoints implemented

Flow steps

Launch endpoint
- Vim OS starts the app loading process
- Calls the app launch endpoint URL (configured in Developer Console)
- Launch endpoint redirects to Vim's authorization endpoint with required parameters
Authorization Server
- Vim's authorize endpoint issues an authorization code
- Redirects to the verified redirect_uri (App's main page)
- Authorization code included as query parameter in URL
App initialization
- App code loads and initializes VimOS instance
- SDK retrieves authorization code from URL query parameters
- SDK calls app backend token endpoint with authorization code
Token exchange
- App backend calls Vim OS token endpoint with:
  - Authorization code
  - App's client ID
  - App's client secret
- Vim OS returns access token and ID token to app backend
User authorization
- App backend identifies and authorizes user using:
  - ID token verification
  - Optional UserInfo endpoint calls
- Backend returns both access token and ID token to SDK
Secure communication
- SDK verifies access token
- Establishes secure communication channel between VimOS and Application
- Maintains secure session
SDK initialization completion
- SDK resolves init process
- Provides application with ID token
- ID token is exclusively generated for the application
Optional SSO
- Application can use ID token for SSO
- Generate application-specific access token
- Use token for internal API calls

OAuth 2.0 endpoints

Authorization endpoint

GET https://api.getvim.com/v1/oauth/authorize

Parameters:

launch_id: Launch context identifier
client_id: Your application's client ID
redirect_uri: Must match registered URI
response_type: Always "code"
state: Optional security parameter

Token endpoint

POST https://api.getvim.com/v1/oauth/token

Parameters:

code: Authorization code
client_id: Your application's client ID
client_secret: Your application's secret
grant_type: "authorization_code"

Response:

json

{
  "access_token": "eyJ0...",
  "id_token": "eyJ1...",
  "token_type": "Bearer",
  "expires_in": 3600
}

UserInfo endpoint

GET https://api.getvim.com/v1/oauth/userinfo

Headers:

Authorization: Bearer

Auth0 social login integration

Auth0 can be configured as an Identity Provider for Vim OS applications:

Connection setup
- Configure OAuth 2.0 connection
- Set authorize and token URLs
- Configure scopes
Profile mapping

javascript

function(user, context, callback) {
  context.idToken['https://vim.com/organization_id'] = user.organization_id;
  context.idToken['https://vim.com/permissions'] = user.app_metadata.permissions;
  callback(null, user, context);
}

Token exchange
- Auth0 token exchanged for Vim token
- Permissions mapped to Vim scopes
- Session established with Vim OS

Okta integration

Okta can be configured as an Identity Provider for Vim OS applications:

Application setup
- Create a new OpenID Connect application in Okta
- Configure Sign-in redirect URIs
- Set up authorization server policies
Connection configuration

json

{
  "authorization_endpoint": "https://api.getvim.com/v1/oauth/authorize",
  "token_endpoint": "https://api.getvim.com/v1/oauth/token",
  "userinfo_endpoint": "https://api.getvim.com/v1/oauth/userinfo",
  "scopes": ["openid", "profile", "email"]
}

Profile mapping

javascript

const oktaConfig = {
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  clientId: '{clientId}',
  redirectUri: window.location.origin + '/login/callback',
  scopes: ['openid', 'profile', 'email']
};

const oktaAuth = new OktaAuth(oktaConfig);

async function login(launch_id) {
  const tokens = await oktaAuth.signInWithRedirect({
    sessionToken: launch_id
  });
  return tokens;
}

Azure AD integration

Azure Active Directory can be configured for Vim OS authentication:

App registration
- Register a new application in Azure Portal
- Configure platform settings for web application
- Add redirect URIs
- Configure API permissions
Connection setup

json

{
  "authority": "https://login.microsoftonline.com/{tenantId}",
  "client_id": "{clientId}",
  "redirect_uri": "{redirectUri}",
  "scopes": ["openid", "profile", "email"]
}

MSAL implementation

javascript

const msalConfig = {
  auth: {
    clientId: '{clientId}',
    authority: 'https://login.microsoftonline.com/{tenantId}',
    redirectUri: window.location.origin + '/login/callback'
  }
};

const msalInstance = new msal.PublicClientApplication(msalConfig);

async function login(launch_id) {
  const loginRequest = {
    scopes: ['openid', 'profile', 'email'],
    loginHint: launch_id
  };
  
  return msalInstance.loginRedirect(loginRequest);
}

Generic OAuth2 implementation

For custom OAuth2 implementations or other Identity Providers:

Provider configuration

javascript

const config = {
  authorizeEndpoint: 'https://api.getvim.com/v1/oauth/authorize',
  tokenEndpoint: 'https://api.getvim.com/v1/oauth/token',
  userinfoEndpoint: 'https://api.getvim.com/v1/oauth/userinfo',
  clientId: YOUR_CLIENT_ID,
  redirectUri: YOUR_REDIRECT_URI,
  scopes: ['openid', 'profile', 'email']
};

Authorization flow

javascript

async function initiateAuth(launch_id) {
  const authUrl = new URL(config.authorizeEndpoint);
  authUrl.searchParams.set('client_id', config.clientId);
  authUrl.searchParams.set('redirect_uri', config.redirectUri);
  authUrl.searchParams.set('response_type', 'code');
  authUrl.searchParams.set('scope', config.scopes.join(' '));
  authUrl.searchParams.set('login_hint', launch_id);
  
  window.location.href = authUrl.toString();
}

async function handleCallback(code) {
  const response = await fetch(config.tokenEndpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: config.clientId,
      client_secret: config.clientSecret,
      code,
      grant_type: 'authorization_code',
      redirect_uri: config.redirectUri
    })
  });
  
  return response.json();
}

Token exchange

javascript

async function exchangeToken(idpToken) {
  const response = await fetch('your-backend/exchange-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: idpToken })
  });
  
  const { vimToken } = await response.json();
  return vimToken;
}

Security considerations

Token security
- Store tokens securely
- Never expose in client-side storage
- Implement proper token rotation
ID token verification
- Verify signature using JWKS
- Validate issuer and audience
- Check expiration time
- Verify required claims
Error handling
- Handle token expiration
- Implement refresh flow
- Log security events
- Monitor for suspicious activity

Testing

Sandbox environment

Use Vim Sandbox EHR for testing
Test with different user roles
Verify error scenarios
Test token expiration

Postman collection

Set environment variables
Run authentication flow
Verify token responses
Test error conditions

Client secret rotation

Implement secret rotation for enhanced security:

Generate new secret
- Request new secret from Vim Console
- Store securely in environment
Transition period
- Keep both old and new secrets
- Try new secret first
- Fall back to old if needed
Complete rotation
- Monitor for old secret usage
- Remove old secret when unused
- Update monitoring alerts

For implementation details, see the Authentication implementation guide.

Authentication deep dive ​

Overview ​

OAuth 2.0 in Vim OS ​

Resource owner ​

Resource server ​

Client ​

Authorization server ​

OpenID Connect integration ​

ID token contents ​

UserInfo response ​

Authentication sequence ​

Pre-conditions ​

Flow steps ​

OAuth 2.0 endpoints ​

Authorization endpoint ​

Token endpoint ​

UserInfo endpoint ​

Auth0 social login integration ​

Okta integration ​

Azure AD integration ​

Generic OAuth2 implementation ​

Security considerations ​

Testing ​

Sandbox environment ​

Postman collection ​

Client secret rotation ​

Authentication deep dive

Overview

OAuth 2.0 in Vim OS

Resource owner

Resource server

Client

Authorization server

OpenID Connect integration

ID token contents

UserInfo response

Authentication sequence

Pre-conditions

Flow steps

OAuth 2.0 endpoints

Authorization endpoint

Token endpoint

UserInfo endpoint

Auth0 social login integration

Okta integration

Azure AD integration

Generic OAuth2 implementation

Security considerations

Testing

Sandbox environment

Postman collection

Client secret rotation