Skip to main content

SSO Setup Guide

ECOSIRE uses Authentik as its identity provider, implementing OpenID Connect (OIDC) for secure single sign-on. This guide covers setting up SSO for your organization — both using the hosted Authentik instance and integrating your own IdP.

Introduction​

ECOSIRE's authentication flow:

  1. User visits ecosire.com and clicks Sign In
  2. Browser redirects to https://auth.ecosire.com/
  3. Authentik authenticates the user (local account, or federated LDAP/SAML/OIDC)
  4. Authentik issues a one-time code, redirects to ecosire.com/auth/callback
  5. ECOSIRE API exchanges the code for an access token and refresh token
  6. Tokens are stored in HttpOnly cookies — never in localStorage

Prerequisites​

  • Admin access to Authentik (https://auth.ecosire.com/if/admin/)
  • ECOSIRE organization admin account
  • (Optional) Your corporate IdP: Azure AD, Okta, Google Workspace, or any SAML 2.0/OIDC provider

Step 1 — Understand the Authentik Architecture​

ECOSIRE's Authentik setup:

ComponentValue
Admin URLhttps://auth.ecosire.com/if/admin/
OAuth2 ProviderECOSIRE Web OAuth2 (pk=1)
Client IDecosire-web
Scopesopenid, profile, email
Authorization endpointhttps://auth.ecosire.com/application/o/authorize/
Token endpointhttps://auth.ecosire.com/application/o/token/
OIDC Discoveryhttps://auth.ecosire.com/application/o/ecosire-web/.well-known/openid-configuration

Step 2 — Add a User to ECOSIRE​

New users are auto-provisioned on first login if the enrollment flow is enabled. To manually create a user:

  1. Log in to Authentik Admin.
  2. Go to Directory → Users → Create.
  3. Fill in username, email, and name.
  4. Send the password reset email.

The user will appear in ECOSIRE after their first successful login (auto-created via the upsertUser flow in the API).

Step 3 — Federate with Azure Active Directory​

Allow your corporate Azure AD users to sign in to ECOSIRE:

  1. In Azure Portal → App Registrations → New registration:

    • Name: ECOSIRE SSO
    • Redirect URI: https://auth.ecosire.com/source/oauth/callback/azure-ad/

  2. Copy the Application (client) ID and Directory (tenant) ID.

  3. Under Certificates & secrets, create a new client secret.

  4. In Authentik Admin → Sources → Create → OAuth2/OpenID:

    • Name: Azure AD
    • Consumer Key: <Application ID>
    • Consumer Secret: <Client Secret>
    • OIDC Well-Known URL: https://login.microsoftonline.com/<Tenant ID>/v2.0/.well-known/openid-configuration
    • Scopes: openid profile email

  5. Users now see a Sign in with Microsoft button on the Authentik login page.

Step 4 — Federate with Google Workspace​

  1. In Google Cloud Console → APIs & Services → Credentials → Create OAuth Client:

    • Application type: Web application
    • Authorized redirect URI: https://auth.ecosire.com/source/oauth/callback/google/

  2. Copy Client ID and Secret.

  3. In Authentik Admin → Sources → Create → Google:

    • Consumer Key: <Client ID>
    • Consumer Secret: <Client Secret>

Step 5 — Federate with Okta​

  1. In Okta Admin → Applications → Create App Integration → OIDC → Web Application.

  2. Set Sign-in redirect URI: https://auth.ecosire.com/source/oauth/callback/okta/

  3. Copy Client ID, Client Secret, and Okta domain.

  4. In Authentik Admin → Sources → Create → OAuth2/OpenID:

    • OIDC Well-Known URL: https://your-org.okta.com/.well-known/openid-configuration

Step 6 — Configure ECOSIRE API for a New Client​

If you are building a new application that should authenticate against ECOSIRE's Authentik:

  1. In Authentik Admin → Applications → Create:

    • Name: Your App Name
    • Slug: your-app
    • Provider: Create new OAuth2 Provider

  2. OAuth2 Provider settings:

    • Client type: Confidential
    • Redirect URIs: https://yourapp.com/auth/callback
    • Scopes: openid profile email
    • Subject mode: Based on the User's Email

  3. Copy Client ID and Client Secret to your app's environment variables.

Step 7 — Implement OIDC Flow in Your App​

// Step 1: Redirect to Authentik
const authUrl = new URL('https://auth.ecosire.com/application/o/authorize/');
authUrl.searchParams.set('client_id', process.env.AUTHENTIK_CLIENT_ID!);
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/auth/callback');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('state', generateCsrfToken());

res.redirect(authUrl.toString());

// Step 2: Handle callback
app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;
  // Verify state matches CSRF token...

  // Exchange code for tokens
  const tokenRes = await fetch('https://auth.ecosire.com/application/o/token/', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code as string,
      redirect_uri: 'https://yourapp.com/auth/callback',
      client_id: process.env.AUTHENTIK_CLIENT_ID!,
      client_secret: process.env.AUTHENTIK_CLIENT_SECRET!,
    }),
  });
  const tokens = await tokenRes.json();
  // Store tokens in HttpOnly cookies...
});

Step 8 — Test SSO​

  1. Open an incognito browser window.
  2. Navigate to https://ecosire.com.
  3. Click Sign In.
  4. On the Authentik login page, click your federated IdP button (e.g., Sign in with Microsoft).
  5. Complete the IdP login.
  6. Confirm you are redirected back to the ECOSIRE dashboard as the authenticated user.

Troubleshooting​

IssueSolution
Redirect loop on loginEnsure only proxy.ts exists (not middleware.ts) in Next.js
invalid_client from AuthentikConfirm Client Secret matches exactly — regenerate via Django ORM if needed
User not created in ECOSIRECheck POST /auth/callback — upsertUser runs here
SAML assertion errorsCheck clock skew — server clocks must be within 5 minutes
Azure AD token rejectedConfirm redirect URI in Azure matches exactly (trailing slash matters)

Next Steps​

Last updated on