Dashboard Project

A web dashboard with OpenID Connect (OIDC) authentication, featuring project management and role-based access control.

What This Does

This dashboard provides a way to organize and share access to various projects or applications within your organization. Users log in through your existing identity provider (like Keycloak, Auth0, Okta, or Azure AD) and see different projects based on their group memberships.

You can control which users see which projects and what information they can access about each project. The system is highly customizable - you define your own project properties and create your own templates to display them however you want. Some users might see a simple project card with basic info, while others with higher permissions might see additional details or direct access links.

The dashboard works great for IT departments managing internal tools, development teams organizing various applications, or any organization that needs to provide role-based access to different resources while maintaining a clean, organized interface.

Prerequisites

• Node.js (v14 or higher)

• pnpm package manager

• OIDC-compliant identity provider (e.g., Keycloak, Auth0, Okta, Azure AD)

• SSL certificates (for HTTPS)

Setup

1. Install Dependencies

pnpm install

2. Configure Server

Create your configuration.yaml file based on the example in data/configuration.yaml:

server:
  port: 443                    # Port to run on
  baseUrl: "https://your-domain"  # Your domain URL
  sessionSecret: "your-long-random-session-secret"  # Generate a random string
  shuffleMode: "private_first"  # Options: "none", "all", "private_first"
  secureCookies: true          # Set to false for HTTP, true for HTTPS

3. Configure OIDC Provider

Add OIDC configuration to your configuration.yaml:

oidc:
  issuer: "https://your-oidc-provider/issuer-endpoint"
  clientId: "your-client-id"
  clientSecret: "your-client-secret"
  logoutRedirectUri: "https://your-oidc-provider/logout?post_logout_redirect_uri={REDIRECT_URI}"

OIDC Provider Setup: In your identity provider’s admin console:

1. Create a new client with the ID specified above

2. Set the redirect URI to: https://your-domain/callback

3. Enable "Client authentication" and note the client secret

4. Configure appropriate user groups and roles

4. Configure SSL (Optional)

For HTTPS, add SSL configuration to your configuration.yaml:

server:
  # ... other server config
  ssl:
    keyFile: "path/to/ssl.key"    # Path to SSL private key
    certFile: "path/to/ssl.crt"   # Path to SSL certificate

Place your SSL certificate files in your data directory or specify absolute paths.

5. Configure Projects

Create your projects.yaml file and customize templates:

Projects Configuration:

projects:
  - public_groups: ["/group1"]
    public:
      title: "Project Name"
      description: "Project description"
      # Add any custom properties your template needs
    private_groups: ["/admin"]
    private:
      link: "https://project-url.com"
      # Add any custom properties your template needs

Access Control Rules:

• public_groups: User groups that can see the project

• private_groups: User groups that get access to private properties

• Properties in public section are available when user is in public_groups

• Properties in private section are available when user is in private_groups

• If user is in neither group, the project is hidden

Template Customization:

• Copy templates from data/public/ and customize them

• Templates can access any properties from public and/or private sections

• Use EJS syntax to render project data: <%= project.title %>

• Add custom CSS in your styles.css

• Place project screenshots in screenshots/ directory

Shuffle Modes:

• "none": Projects shown in original order

• "all": All projects shuffled randomly

• "private_first": Accessible projects shown first, then shuffled

Running the Application

Docker Deployment

Build and run using Docker:

# Build the image
docker build -t dashboard .

# Run the container - mount your data folder containing configuration and templates
docker run -p 443:443 -v /path/to/your/data:/app/data dashboard

Important: You must mount your data folder (containing configuration.yaml, projects.yaml, and templates) to /app/data in the container. The server will persist session information in the sessions/ subdirectory.

Development Mode

Use the provided scripts for easy development:

# Start the server
./development/start.sh

# Stop the server
./development/stop.sh

# Restart the server
./development/restart.sh

Manual Start

# Start with default data folder
node server.js

# Start with custom data folder
DATA_FOLDER=/path/to/data node server.js

The server will be available at https://your-domain

Security Considerations

• Always use HTTPS in production

• Protect your SSL private key

• Use strong session secrets

• Keep OIDC client secrets confidential

• Regularly update dependencies

Troubleshooting

Port Already in Use:

lsof -i:443  # Check what's using the port
./development/stop.sh  # Stop existing server

SSL Issues:

• Verify certificate validity and path

• Check file permissions for SSL files

Authentication Issues:

• Verify OIDC provider configuration

• Check network connectivity to identity provider

• Review redirect URIs in OIDC client settings

Project Access Issues:

• Verify user group memberships in your identity provider

• Check your projects.yaml group configurations

• Review application logs for access control decisions

Project Structure

dashboard/
├── data/                    # Example data folder (customize as needed)
│   ├── configuration.yaml    # Example server and OIDC provider configuration
│   ├── projects.yaml         # Example project definitions and access control
│   ├── public/               # Example static files and templates
│   │   ├── logged-out.ejs   # Example logout confirmation page
│   │   ├── projects.ejs     # Example main projects dashboard
│   │   ├── styles.css       # Example styling
│   │   └── screenshots/     # Example project screenshot images
│   ├── sessions/            # Session storage directory
│   ├── ssl.crt             # Example SSL certificate
│   └── ssl.key             # Example SSL private key
├── development/             # Development scripts
│   ├── start.sh            # Start server script
│   ├── stop.sh             # Stop server script
│   └── restart.sh          # Restart server script
├── server.js               # Main application server
└── package.json           # Node.js dependencies