# 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](https://taleshape.com/shaper/docs/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](https://github.com/taleshape-com/shaper/issues/23) so we can prioritize implementing user permission functionality.

## How it works

Shaper's base SSO functionality is built on JWTs.

*See it in action:*
<YouTube id="https://www.youtube.com/watch?v=c6VnUIVD3h4" />

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`](https://taleshape.com/shaper/docs/configuration-options#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`](https://taleshape.com/shaper/docs/configuration-options#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:

```javascript
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](https://taleshape.com/plans-and-pricing). Please [reach out](https://taleshape.com/contact) if you are interested.