Single Sign-On

Instead of managing users in Shaper, you can use Singe Sign-On (SSO) to connect Shaper to your existing user management.

This makes onboarding (and offboarding!) users simpler since users can just start using Shaper without creating an account first and without typing a password.

Note

Single Sign-On is for logging into Shaper’s dashboard/task management UI, not for users to view dashboards.

To authenticate users viewing dashboards use Dashboard Embedding.

If embedding doesn’t fit your use case and you are looking for the Shaper UI but with view-only permissions, please reach out on this Github issue so we can prioritize implementing user permission functionality.

How it works

Shaper’s base SSO functionality is built on JWTs.

See it in action:

Play

The workflow is as follows:

1. User opens Shaper. When user doesn’t have a valid JWT, Shaper redirects user to configured sso-login-url with the query parameter redirect set to the Shaper page the user tried to access.
2. The SSO login endpoint (you implement this endpoint) authenticates the user and ensures the user is permitted to access Shaper.
3. Generate a JWT for the user with userId and optionally also userEmail and userName set. Shaper uses these for auditing purposes to identify the user. To generate the JWT, you need to use the same JWT secret as Shaper. Configure the JWT secret Shaper uses by setting jwt-secret.
4. Get the URL from the redirect query parameter, set the token parameter of that URL to the generated JWT and redirect the user to this URL.

Here is an example for an SSO Login endpoint implemented in Node.js:

const http = require('http');
const jwt = require('jsonwebtoken');

const PORT = process.env.PORT || 3000;
const SHPAPER_JWT_SECRET = process.env.SHPAPER_JWT_SECRET || 'test-secret';
const FALLBACK_REDIRECT_URL = process.env.FALLBACK_REDIRECT_URL || 'http://localhost:5454/';

const USER = {
  userId: process.env.SSO_USER_ID || 'demo_user',
  userEmail: process.env.SSO_USER_EMAIL || 'demo@example.com',
  userName: process.env.SSO_USER_NAME || 'Demo User'
};

const server = http.createServer((req, res) => {
  const reqUrl = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
  const redirectParam = reqUrl.searchParams.get('redirect') || FALLBACK_REDIRECT_URL;

  let targetUrl;
  try {
    targetUrl = new URL(redirectParam);
  } catch {
    targetUrl = new URL(FALLBACK_REDIRECT_URL);
  }

  const token = jwt.sign(USER, SHPAPER_JWT_SECRET, { expiresIn: '1h' });

  targetUrl.searchParams.set('token', token);

  console.log(`Logging in as "${USER.userName}" (${USER.userId})`);
  console.log(`Redirecting to: ${targetUrl.toString()}`);

  res.writeHead(302, { 'Location': targetUrl.toString() });
  res.end();
});

server.listen(PORT);

OpenID Connect and Proxy Header Auth

OpenID Connect (OIDC) is a standard that allows users to login with many existing identity providers without the need for any custom code. Google OAuth, Microsoft, auth0, Okta, Amazon Cognito, Keycloak all support OIDC.

Proxy Header Authentication allows logging in users automatically for application running behind a corporate proxy server/load balancer such as Nginx, Envoy, Traefik, Caddy, HAProxy, Kong Gateway and Apache HTTP Server. The proxy server ensures users haave a valid session and sets HTTP headers to identify which user is accessing the system. Shaper then trusts those headers since it’s guaranteed that all requests can only reach Shaper through the proxy server.

OIDC and Proxy Header Auth can be implemented with zero custom code and are great solutions if you are already using them in your infrastructure. We support OIDC and Proxy Header Auth with our paid plans. Please reach out if you are interested.