portainer-core/docs/OIDC_CONFIGURATION.md

OIDC Authentication Configuration

Overview

Core-API has been configured with OIDC authentication support using Authentik as the identity provider. This provides secure authentication for infrastructure management endpoints.

Current Status

OIDC is currently DISABLED (oidc_enabled=false in config.py)

This allows:

• Internal services to access the API without authentication
• Direct API access from the Docker network
• Backward compatibility with existing integrations

Authentik Configuration

Provider Details

• Provider Name: core-api-provider
• Provider ID: 1
• Client ID: core-api
• Client Secret: WfsY0iIVOmO1wvXn1u8jwa08eiQsn2yVf9toBwVyEqps3M98nOZwJMgDOqH5PNZGM6wIxKTwlwYemtaOUg9u5bocd0EqShyoe4yhBQq4SDd0svyArILHZeGHFVEqUi4d
• Issuer: https://auth.schweitz.net/application/o/core-api/

Application Details

• Application Name: Core API
• Slug: core-api
• Launch URL: http://localhost:8083/docs

Redirect URIs

• http://localhost:8083/docs/oauth2-redirect
• https://core-api.schweitz.net/docs/oauth2-redirect
• http://192.168.86.149:8083/docs/oauth2-redirect

Enabling OIDC Authentication

When ready to enable OIDC authentication for external access:

1. Update core-api Configuration

In /home/jpmschweitzer/Projects/portainer-core/services/core-api/src/config.py:

# OIDC Authentication (Authentik)
oidc_enabled: bool = True  # Change from False to True
oidc_issuer: str = "https://auth.schweitz.net/application/o/core-api/"
oidc_audience: str = "core-api"
oidc_client_secret: str = "WfsY0iIVOmO1wvXn1u8jwa08eiQsn2yVf9toBwVyEqps3M98nOZwJMgDOqH5PNZGM6wIxKTwlwYemtaOUg9u5bocd0EqShyoe4yhBQq4SDd0svyArILHZeGHFVEqUi4d"

2. Restart core-api

docker restart core-api

3. Test Authentication

1. Visit: http://localhost:8083/docs
2. Click the "Authorize" button
3. Log in with Google via Authentik
4. Access protected endpoints

Protected Endpoints

When OIDC is enabled, the following endpoints require admin authentication:

Infrastructure Management (Write Operations)

• POST /infrastructure/services - Deploy stack
• PUT /infrastructure/services/{name} - Update stack
• DELETE /infrastructure/services/{name} - Delete stack
• POST /infrastructure/proxy - Create proxy host
• POST /infrastructure/services/{name}/stop - Stop service
• POST /infrastructure/services/{name}/start - Start service

Monitoring Management

• POST /infrastructure/monitors - Create monitor
• PUT /infrastructure/monitors/{monitor_id} - Update monitor
• DELETE /infrastructure/monitors/{monitor_id} - Delete monitor

Read Endpoints (Public)

All GET endpoints remain publicly accessible:

• /health - Health check
• /infrastructure/health - Infrastructure health
• /infrastructure/services - List services
• /infrastructure/ports - List ports
• /infrastructure/domains - List domains
• /infrastructure/monitors - List monitors

Internal Network Access

Important: After enabling OIDC for external users, internal services still need unrestricted access.

Future Enhancement Options

1. Network-based Authentication

   • Check if request originates from docker-dataplane network
   • Allow requests from internal IPs without auth
   • Require OIDC only for external requests

2. Service Accounts

   • Create machine tokens for internal services
   • Use Bearer token authentication for service-to-service calls
   • Keep OIDC for user authentication

3. NPM Proxy Layer

   • External domain (https://core-api.schweitz.net) → Requires Authentik SSO
   • Internal access (http://core-api:8083) → No authentication

Admin Groups

Users must be members of one of these Authentik groups to access protected endpoints:

• admin
• authentik Admins

Configure user group membership in Authentik admin panel: https://auth.schweitz.net/if/admin/#/identity/users

Authentik Management

• Admin Panel: https://auth.schweitz.net/if/admin/
• Applications: https://auth.schweitz.net/if/admin/#/core/applications
• Providers: https://auth.schweitz.net/if/admin/#/core/providers

API Token Management

The Authentik API token used for automation is stored in: /home/jpmschweitzer/Projects/portainer-core/services/core-api/src/credentials.py

AUTHENTIK_CORE_API_TOKEN = "peXM0EzDv2Wiwycbfm3cE5O44IMAOR8ntUwKVP977yFvVopCzDlKY8tymlMM"

To create additional tokens: https://auth.schweitz.net/if/admin/#/identity/tokens

Security Considerations

1. Client Secret: Stored in config.py (gitignored), consider moving to environment variable
2. Token Validation: Tokens are validated using JWKS from Authentik
3. Token Expiry: Access tokens valid for 60 minutes, refresh tokens for 30 days
4. SSL: All production endpoints should use HTTPS (via NPM)
5. Admin Access: Restrict admin group membership carefully

Troubleshooting

Login Issues

• Check Authentik service status: docker ps | grep authentik
• Check Authentik logs: docker logs authentik-server
• Verify redirect URIs match exactly in Authentik provider config

Token Validation Errors

• Verify OIDC issuer URL is correct
• Check core-api logs: docker logs core-api
• Ensure Authentik is accessible from core-api container

Permission Denied (403)

• Verify user is member of admin group in Authentik
• Check user claims in JWT token at https://jwt.io

Related Documentation

• Security Implementation Plan: /home/jpmschweitzer/Projects/portainer-core/security-implementation-plan.md
• SSO Progress: /home/jpmschweitzer/Projects/portainer-core/SSO_IMPLEMENTATION_PROGRESS.md
• Authentik Docs: https://docs.goauthentik.io/