Portainer

Dieser Leitfaden erklärt, wie man die Single Sign-On (SSO)-Authentifizierung zwischen SmartLink und Portainer mithilfe von OAuth2/OpenID Connect konfiguriert. Die Portainer Business Edition unterstützt die OAuth-Authentifizierung nativ.

Voraussetzungen

Portainer Business Edition (BE) Version 2.11 oder höher
Administratorzugriff auf Portainer
Anwendung in SmartLink mit OpenID Connect konfiguriert
Gültige Portainer Business-Lizenz

Hinweis: Die OAuth-Authentifizierung ist nur in der Portainer Business Edition verfügbar. Die Community Edition (CE) unterstützt nur die lokale und LDAP-Authentifizierung.

Konfiguration in SmartLink

1. Anwendung erstellen

Melden Sie sich als Administrator bei SmartLink an
Gehen Sie zu Anwendungen → Hinzufügen
Erstellen Sie eine neue Anwendung:
- Name: Portainer
- URL: https://portainer.example.com
- Beschreibung: Verwaltung von Docker/Kubernetes-Containern
- Symbol: Wählen Sie das Portainer-Symbol aus

2. OpenID Connect konfigurieren

Im Tab Authentifizierung
Wählen Sie OpenID Connect
Notieren Sie die Informationen:
- Client-ID: portainer-xxxxxx
- Client-Geheimnis: secret-xxxxxx
- Issuer-URL: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]
- App-ID: [appid] (eindeutige Kennung der Anwendung in SmartLink)

3. Erlaubte Umleitungs-URLs

Fügen Sie in Erlaubte Umleitungs-URLs hinzu:

https://portainer.example.com/
https://portainer.example.com/#!/auth

4. Erforderliche Scopes

openid
profile
email
groups (für das Zuordnen von Rollen)

Konfiguration in Portainer

1. Zugriff auf Authentifizierungseinstellungen

Melden Sie sich als Administrator bei Portainer an
Gehen Sie zu Einstellungen → Authentifizierung
Wählen Sie OAuth als Authentifizierungsmethode

2. OAuth2/OpenID Connect konfigurieren

Konfigurieren Sie die OAuth-Parameter:

Anbieterinformationen

Client-ID: portainer-xxxxxx (von SmartLink)
Client-Geheimnis: secret-xxxxxx (von SmartLink)
Autorisierungs-URL: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
Zugriffstoken-URL: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/token
Ressourcen-URL: https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
Umleitungs-URL: https://portainer.example.com/ (automatisch generiert)
Abmelde-URL: https://votre-smartlink.link.vaultys.org/logout
Benutzeridentifikator: sub oder email
Scopes: openid profile email groups

Attributzuordnung

Benutzername: email
Vorname: given_name
Nachname: family_name
E-Mail: email
Gruppen: groups

3. Konfiguration mit Docker

Um Portainer mit der OAuth-Konfiguration bereitzustellen:

version: '3.8'

services:
  portainer:
    image: portainer/portainer-ee:latest
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9443:9443"
      - "8000:8000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    command: >
      --http-disabled
      --ssl-cert /certs/cert.pem
      --ssl-key /certs/key.pem
    environment:
      - PORTAINER_OAUTH_CLIENT_ID=portainer-xxxxxx
      - PORTAINER_OAUTH_CLIENT_SECRET=secret-xxxxxx
      - PORTAINER_OAUTH_AUTH_URL=https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
      - PORTAINER_OAUTH_TOKEN_URL=https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/token
      - PORTAINER_OAUTH_RESOURCE_URL=https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
      - PORTAINER_OAUTH_REDIRECT_URL=https://portainer.example.com/
      - PORTAINER_OAUTH_LOGOUT_URL=https://votre-smartlink.link.vaultys.org/logout
      - PORTAINER_OAUTH_USER_IDENTIFIER=sub
      - PORTAINER_OAUTH_SCOPES=openid profile email groups

volumes:
  portainer_data:

4. Konfiguration mit Kubernetes

Helm-Bereitstellung für Portainer:

# values.yaml
image:
  repository: portainer/portainer-ee
  tag: latest

service:
  type: LoadBalancer
  httpPort: 9000
  httpsPort: 9443

persistence:
  enabled: true
  size: 10Gi

oauth:
  enabled: true
  clientId: "portainer-xxxxxx"
  clientSecret: "secret-xxxxxx"
  authorizationURL: "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/authorize"
  accessTokenURL: "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/token"
  resourceURL: "https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo"
  redirectURL: "https://portainer.example.com/"
  logoutURL: "https://votre-smartlink.link.vaultys.org/logout"
  userIdentifier: "sub"
  scopes: "openid profile email groups"

Rollen- und Berechtigungsverwaltung

Konfiguration automatischer Rollen

Portainer unterstützt mehrere Rollen: Administrator, Operator, Benutzer und HelpDesk.

1. Automatische Benutzerbereitstellung

Aktivieren Sie in Portainer:

Automatische Benutzerbereitstellung: ✅
Standardrolle für neue Benutzer: Benutzer

2. Zuordnung von Gruppen zu Rollen

In den OAuth-Einstellungen von Portainer:

{
  "group_mappings": [
    {
      "group": "portainer-admins",
      "role": "Administrator"
    },
    {
      "group": "portainer-operators",
      "role": "Operator"
    },
    {
      "group": "portainer-users",
      "role": "Benutzer"
    },
    {
      "group": "portainer-helpdesk",
      "role": "HelpDesk"
    }
  ]
}

Teamkonfiguration

Um Benutzer in Teams zu organisieren:

Einstellungen → Teams
Erstellen Sie Teams, die den SmartLink-Gruppen entsprechen
Konfigurieren Sie die automatische Zuordnung:
- Teammitgliedschaftsanbieter: OAuth
- Gruppenanspruch: groups
- Teamzuweisung: Automatisch

Berechtigungen für Endpunkte

Konfigurieren Sie den Zugriff auf verschiedene Umgebungen:

# Konfiguration von Berechtigungen pro Endpunkt
endpoints:
  - name: Produktion
    groups:
      - portainer-prod-admins: Administrator
      - portainer-prod-users: Benutzer
  
  - name: Staging
    groups:
      - portainer-dev-team: Administrator
      - portainer-qa-team: Benutzer
  
  - name: Entwicklung
    groups:
      - portainer-developers: Administrator

Konfigurationstest

1. Test der Erstverbindung

Melden Sie sich von Portainer ab
Klicken Sie auf der Anmeldeseite auf Mit OAuth anmelden
Sie werden zu SmartLink weitergeleitet
Melden Sie sich mit Ihren SmartLink-Anmeldeinformationen an
Sie sollten bei Portainer angemeldet sein

2. Überprüfung der Berechtigungen

# Über die Portainer-API
curl -X GET https://portainer.example.com/api/users/me \
  -H "Authorization: Bearer IHR_TOKEN"

# Erwartete Antwort
{
  "Id": 2,
  "Username": "john.doe",
  "Role": 1,
  "UserTheme": "",
  "PortainerAuthorizations": {...}
}

3. Test mit Docker CLI

# Docker-Context-Konfiguration
docker context create portainer \
  --docker "host=tcp://portainer.example.com:2376,ca=ca.pem,cert=cert.pem,key=key.pem"

# Verwendung
docker context use portainer
docker ps

Umgebungsconfiguration

Hinzufügen von Docker-Umgebungen

Umgebungen → Umgebung hinzufügen
Wählen Sie den Typ aus:
- Docker Standalone
- Docker Swarm
- Kubernetes
- Azure Container Instances
- Docker über API

Konfiguration für Docker Swarm

# docker-compose.yml für den Portainer-Agent
version: '3.8'

services:
  agent:
    image: portainer/agent:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    networks:
      - agent_network
    deploy:
      mode: global
      placement:
        constraints: [node.platform.os == linux]

networks:
  agent_network:
    driver: overlay
    attachable: true

Konfiguration für Kubernetes

# portainer-agent-k8s.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: portainer
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: portainer-sa-clusteradmin
  namespace: portainer
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: portainer-crb-clusteradmin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: portainer-sa-clusteradmin
  namespace: portainer
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: portainer-agent
  namespace: portainer
spec:
  selector:
    matchLabels:
      app: portainer-agent
  template:
    metadata:
      labels:
        app: portainer-agent
    spec:
      serviceAccountName: portainer-sa-clusteradmin
      containers:
      - name: portainer-agent
        image: portainer/agent:latest
        ports:
        - containerPort: 9001
          protocol: TCP

Fehlerbehebung

Fehler "Ungültige OAuth-Konfiguration"

Problem: Die OAuth-Konfiguration ist ungültig

Lösung:

Überprüfen Sie alle URLs (achten Sie auf abschließende Schrägstriche)

Testen Sie die Endpunkte:

curl https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration

Überprüfen Sie die Portainer-Logs:
```
docker logs portainer
```

Fehler "Benutzer hat keinen Zugriff auf eine Umgebung"

Problem: Der Benutzer ist angemeldet, hat aber keinen Zugriff

Lösung:

Überprüfen Sie die Gruppen des Benutzers in SmartLink
Konfigurieren Sie die Endpunktberechtigungen
Weisen Sie neuen Benutzern eine Standardrolle zu

Gruppen werden nicht synchronisiert

Problem: Die SmartLink-Gruppen werden nicht zugeordnet

Lösung:

Stellen Sie sicher, dass der Scope groups angefordert wird

Testen Sie die UserInfo-Antwort:

curl -H "Authorization: Bearer TOKEN" \
  https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo

Überprüfen Sie das Gruppenformat (muss ein Array sein)

SSL-Zertifikatfehler

Problem: SSL-Fehler bei der OAuth-Verbindung

Lösung:

Verwenden Sie gültige Zertifikate (keine selbstsignierten)

Deaktivieren Sie vorübergehend die Überprüfung für Tests:

environment:
  - PORTAINER_OAUTH_SSO_INSECURE_SKIP_VERIFY=true

⚠️ Niemals in der Produktion verwenden

Sicherheit

Empfehlungen

Zwingendes HTTPS: Immer HTTPS verwenden
Isolierung der Umgebungen: Prod/Staging/Dev trennen
Strenge RBAC: Geeignete Rollen verwenden
Audit-Logs: Aktivieren und überwachen Sie die Logs
Geheimnisrotation: Ändern Sie die OAuth-Geheimnisse regelmäßig

Verstärkte Sicherheitskonfiguration

# Sichere Konfiguration
environment:
  # Deaktivieren der lokalen Authentifizierung nach der OAuth-Konfiguration
  - PORTAINER_AUTH_LOCAL_DISABLED=true
  # Session-Timeout
  - PORTAINER_SESSION_TIMEOUT=8h
  # Audit-Logs aktivieren
  - PORTAINER_AUDIT_LOG=true
  # HTTPS erzwingen
  - PORTAINER_HTTP_DISABLED=true

Zugriffsbeschränkung nach IP

# Nginx-Konfiguration zur Beschränkung des Zugriffs
location / {
    # Nur bestimmte IPs zulassen
    allow 10.0.0.0/8;
    allow 192.168.1.0/24;
    deny all;
    
    proxy_pass https://portainer:9443;
    proxy_set_header Host $host;
}

Erweiterte Konfiguration

Integration mit GitOps

# ArgoCD-Konfiguration für Portainer
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: portainer
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/portainer/k8s
    targetRevision: HEAD
    path: charts/portainer
    helm:
      values: |
        oauth:
          enabled: true
          clientId: portainer-xxxxxx
          clientSecret: secret-xxxxxx

Überwachung mit Prometheus

# Metrikkonfiguration
environment:
  - PORTAINER_METRICS_ENABLED=true
  - PORTAINER_METRICS_PORT=9090

# Scrape-Konfiguration Prometheus
scrape_configs:
  - job_name: 'portainer'
    static_configs:
      - targets: ['portainer:9090']

Voraussetzungen​

Konfiguration in SmartLink​

1. Anwendung erstellen​

2. OpenID Connect konfigurieren​

3. Erlaubte Umleitungs-URLs​

4. Erforderliche Scopes​

Konfiguration in Portainer​

1. Zugriff auf Authentifizierungseinstellungen​

2. OAuth2/OpenID Connect konfigurieren​

Anbieterinformationen​

Attributzuordnung​

3. Konfiguration mit Docker​

4. Konfiguration mit Kubernetes​

Rollen- und Berechtigungsverwaltung​

Konfiguration automatischer Rollen​

1. Automatische Benutzerbereitstellung​

2. Zuordnung von Gruppen zu Rollen​

Teamkonfiguration​

Berechtigungen für Endpunkte​

Konfigurationstest​

1. Test der Erstverbindung​

2. Überprüfung der Berechtigungen​

3. Test mit Docker CLI​

Umgebungsconfiguration​

Hinzufügen von Docker-Umgebungen​

Konfiguration für Docker Swarm​

Konfiguration für Kubernetes​

Fehlerbehebung​

Fehler "Ungültige OAuth-Konfiguration"​

Fehler "Benutzer hat keinen Zugriff auf eine Umgebung"​

Gruppen werden nicht synchronisiert​

SSL-Zertifikatfehler​

Sicherheit​

Empfehlungen​

Verstärkte Sicherheitskonfiguration​

Zugriffsbeschränkung nach IP​

Erweiterte Konfiguration​

Integration mit GitOps​

Überwachung mit Prometheus​

Ressourcen​

Voraussetzungen

Konfiguration in SmartLink

1. Anwendung erstellen

2. OpenID Connect konfigurieren

3. Erlaubte Umleitungs-URLs

4. Erforderliche Scopes

Konfiguration in Portainer

1. Zugriff auf Authentifizierungseinstellungen

2. OAuth2/OpenID Connect konfigurieren

Anbieterinformationen

Attributzuordnung

3. Konfiguration mit Docker

4. Konfiguration mit Kubernetes

Rollen- und Berechtigungsverwaltung

Konfiguration automatischer Rollen

1. Automatische Benutzerbereitstellung

2. Zuordnung von Gruppen zu Rollen

Teamkonfiguration

Berechtigungen für Endpunkte

Konfigurationstest

1. Test der Erstverbindung

2. Überprüfung der Berechtigungen

3. Test mit Docker CLI

Umgebungsconfiguration

Hinzufügen von Docker-Umgebungen

Konfiguration für Docker Swarm

Konfiguration für Kubernetes

Fehlerbehebung

Fehler "Ungültige OAuth-Konfiguration"

Fehler "Benutzer hat keinen Zugriff auf eine Umgebung"

Gruppen werden nicht synchronisiert

SSL-Zertifikatfehler

Sicherheit

Empfehlungen

Verstärkte Sicherheitskonfiguration

Zugriffsbeschränkung nach IP

Erweiterte Konfiguration

Integration mit GitOps

Überwachung mit Prometheus

Ressourcen