Portainer

This guide explains how to configure single sign-on (SSO) between VaultysHub and Portainer using OAuth2/OpenID Connect. Portainer Business Edition natively supports OAuth authentication.

Prerequisites

• Portainer Business Edition (BE) version 2.11 or higher
• Administrator access to Portainer
• Application configured in VaultysHub with OpenID Connect
• Valid Portainer Business license

Note: OAuth authentication is only available in Portainer Business Edition. The Community Edition (CE) only supports local and LDAP authentication.

Configuration in VaultysHub

1. Create the application

1. Log in to VaultysHub as an administrator
2. Go to Applications → Add
3. Create a new application:
   • Name: Portainer
   • URL: https://portainer.example.com
   • Description: Docker/Kubernetes container management
   • Icon: Choose the Portainer icon

2. Configure OpenID Connect

1. In the Authentication tab
2. Select OpenID Connect
3. Note the information:
   • Client ID: portainer-xxxxxx
   • Client Secret: secret-xxxxxx
   • Issuer URL: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]
   • App ID: [appid] (unique identifier of the application in VaultysHub)

3. Redirect URLs

Add the Portainer address in Redirect URI, identical to the Redirect URL field in Portainer:

https://portainer.example.com/

4. Required scopes

• openid
• profile
• email

Configuration in Portainer

1. Access authentication settings

1. Log in to Portainer as an administrator
2. Go to Settings → Authentication
3. Select OAuth as the authentication method

2. Configure OAuth2/OpenID Connect

Configure the OAuth settings:

Provider information (Settings → Authentication → OAuth → Custom)

Field	Value
Client ID / Client secret	those of the VaultysHub application
Authorization URL	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/auth
Access token URL	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/token
Resource URL	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/userinfo
Redirect URL	https://portainer.example.com/ (identical to the URI declared in VaultysHub)
Logout URL	https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/logout (optional)
User identifier	email
Scopes	openid email profile (separated by spaces)
Auth Style	In Header (VaultysHub expects the secret in the Basic header, client_secret_basic)

Enable Automatic user provisioning to create accounts on first login, with a default team if needed.

Configuration in the interface only

Portainer is configured in its administration interface (or via its API), not through environment variables.

Role and permission management

Automatic role configuration

Portainer supports several roles: Administrator, Operator, User, and HelpDesk.

1. Automatic user creation

In Portainer, enable:

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

2. Mapping groups to roles

VaultysHub does not transmit user groups: automatic mapping of groups to roles is not possible. New users receive the default role above, then roles are assigned directly in Portainer.

Team configuration

To organize users into teams:

1. Settings → Teams
2. Create the necessary teams
3. Manually add users (automatic assignment by group claim is not available with VaultysHub)

Permissions on endpoints

Configure access to different environments directly in Portainer, assigning each environment to teams or users.

Testing the configuration

1. Initial login test

1. Log out of Portainer
2. On the login page, click Login with OAuth
3. You are redirected to VaultysHub
4. Authenticate with your VaultysHub credentials
5. You should be logged into Portainer

2. Permission verification

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

# Expected response
{
  "Id": 2,
  "Username": "john.doe",
  "Role": 1,
  "UserTheme": "",
  "PortainerAuthorizations": {
    "EndpointResourcesAccess": {...},
    "PortainerResourcesAccess": {...}
  }
}

3. Test with Docker CLI

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

# Usage
docker context use portainer
docker ps

Environment configuration

Adding Docker environments

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

Configuration for Docker Swarm

# docker-compose.yml for the 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

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

Troubleshooting

"Invalid OAuth configuration" error

Problem: The OAuth configuration is not valid

Solution:

1. Check all URLs (pay attention to trailing slashes)
2. Test the endpoints:

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

3. Check the Portainer logs:

   docker logs portainer

"User does not have access to any environment" error

Problem: The user is logged in but has no access

Solution:

1. Check the user's teams in Portainer
2. Configure endpoint permissions
3. Assign a default role to new users

Groups are not synchronized

Problem: VaultysHub groups are not mapped

Solution: This is the expected behavior. VaultysHub does not transmit groups: assign roles and teams directly in Portainer.

SSL certificate error

Problem: SSL error during OAuth connection

Solution: Portainer must trust the VaultysHub certificate. With an internal certificate authority, add it to the Portainer container's certificate store (e.g., via SSL_CERT_DIR).

Security

Recommendations

1. HTTPS required: Always use HTTPS
2. Environment isolation: Separate prod/staging/dev
3. Strict RBAC: Use appropriate roles
4. Audit logs: Enable and monitor logs
5. Secret rotation: Regularly change OAuth secrets

IP access restriction

# Nginx configuration to limit access
location / {
    # Allow only certain 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;
}

Resources

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