App Installation Flow

This guide explains how to implement the OAuth 2.0 app installation flow for client applications that will be listed in the ResDiary App Marketplace. When venues discover and install your app from the

Overview

The app installation flow enables venues to securely connect your application to their ResDiary diary. This flow combines:

• App Marketplace Discovery: Venues browse and select your app

• Install URL Redirect: ResDiary redirects to your app's install endpoint

• OAuth 2.0 Authorization: Your app initiates the authorization code flow with PKCE

• Access Token Exchange: Your app obtains tokens to access the venue's data

---

Prerequisites

Before implementing the app installation flow, ensure you have:

1. Created an App in the Developer Hub

2. Configured Install URL in your app settings

3. Configured Redirect URL for OAuth callbacks

4. Understanding of OAuth 2.0 authorization code flow with PKCE (see OAuth 2.0 Authorization Code Flow w/ PKCE)

---

Installation Flow Diagram

---

Step-by-Step Implementation

Step 1: Configure Install URL

In your app settings, configure the Install URL where venues will be redirected when they install your app from the marketplace.

Example Install URL:

https://yourapp.com/install

💡 Tip: The Install URL should be a dedicated endpoint in your application that handles the installation flow. This endpoint will receive the authorization_uri query parameter from ResDiary.

---

Step 2: Receive Installation Request

When a venue clicks "Install" on your app in the marketplace, ResDiary redirects them to your Install URL with an authorization_uri query parameter.

Example redirect to your Install URL:

GET https://yourapp.com/install?authorization_uri={partial_authorization_uri}

The authorization_uri parameter contains a partial URL to the OAuth authorization server with some pre-filled parameters:

Pre-filled parameters in authorization_uri:

• client_id: Your application's Client ID

• scope: The API scope based on your app type (consumer_api, data_extract_api, or epos_api)

• microsite_name: The unique microsite name of the venue's diary being authorized

• response_type: Set to code for authorization code flow

• redirect_uri: Your app's configured Redirect URL

Example authorization_uri value:

https://authorization-server.com/oauth/authorize?
    client_id=1234&
    scope=consumer_api%20offline_access&
    microsite_name=SampleVenue&
    response_type=code&
    redirect_uri=https://yourapp.com/callback

---

Step 3: Generate PKCE Parameters

Your install endpoint must generate PKCE (Proof Key for Code Exchange) parameters to secure the authorization flow.

Required PKCE parameters:

1. code_verifier: A cryptographically random string (43-128 characters)

2. code_challenge: SHA-256 hash of the code_verifier, Base64 URL-encoded

3. state: A random string for CSRF protection

💡 Implementation Details: For detailed information on generating PKCE parameters with code examples in multiple languages, see Phase 1: Preparation

⚠️ Security Warning: Store the code_verifier and state securely in your session. You will need the code_verifier to exchange the authorization code for an access token, and the state to validate the callback.

---

Step 4: Complete Authorization URI

Add the missing PKCE parameters to the authorization_uri received from ResDiary:

Parameters to add:

• code_challenge: The SHA-256 hashed code_verifier (Base64 URL-encoded)

• code_challenge_method: Must be S256

• state: Random string for CSRF protection

Example code to complete the authorization URI:

public string CompleteAuthorizationUri(string partialAuthUri, string codeChallenge, string state)
{
    var uriBuilder = new UriBuilder(partialAuthUri);
    var query = HttpUtility.ParseQueryString(uriBuilder.Query);
    
    // Add PKCE parameters
    query["code_challenge"] = codeChallenge;
    query["code_challenge_method"] = "S256";
    query["state"] = state;
    
    uriBuilder.Query = query.ToString();
    return uriBuilder.ToString();
}

Complete authorization URI example:

https://authorization-server.com/oauth/authorize?
    client_id=1234&
    scope=consumer_api%20offline_access&
    microsite_name=SampleVenue&
    response_type=code&
    redirect_uri=https://yourapp.com/callback&
    code_challenge=djfjw8jfjk3k2eow9jfw8w==&
    code_challenge_method=S256&
    state=xyz123

---

Step 5: Redirect to Authorization Server

Redirect the venue user to the complete authorization URI to initiate the OAuth 2.0 authorization code flow.

Example redirect:

public IActionResult Install(string authorization_uri)
{
    // Generate PKCE parameters
    var (codeVerifier, codeChallenge, state) = PkceGenerator.GeneratePkceParameters();
    
    // Store in session for later use
    HttpContext.Session.SetString("code_verifier", codeVerifier);
    HttpContext.Session.SetString("oauth_state", state);
    
    // Complete authorization URI
    string completeAuthUri = CompleteAuthorizationUri(authorization_uri, codeChallenge, state);
    
    // Redirect to authorization server
    return Redirect(completeAuthUri);
}

---

Step 6: Handle Authorization Callback

After the user authenticates and grants permissions, the OAuth authorization server redirects them back to your configured Redirect URL with an authorization code.

Example callback:

GET https://yourapp.com/callback?code=authorization_code&state=xyz123

Callback parameters:

• code: The authorization code to exchange for an access token

• state: The state parameter you sent (must be validated)

Example callback handler:

public async Task<IActionResult> Callback(string code, string state)
{
    // Validate state parameter
    string expectedState = HttpContext.Session.GetString("oauth_state");
    if (state != expectedState)
    {
        return BadRequest("Invalid state parameter - possible CSRF attack");
    }
    
    // Retrieve code verifier from session
    string codeVerifier = HttpContext.Session.GetString("code_verifier");
    
    // Exchange authorization code for access token
    var tokens = await ExchangeCodeForToken(code, codeVerifier);
    
    // Store tokens securely
    await StoreTokens(tokens);
    
    // Clear session data
    HttpContext.Session.Remove("code_verifier");
    HttpContext.Session.Remove("oauth_state");
    
    // Redirect to success page
    return RedirectToAction("InstallationComplete");
}

✅ Best Practice: Always validate the state parameter to prevent CSRF attacks. The state value returned must exactly match the value you sent in the authorization request.

---

Step 7: Exchange Authorization Code for Access Token

Exchange the authorization code for an access token by making a POST request to the OAuth token endpoint with the authorization code and code verifier.

💡 Implementation Details: For complete information on token exchange including request format, parameters, response structure, and code examples, see Phase 3: Token Exchange

📖 Token Management: For information about token refresh and long-term access, see Phase 4: Token Management

---

Step 8: Store Tokens Securely

Store the access token and refresh token securely in your application's database or secure storage.

Security best practices:

• Encrypt tokens at rest

• Never store tokens in browser localStorage or sessionStorage

• Associate tokens with the specific venue (microsite_name)

• Store token expiry time for proactive refresh

• Use secure HTTP-only cookies for web applications

Example token storage:

public async Task StoreTokens(TokenResponse tokens, string micrositeName)
{
    var installation = new AppInstallation
    {
        MicrositeName = micrositeName,
        AccessToken = _encryptionService.Encrypt(tokens.AccessToken),
        RefreshToken = _encryptionService.Encrypt(tokens.RefreshToken),
        TokenExpiresAt = DateTime.UtcNow.AddSeconds(tokens.ExpiresIn),
        Scope = tokens.Scope,
        InstalledAt = DateTime.UtcNow
    };
    
    await _dbContext.AppInstallations.AddAsync(installation);
    await _dbContext.SaveChangesAsync();
}

---

Complete Installation Flow Example

Here's a complete example of an install endpoint implementation:

[HttpGet("install")]
public IActionResult Install([FromQuery] string authorization_uri)
{
    if (string.IsNullOrEmpty(authorization_uri))
    {
        return BadRequest("Missing authorization_uri parameter");
    }
    
    try
    {
        // Parse the authorization URI to extract microsite_name
        var uri = new Uri(authorization_uri);
        var query = HttpUtility.ParseQueryString(uri.Query);
        string micrositeName = query["microsite_name"];
        
        // Generate PKCE parameters
        var (codeVerifier, codeChallenge, state) = PkceGenerator.GeneratePkceParameters();
        
        // Store in session for callback
        HttpContext.Session.SetString("code_verifier", codeVerifier);
        HttpContext.Session.SetString("oauth_state", state);
        HttpContext.Session.SetString("microsite_name", micrositeName);
        
        // Add PKCE parameters to authorization URI
        query["code_challenge"] = codeChallenge;
        query["code_challenge_method"] = "S256";
        query["state"] = state;
        
        var uriBuilder = new UriBuilder(uri)
        {
            Query = query.ToString()
        };
        
        // Redirect to authorization server
        return Redirect(uriBuilder.ToString());
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error processing install request");
        return StatusCode(500, "Installation failed");
    }
}

[HttpGet("callback")]
public async Task<IActionResult> Callback([FromQuery] string code, [FromQuery] string state)
{
    try
    {
        // Validate state parameter
        string expectedState = HttpContext.Session.GetString("oauth_state");
        if (state != expectedState)
        {
            _logger.LogWarning("State parameter mismatch - possible CSRF attack");
            return BadRequest("Invalid state parameter");
        }
        
        // Retrieve stored values
        string codeVerifier = HttpContext.Session.GetString("code_verifier");
        string micrositeName = HttpContext.Session.GetString("microsite_name");
        
        // Exchange code for tokens
        var tokens = await ExchangeCodeForToken(code, codeVerifier);
        
        // Store tokens securely
        await StoreTokens(tokens, micrositeName);
        
        // Clear session
        HttpContext.Session.Remove("code_verifier");
        HttpContext.Session.Remove("oauth_state");
        HttpContext.Session.Remove("microsite_name");
        
        // Redirect to success page
        return RedirectToAction("InstallationComplete");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error processing OAuth callback");
        return RedirectToAction("InstallationFailed");
    }
}

---

Security Considerations

⚠️ Critical: All OAuth 2.0 flows MUST use HTTPS for all URLs (Install URL, Redirect URL, and API endpoints). Never use HTTP in production.

Installation-specific security requirements:

• Always validate the state parameter in your callback to prevent CSRF attacks

• Store the code_verifier securely in server-side session storage

• Never expose your client_secret in client-side code or public repositories

• Encrypt tokens at rest in your database

• Associate tokens with specific venues (microsite_name)

📖 Complete Security Guide: For comprehensive security best practices including HTTPS requirements, CSRF protection, client secret handling, token storage, and additional security recommendations, see Security Best Practices

---

Error Handling

Common Installation Errors

Error	Cause	Solution
Missing authorization_uri	ResDiary didn't provide the parameter	Verify Install URL is correctly configured in app settings
Invalid authorization_uri	Malformed or incomplete URI	Validate URI format and required parameters
State mismatch	CSRF attack or session loss	Regenerate state and restart flow
Invalid authorization code	Code expired or already used	Authorization codes are single-use and expire quickly (typically 10 minutes)
Token exchange failed	Invalid credentials or parameters	Verify client_id, client_secret, and code_verifier are correct

📖 Complete Error Reference: For comprehensive error codes, troubleshooting guides, and solutions for authorization errors, token exchange errors, and refresh token errors, see Error Handling

Handling Installation Failures

Provide clear error messages and recovery options:

public IActionResult InstallationFailed()
{
    ViewBag.ErrorMessage = "Installation failed. Please try again or contact support.";
    ViewBag.RetryUrl = Url.Action("RetryInstallation");
    return View();
}

public IActionResult RetryInstallation()
{
    // Clear any existing session data
    HttpContext.Session.Clear();
    
    // Redirect back to app marketplace or provide manual installation instructions
    return RedirectToAction("InstallationInstructions");
}

---

Testing the Installation Flow

Test Environment

Before submitting your app for production approval, test the installation flow in the Test Environment:

1. Configure your Install URL in the Test Environment settings

2. Use test credentials (Test Client ID and Client Secret)

3. Test with a test diary (microsite_name)

4. Verify token exchange and storage

5. Test API calls with obtained access tokens

Testing Checklist

• Install URL correctly receives authorization_uri parameter

• PKCE parameters are generated correctly

• Authorization URI is completed with all required parameters

• State parameter is validated in callback

• Authorization code is successfully exchanged for tokens

• Tokens are stored securely

• Access token can be used to make API calls

• Refresh token can be used to obtain new access tokens

• Error scenarios are handled gracefully

• HTTPS is used for all URLs

---

Next Steps

After implementing the app installation flow:

1. Test thoroughly in the Test Environment

2. Submit your app for production approval

3. Implement token refresh to maintain long-term access (see Phase 4: Token Management)

4. Monitor installations and handle errors gracefully

5. Provide support for venues during installation

---

Summary

The OAuth 2.0 app installation flow enables venues to securely connect your application to their ResDiary diary:

1. Configure Install URL in your app settings

2. Receive installation request with authorization_uri parameter

3. Generate PKCE parameters for secure authorization

4. Complete authorization URI with PKCE parameters

5. Redirect to authorization server for user authentication

6. Handle callback with authorization code

7. Exchange code for tokens using code_verifier

8. Store tokens securely for API access

By following this guide, you'll provide a seamless and secure installation experience for venues using your application.