@cognite/dune-fe-auth

Authentication for Dune CDF React applications.

Installation

npm install @cognite/dune-fe-auth

Usage

CDFAuthenticationProvider

Wrap your application with the CDFAuthenticationProvider and pass your CDF configuration:

import { CDFAuthenticationProvider, CDFConfig } from '@cognite/dune-fe-auth';

const cdfConfig: CDFConfig = {
  project: 'your-project-name',
  baseUrl: 'https://api.cognitedata.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  appId: 'your-app-name', // optional
};

function App() {
  return (
    <CDFAuthenticationProvider config={cdfConfig}>
      <YourAppComponents />
    </CDFAuthenticationProvider>
  );
}

useCDF Hook

Use the useCDF hook to access the Cognite SDK in your components:

import { useCDF } from '@cognite/dune-fe-auth';

function MyComponent() {
  const { sdk, isLoading, error } = useCDF();
  
  if (error) {
    return <div>Error: {error}</div>;
  }
  
  if (isLoading) {
    return <div>Loading...</div>;
  }
  
  // Use the SDK to interact with CDF
  const fetchAssets = async () => {
    const assets = await sdk.assets.list();
    return assets;
  };
  
  return <div>...</div>;
}

Utilities

The package also exports utility functions for authentication:

import { getToken, createCDFSDK, EMPTY_SDK, CDFConfig } from '@cognite/dune-fe-auth';

// Get an access token
const token = await getToken(clientId, clientSecret);

// Create a configured SDK directly
const config: CDFConfig = {
  project: 'your-project',
  baseUrl: 'https://api.cognitedata.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
};
const sdk = await createCDFSDK(config);

Custom Loading and Error Components

You can customize the loading and error states:

import { CDFAuthenticationProvider } from '@cognite/dune-fe-auth';

function App() {
  return (
    <CDFAuthenticationProvider 
      config={cdfConfig}
      loadingComponent={<div>Custom loading...</div>}
      errorComponent={(error) => <div>Custom error: {error}</div>}
    >
      <YourAppComponents />
    </CDFAuthenticationProvider>
  );
}

Deployment Script

This package includes a CLI tool for deploying Dune apps to CDF.

Quick Start

# Using npx
npx cdf-deploy

# Or install globally
npm install -g @cognite/dune-fe-auth
cdf-deploy

Configuration

Create an app.json file in your project root:

{
  "name": "My App",
  "description": "Application description",
  "externalId": "my-app",
  "versionTag": "1.0.0",
  "deployment": {
    "org": "your-org",
    "project": "your-project"
  }
}

Data Set Requirement

Security Note: Apps must be uploaded to a data set with external ID published-custom-apps. This security measure ensures that only authorized users (with write access to this data set) can deploy apps.

Your IT admin needs to:

1. Create a data set with external ID published-custom-apps
2. Grant write access to users who should be able to deploy apps

If the data set doesn't exist or you don't have access, deployment will fail with a clear error message.

CI/CD Mode

For automated deployments, use client credentials:

# Set environment variables
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"
export BASE_URL="https://api.cognitedata.com"

# Deploy
npx cdf-deploy --ci

See src/scripts/README.md for detailed documentation.

Configuration

The package uses prop-based configuration instead of environment variables for better security and flexibility.

Peer Dependencies

This package requires:

• @cognite/sdk ^8.0.0
• react ^18.0.0

Development

# Install dependencies
npm install

# Initialize git submodule (required for auth-client source code)
git submodule update --init --recursive

# Build the package
npm run build

# Watch for changes during development
npm run dev

# Preview the built package
npm run preview

# Type check
npm run type-check

Git Submodule

This package uses a git submodule to bundle the @cognite/auth-client source code directly into the distribution. The submodule is located at src/vendor/cog-idp and points to the cog-idp repository.

Important: When cloning this repository, make sure to initialize the submodule:

git submodule update --init --recursive

The auth-client code is bundled during the build process, so consumers of the npm package don't need access to the submodule.

Publishing

npm publish

License

MIT