FHIRVINE-Smart-Proxy/USERGUIDE.md

FHIRVINE SMART Proxy User Guide

Introduction

FHIRVINE is a SMART on FHIR proxy that simplifies the integration, testing, and configuration of SMART applications with FHIR servers. This guide provides a comprehensive overview of all features, API endpoints, and use cases to help developers and administrators effectively use FHIRVINE.

Features Overview

App Gallery

• Purpose: Register, view, edit, and delete SMART applications.
• Access: Navigate to /app-gallery from the homepage.
• Functionality:
  • Register new apps with details like name, redirect URIs, scopes, and logo.
  • Edit existing app details.
  • Delete apps and associated tokens.
  • Test apps using temporary registrations (24-hour expiry).

Test Client Mode

• Purpose: Simulate a SMART app client to test OAuth2 authentication flows.
• Access: Navigate to /test-client.
• Functionality:
  • Select a registered app by Client ID.
  • Choose response mode: inline (display response on page) or redirect (send to app’s redirect URI).
  • Initiate an OAuth2 authorization flow, grant consent, and view the resulting authorization code or token.

Test Server Mode

• Purpose: Simulate a SMART on FHIR server to test app interactions.
• Access: Navigate to /test-server.
• Functionality:
  • Input Client ID, Client Secret, Redirect URI, and scopes.
  • Initiate an OAuth2 flow, grant consent, and receive an access token and refresh token.
  • View token details and test token exchange.

Configuration Menu

• Purpose: Customize FHIRVINE’s behavior through a user-friendly interface.
• Access: Navigate to /configure/security, /configure/proxy-settings, or /configure/server-endpoints.
• Submenus:
  • Security Settings:
    • Configure access token duration (seconds).
    • Configure refresh token duration (seconds).
    • Set allowed OAuth2 scopes.
  • Proxy Settings:
    • Set the upstream FHIR server URL.
    • Adjust the proxy request timeout (seconds).
  • Server Endpoints:
    • Define the metadata endpoint path.
    • Define the capability statement endpoint path.
    • Define the base resource endpoint path.

API Documentation

• Purpose: Explore and test FHIRVINE’s API endpoints.
• Access: Navigate to /apidocs.
• Functionality:
  • View all available API endpoints with descriptions.
  • Test endpoints directly from the Swagger UI.

Web Interface Usage

Homepage

• URL: /
• Description: The landing page provides an overview of FHIRVINE and navigation links to key features.
• Actions:
  • Click "Explore Apps" to access the App Gallery.
  • Click "Test Client" to test as a client.
  • Click "Test Server" to test as a server.
  • Click "Configure" to access the configuration menu.

Registering a New App

1. Go to /app-gallery.
2. Click "Register New App".
3. Fill in the form:
   • Application Name: e.g., "My SMART App".
   • Redirect URIs: Space-separated list (e.g., https://myapp.com/callback).
   • Allowed Scopes: Space-separated (e.g., patient/*.read openid).
   • Logo URI, Contacts, Terms of Service URI, Privacy Policy URI: Optional fields.
4. Submit the form to receive a Client ID and Client Secret.

Testing an App as a Client

1. Go to /test-client.
2. Select a Client ID from the dropdown (populated from registered apps).
3. Choose a response mode:
   • Inline: View the response on the page.
   • Redirect: Redirect to the app’s URI with the authorization code.
4. Click "Launch Test" to initiate the OAuth2 flow.
5. On the consent page (/oauth2/authorize), click "Allow" to proceed.
6. View the authorization code or token response.

Testing as a Server

1. Go to /test-server.
2. Enter:
   • Client ID: From a registered app.
   • Client Secret: From registration.
   • Redirect URI: App’s callback URL.
   • Scopes: Space-separated scopes to request.
3. Click "Initiate Authorization".
4. Grant consent on the /oauth2/authorize page.
5. Receive and view the access token, refresh token, and token request details.

Configuring Settings

• Security Settings (/configure/security):
  • Adjust token durations and scopes, then save.
• Proxy Settings (/configure/proxy-settings):
  • Set the FHIR server URL and timeout, then save.
• Server Endpoints (/configure/server-endpoints):
  • Define endpoint paths, then save.

API Endpoints

Overview

FHIRVINE exposes several API endpoints under the /oauth2 prefix, documented via Swagger UI at /apidocs. Below are the key endpoints and their use cases.

1. Well-Known SMART Configuration

• Endpoint: GET /.well-known/smart-configuration
• Description: Provides the SMART on FHIR configuration for discovery.
• Use Case: Apps use this to discover FHIRVINE’s OAuth2 endpoints.
• Response:

  {
    "issuer": "http://localhost:5001/oauth2",
    "authorization_endpoint": "http://localhost:5001/oauth2/authorize",
    "token_endpoint": "http://localhost:5001/oauth2/token",
    "revocation_endpoint": "http://localhost:5001/oauth2/revoke",
    "introspection_endpoint": "http://localhost:5001/oauth2/introspect",
    "scopes_supported": ["openid", "profile", "launch", "launch/patient", "patient/*.read", "offline_access"],
    "response_types_supported": ["code"],
    "grant_types_supported": ["authorization_code", "refresh_token"]
  }
  

2. Authorize

• Endpoint: GET /oauth2/authorize
• Description: Initiates the OAuth2 authorization flow.
• Parameters:
  • client_id: Client ID of the app.
  • redirect_uri: App’s callback URL.
  • scope: Space-separated scopes (e.g., patient/*.read openid).
  • response_type: Must be code.
  • state: State parameter for CSRF protection.
  • aud: Audience (FHIR server URL).
  • code_challenge: PKCE code challenge.
  • code_challenge_method: Must be S256.
• Use Case: Redirect users to authenticate and authorize the app.
• Response: Redirects to the redirect_uri with an authorization code (e.g., ?code=<code>&state=<state>).

3. Token

• Endpoint: POST /oauth2/token
• Description: Exchanges an authorization code for an access token.
• Parameters:
  • grant_type: authorization_code or refresh_token.
  • code: Authorization code (for authorization_code grant).
  • redirect_uri: Must match the original redirect URI.
  • client_id: Client ID.
  • client_secret: Client Secret.
  • code_verifier: PKCE code verifier.
  • refresh_token: Refresh token (for refresh_token grant).
• Use Case: Obtain access and refresh tokens to interact with the FHIR server.
• Response:

  {
    "access_token": "<access-token>",
    "refresh_token": "<refresh-token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "patient/*.read openid"
  }
  

4. Revoke

• Endpoint: POST /oauth2/revoke
• Description: Revokes an access or refresh token.
• Parameters:
  • token: The token to revoke.
  • token_type_hint: access_token or refresh_token (optional).
• Use Case: Invalidate tokens when they are no longer needed.
• Response:

  {}
  

5. Introspect

• Endpoint: POST /oauth2/introspect
• Description: Verifies the status of a token.
• Parameters:
  • token: The token to introspect.
• Use Case: Check if a token is active or expired.
• Response:

  {
    "active": true,
    "client_id": "<client-id>",
    "scope": "patient/*.read openid",
    "exp": 1698777600
  }
  

6. FHIR Proxy

• Endpoint: GET|POST /oauth2/proxy/<path:path>
• Description: Proxies requests to the upstream FHIR server, adding the access token in the Authorization header.
• Parameters:
  • path: The FHIR resource path (e.g., Patient/123).
  • Headers: Authorization: Bearer <access-token>.
• Use Case: Access FHIR resources securely through the proxy.
• Response: The FHIR server’s response (e.g., a Patient resource in JSON).

Use Cases

Use Case 1: Registering and Testing a SMART App

1. Register a new app in the App Gallery with redirect URI https://myapp.com/callback and scopes patient/*.read openid.
2. Use the Client ID and Secret in /test-client to simulate an OAuth2 flow.
3. Grant consent and receive an authorization code.
4. Exchange the code for an access token using the /oauth2/token endpoint.
5. Use the access token to query FHIR resources via /oauth2/proxy/Patient.

Use Case 2: Configuring Proxy Settings

1. Go to /configure/proxy-settings.
2. Change the FHIR server URL to a custom server (e.g., https://myfhirserver.com).
3. Set the proxy timeout to 30 seconds.
4. Save the settings and test the proxy by querying a resource.

Use Case 3: Revoking a Token

1. After testing an app, obtain a refresh token.
2. Use the /oauth2/revoke endpoint to invalidate the refresh token.
3. Verify the token’s status using /oauth2/introspect.

Troubleshooting

Common Issues

• Configuration Values Not Displaying:
  • Check the logs for get_config_value debug messages to confirm database retrieval.
  • Ensure the database (/app/instance/fhirvine.db) contains the correct values.
• OAuth2 Flow Fails:
  • Verify the Client ID, Secret, and Redirect URI match the registered app.
  • Check the FHIR server URL in /configure/proxy-settings.
• Images Not Displaying:
  • Ensure FHIRVINE.png is in /app/static/.
  • Check volume mounts in docker-compose.yml (e.g., ./static:/app/static).

Logs

• Logs are available via Docker:

  docker logs fhirvine_app
  

• Look for DEBUG and ERROR messages to diagnose issues.

Support

For additional help, contact support@fhirvine.example.com or open an issue on the project’s GitHub repository.