Portainer

Ce guide vous explique comment configurer l'authentification unique (SSO) entre SmartLink 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 SmartLink 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 SmartLink

1. Créer l'application

1. Connectez-vous à SmartLink 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 SmartLink)

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
• groups (pour le mapping des rôles)

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 SmartLink)
• Client secret : secret-xxxxxx (depuis SmartLink)
• Authorization URL : https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/authorize
• 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/logout
• User identifier : sub ou email
• Scopes : openid profile email groups

Mapping des attributs

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

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]/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. 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]/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"

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

Dans les paramètres OAuth de Portainer :

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

Configuration des équipes

Pour organiser les utilisateurs en équipes :

1. Settings → Teams
2. Créez des équipes correspondant aux groupes SmartLink
3. Configurez le mapping automatique :
   • Team membership provider : OAuth
   • Group claim : groups
   • Team assignment : Automatic

Permissions sur les endpoints

Configurez les accès aux différents environnements :

# Configuration des permissions par endpoint
endpoints:
  - name: Production
    groups:
      - portainer-prod-admins: Administrator
      - portainer-prod-users: User
  
  - name: Staging
    groups:
      - portainer-dev-team: Administrator
      - portainer-qa-team: User
  
  - name: Development
    groups:
      - portainer-developers: Administrator

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 SmartLink
4. Authentifiez-vous avec vos identifiants SmartLink
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 groupes de l'utilisateur dans SmartLink
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 SmartLink ne sont pas mappés

Solution :

1. Vérifiez que le scope groups est bien demandé
2. Testez la réponse UserInfo :

   curl -H "Authorization: Bearer TOKEN" \
     https://votre-smartlink.link.vaultys.org/api/oidc/[appid]/userinfo
3. Vérifiez le format des groupes (doit être un array)

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

• Documentation Portainer OAuth
• Portainer Business Features
• API Portainer
• Forum Portainer