Third-Party OAuth Integration Guide for Publishers (BYOL / Short Link)

<aside> 🧭

</aside>

Overview

This guide is for publishers who want to allow users to access their content on Cashmere that has already been licensed on the publishers platform. We refer to this setup as Bring Your Own License (BYOL) and Short Link.

This image visualizes the flow of how your integration would work. In the first Image, Cashmere Link notifies the user that a 3rd party is facilitating the connection. The second and third images are intended to represent your auth flow. In the last image, when the token and the scopes have been returned to Cashmere, we present it back to the user and confirm the authentication process.

What This Integration Provides

Single Sign-On: Users authenticate once with your system to access licensed content
Automatic Collection Access: Content collections are automatically available based on user permissions
Seamless User Experience: No additional account creation or manual license management required
Dynamic Access Control: Collection access updates automatically when user permissions change

Your Role as Publisher

As a third-party publisher, you will:

Configure your OAuth provider with specific requirements
Implement custom OAuth claims to communicate collection access rights
Provide configuration details to Cashmere for integration
Test the integration before going live

Step 1: OAuth Provider Configuration

1.1 Create OAuth Application

In your OAuth provider (Auth0, Okta, custom implementation, etc.), create a new web application with these specifications:

Required Settings:

Application Type: Web Application or Single Page Application
Grant Types:
- Authorization Code with PKCE (required)
- Refresh Token (recommended for seamless experience, required to update users continually)
Token Endpoint Authentication: Client Secret Basic or Client Secret Post

Required Scopes:

Your OAuth application must support these scopes:

openid - Standard OpenID Connect scope
email - User email address (required for account matching)
offline_access - Refresh token support (required for Cashmere to check user access later)
https://cashmere.io/collection_ids - Custom scope for collection access

1.2 Configure Redirect URI

Set your OAuth application's redirect URI to:

<https://cashmere.io/publisher_oauth/callback>

Important: The redirect URI must match exactly. Contact Cashmere if you need a different domain or custom redirect URL.

1.3 Note Your OAuth Endpoints

You'll need to provide these details to Cashmere:

Authorization URL: Where users are redirected to authenticate
Token URL: Where authorization codes are exchanged for tokens
Client ID: Your OAuth application's public identifier
Client Secret: Your OAuth application's private key (share securely with Cashmere)

Step 2: Implement Custom Claims

2.1 Collection IDs Claim

The most critical part of the integration is implementing the https://cashmere.io/collection_ids custom claim. This claim tells Cashmere which content collections a user has access to. Cashmere validates passed collection ids to ensure you are the owner of them.

Claim Requirements:

Claim Name: Must be exactly https://cashmere.io/collection_ids
Token Location: Must be included in the ID token
Format: Comma-separated string of collection IDs
Example: "1,5,10,15" (user has access to collections 1, 5, 10, and 15)

Implementation Examples:

Auth0 Post Login Trigger:

exports.onExecutePostLogin = async (event, api) => {
  if (event.transaction?.requested_scopes?.includes("<https://cashmere.io/collection_ids>")) {
    // Determine user's collection access based on your business logic
    const userCollections = getUserCollections(event.user.user_id);
    api.idToken.setCustomClaim(
      "<https://cashmere.io/collection_ids>",
      userCollections.join(',')  // eg "1,2,3"
    );
  }
};

2.2 Business Logic for Collection Access

You need to implement logic to determine which collections a user can access. This typically involves:

User Role Mapping: Map user roles/groups to collection IDs
Subscription Status: Check active subscriptions or licenses
Dynamic Permissions: Query your database for user-specific access rights
Organizational Access: Include collections based on user's organization/department

It also might be as simple as a hard-coded list if you are granting all of your users access to a set list of collections.

Example Business Logic:

function getUserCollections(userId) {
  const user = getUserFromDatabase(userId);
  const collections = [];

  // Add collections based on subscription tier
  if (user.subscription === 'premium') {
    collections.push(1, 2, 3, 4, 5); // Premium collections
  } else if (user.subscription === 'basic') {
    collections.push(1, 2); // Basic collections only
  }

  // Add organization-specific collections
  if (user.organization === 'university_a') {
    collections.push(10, 11, 12); // University A collections
  }

  return collections;
}

2.3 Access Updates

Your implementation should support dynamic access changes. Cashmere will update the collections list via an OAuth token refresh after each API Token each time it is used.

Step 3: Coordinate with Cashmere

3.1 Information to Provide

Contact Cashmere with the following information:

OAuth Configuration:

Authorization URL: https://your-provider.com/oauth/authorize
Token URL: https://your-provider.com/oauth/token
Client ID: Your OAuth application's client ID
Client Secret: Your OAuth application's client secret
Email: Your Cashmere account email address so we can associate the OAuth provider credentials

You will receive a unique identifier which you will be able to test the connection with via

https://cashmere.io/publisher_oauth/<publisher_provider_uuid>

Step 4: Testing Your OAuth Provider Setup

4.1 OAuth Flow Testing

Authorization Flow: Verify users can authenticate successfully
Token Exchange: Confirm authorization codes exchange for valid tokens

User Guides

Publisher Guides

Developer Guides