Skip to content

OpenID Connect (OIDC) Setup

Portal supports OpenID Connect (OIDC) for single sign-on with any OIDC-compliant identity provider, including AWS Cognito, Azure AD / Microsoft Entra ID, Google Identity Platform, and Okta.

Warning

OIDC authentication does not work with the Tableau REST API. If your Portal uses Tableau integration, you must use static dashboards rather than the Tableau REST API.

Prerequisites

  • Docker-based Portal deployment
  • Access to your organization's OIDC identity provider admin console
  • Ability to update the Portal's Docker Compose and NGINX configuration

Step 1: Register Portal with Your Identity Provider

Create a new application in your OIDC provider with the following settings:

Setting Value
Application Type Web Application
Grant Type Authorization Code
Redirect URI https://<your-portal-hostname>/openidc/authorize
Scopes openid, profile, email

After registration, note these values:

  • Client ID
  • Client Secret
  • Issuer URL (provided by your identity provider)

Step 2: Create the Settings File

Create a file named settings.json:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "redirect_uri": "https://<your-portal-hostname>/openidc/authorize",
  "issuer": "https://your-identity-provider-issuer-url"
}

Provider-Specific Examples

AWS Cognito: 

{
  "client_id": "1a2b3c4d5e6f7g8h9i0j",
  "client_secret": "abcdefghijklmno1234567890",
  "redirect_uri": "https://portal.example.com/openidc/authorize",
  "issuer": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_P07hKC2bJ"
}

The Cognito issuer URL format is: https://cognito-idp.<region>.amazonaws.com/<user-pool-id>

Azure AD / Entra ID: 

{
  "client_id": "application-id-from-azure",
  "client_secret": "client-secret-from-azure",
  "redirect_uri": "https://portal.example.com/openidc/authorize",
  "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
}

Step 3: Deploy the Configuration

  1. Place settings.json in a directory accessible to Docker (e.g., app/openidc/).

  2. Add a volume mount to the auth service in your docker-compose.yaml:

services:
  auth:
    volumes:
      - ./app/openidc:/app/openidc

Step 4: Configure NGINX

Ensure your NGINX configuration routes the OIDC endpoints to the auth service:

location ~ /(openidc/redirect|openidc/authorize)$ {
    proxy_pass http://auth:5756$request_uri;
    include proxy_params;
    include nocache_params;
}

Update the 401 handler to redirect to OIDC instead of the standard login page:

location @401 {
    return 302 https://$http_host/openidc/redirect?location=https://$http_host$request_uri;
}

Step 5: Restart and Test

  1. Restart the Portal: 

    docker-compose down && docker-compose up -d

  2. Navigate to your Portal URL. You should be redirected to your identity provider's login page.

  3. Log in with your corporate credentials.
  4. You should be redirected back to Portal and logged in.

Troubleshooting

  • Redirect loop - Verify the redirect URI in settings.json exactly matches what is registered with your identity provider.
  • Settings file not found - Check the Docker volume mount and ensure settings.json exists at the mounted path. Restart the auth service.
  • Invalid client error - Verify the client_id and client_secret are correct and the application is still active.
  • HTTPS required - The redirect URI must use https://. Ensure your Portal is accessible via HTTPS.