Aller au contenu principal

Portainer

Ce guide vous explique comment configurer l'authentification unique (SSO) entre VaultysHub et Portainer en utilisant OAuth2/OpenID Connect. Portainer Business Edition supporte nativement l'authentification OAuth.

Prérequis​

  • Portainer Business Edition (BE) version 2.11 ou supérieure
  • Accès administrateur à Portainer
  • Application configurée dans VaultysHub avec OpenID Connect
  • Licence Portainer Business valide

Note : L'authentification OAuth n'est disponible que dans Portainer Business Edition. La version Community Edition (CE) ne supporte que l'authentification locale et LDAP.

Configuration dans VaultysHub​

1. Créer l'application​

  1. Connectez-vous à VaultysHub en tant qu'administrateur
  2. Allez dans Applications → Ajouter
  3. Créez une nouvelle application :
    • Nom : Portainer
    • URL : https://portainer.example.com
    • Description : Gestion des conteneurs Docker/Kubernetes
    • Icône : Choisissez l'icône Portainer

2. Configurer OpenID Connect​

  1. Dans l'onglet Authentification
  2. Sélectionnez OpenID Connect
  3. Notez les informations :
    • Client ID : portainer-xxxxxx
    • Client Secret : secret-xxxxxx
    • Issuer URL : https://votre-smartlink.link.vaultys.org/api/oidc/[appid]
    • App ID : [appid] (identifiant unique de l'application dans VaultysHub)

3. URLs de redirection​

Ajoutez dans URLs de redirection autorisées :

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

4. Scopes requis​

  • openid
  • profile
  • email

Configuration dans Portainer​

1. Accès aux paramètres d'authentification​

  1. Connectez-vous à Portainer en tant qu'administrateur
  2. Allez dans Settings → Authentication
  3. Sélectionnez OAuth dans la méthode d'authentification

2. Configuration OAuth2/OpenID Connect​

Configurez les paramètres OAuth :

Informations du provider​

  • Client ID : portainer-xxxxxx (depuis VaultysHub)
  • Client secret : secret-xxxxxx (depuis VaultysHub)
  • Authorization URL : https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/auth
  • Access token URL : https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/token
  • Resource URL : https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
  • Redirect URL : https://portainer.example.com/ (généré automatiquement)
  • Logout URL : https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/logout
  • User identifier : sub ou email
  • Scopes : openid profile email

Mapping des attributs​

  • Username : email
  • Given name : given_name
  • Family name : family_name
  • Email : email

3. Configuration avec Docker​

Pour déployer Portainer avec la configuration OAuth :

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]/auth
      - 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/api/oidc/[appid]/logout
      - PORTAINER_OAUTH_USER_IDENTIFIER=sub
      - PORTAINER_OAUTH_SCOPES=openid profile email

volumes:
  portainer_data:

4. Configuration avec Kubernetes​

Déploiement Helm pour 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]/auth"
  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/api/oidc/[appid]/logout"
  userIdentifier: "sub"
  scopes: "openid profile email"

Gestion des rôles et permissions​

Configuration des rôles automatiques​

Portainer supporte plusieurs rôles : Administrator, Operator, User, et HelpDesk.

1. Création automatique d'utilisateurs​

Dans Portainer, activez :

  • Automatic user provisioning : ✅
  • Default role for new users : User

2. Mapping des groupes vers les rôles​

VaultysHub ne transmet pas les groupes de l'utilisateur : le mapping automatique des groupes vers les rôles n'est pas possible. Les nouveaux utilisateurs reçoivent le rôle par défaut ci-dessus, puis les rôles sont attribués directement dans Portainer.

Configuration des équipes​

Pour organiser les utilisateurs en équipes :

  1. Settings → Teams
  2. Créez les équipes nécessaires
  3. Ajoutez-y les utilisateurs manuellement (l'affectation automatique par claim de groupe n'est pas disponible avec VaultysHub)

Permissions sur les endpoints​

Configurez les accès aux différents environnements directement dans Portainer, en attribuant chaque environnement à des équipes ou à des utilisateurs.

Test de la configuration​

1. Test de connexion initiale​

  1. Déconnez-vous de Portainer
  2. Sur la page de connexion, cliquez sur Login with OAuth
  3. Vous êtes redirigé vers VaultysHub
  4. Authentifiez-vous avec vos identifiants VaultysHub
  5. Vous devez être connecté à Portainer

2. Vérification des permissions​

# Via l'API Portainer
curl -X GET https://portainer.example.com/api/users/me \
  -H "Authorization: Bearer YOUR_TOKEN"

# Réponse attendue
{
  "Id": 2,
  "Username": "john.doe",
  "Role": 1,
  "UserTheme": "",
  "PortainerAuthorizations": {
    "EndpointResourcesAccess": {...},
    "PortainerResourcesAccess": {...}
  }
}

3. Test avec Docker CLI​

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

# Utilisation
docker context use portainer
docker ps

Configuration des environnements​

Ajout d'environnements Docker​

  1. Environments → Add environment
  2. Choisissez le type :
    • Docker Standalone
    • Docker Swarm
    • Kubernetes
    • Azure Container Instances
    • Docker via API

Configuration pour Docker Swarm​

# docker-compose.yml pour l'agent Portainer
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

Configuration pour 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

Dépannage​

Erreur "Invalid OAuth configuration"​

Problème : La configuration OAuth n'est pas valide

Solution :

  1. Vérifiez tous les URLs (attention aux trailing slashes)
  2. Testez les endpoints : 
    curl https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration
  3. Vérifiez les logs Portainer : 
    docker logs portainer

Erreur "User does not have access to any environment"​

Problème : L'utilisateur est connecté mais n'a pas d'accès

Solution :

  1. Vérifiez les équipes de l'utilisateur dans Portainer
  2. Configurez les permissions d'endpoint
  3. Assignez un rôle par défaut aux nouveaux utilisateurs

Les groupes ne sont pas synchronisés​

Problème : Les groupes VaultysHub ne sont pas mappés

Solution : c'est le comportement attendu. VaultysHub ne transmet pas les groupes : attribuez les rôles et les équipes directement dans Portainer.

Erreur de certificat SSL​

Problème : Erreur SSL lors de la connexion OAuth

Solution :

  1. Utilisez des certificats valides (pas auto-signés)
  2. Pour les tests, désactivez temporairement la vérification : 
    environment:
      - PORTAINER_OAUTH_SSO_INSECURE_SKIP_VERIFY=true
  3. ⚠️ Ne jamais utiliser en production

Sécurité​

Recommandations​

  1. HTTPS obligatoire : Toujours utiliser HTTPS
  2. Isolation des environnements : Séparez prod/staging/dev
  3. RBAC strict : Utilisez les rôles appropriés
  4. Audit logs : Activez et surveillez les logs
  5. Rotation des secrets : Changez régulièrement les secrets OAuth

Configuration de sécurité renforcée​

# Configuration sécurisée
environment:
  # Désactiver l'authentification locale après configuration OAuth
  - PORTAINER_AUTH_LOCAL_DISABLED=true
  # Timeout de session
  - PORTAINER_SESSION_TIMEOUT=8h
  # Activer les logs d'audit
  - PORTAINER_AUDIT_LOG=true
  # Forcer HTTPS
  - PORTAINER_HTTP_DISABLED=true

Limitation d'accès par IP​

# Configuration Nginx pour limiter l'accès
location / {
    # Autoriser uniquement certaines IPs
    allow 10.0.0.0/8;
    allow 192.168.1.0/24;
    deny all;
    
    proxy_pass https://portainer:9443;
    proxy_set_header Host $host;
}

Configuration avancée​

Intégration avec GitOps​

# Configuration ArgoCD pour 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

Monitoring avec Prometheus​

# Configuration des métriques
environment:
  - PORTAINER_METRICS_ENABLED=true
  - PORTAINER_METRICS_PORT=9090

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

Ressources​