Brancher HelloID en SSO SAML sur Amazon Connect (et les 3 pièges)

Amazon Connect n'a pas d'écran de configuration SAML : tout se passe dans IAM et côté IdP. Voici la méthode de bout en bout, avec les trois pièges à éviter.

Vous créez une instance Amazon Connect en cochant « SAML 2.0-based authentication », elle démarre, et lorsque vous cherchez l’écran de configuration du SSO, vous réalisez qu’il n’existe pas : Connect n’a tout simplement aucune page de configuration SAML, parce que tout se monte ailleurs.

Le SSO se configure dans IAM et côté IdP, jamais dans Connect : quatre étapes, et trois pièges à éviter. Les exemples utilisent eu-central-1 et des valeurs anonymisées (<ACCOUNT_ID>, <INSTANCE_ID>).

Le principe

HelloID (adossé à Active Directory) reste la source de vérité, et Connect ne fait qu’autoriser un utilisateur déjà authentifié. Le flux est IdP-initiated : l’agent part toujours du portail HelloID, jamais de l’URL Connect.

Côté AWS, on crée un fournisseur d’identité et un rôle ; côté HelloID, une application SAML ; et dans Connect, les utilisateurs eux-mêmes.

Prérequis : l’instance doit être créée en mode SAML. Ce mode est figé à la création, donc une instance « Store users in Amazon Connect » ne se convertit pas et il faut en recréer une.

Étape 1 : déclarer HelloID dans IAM

Récupérez les métadonnées SAML de HelloID (un fichier XML). Elles doivent contenir le certificat de signature (<X509Certificate>), sinon AWS refuse l’import, et comme l’export HelloID l’oublie une fois sur deux, pensez à le redemander avec le certificat embarqué.

aws iam create-saml-provider \
  --name helloid \
  --saml-metadata-document file://helloid-metadata.xml

Ce que ça fait :

• Déclare l’IdP de confiance et stocke son certificat de validation
• Produit l’ARN arn:aws:iam::<ACCOUNT_ID>:saml-provider/helloid, réutilisé partout ensuite

Étape 2 : le rôle de fédération

C’est le rôle que l’assertion permet d’assumer. Il a deux faces : qui peut l’assumer (trust.json) et ce qu’il autorise une fois assumé (permission.json).

// trust.json
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Federated": "arn:aws:iam::<ACCOUNT_ID>:saml-provider/helloid" },
    "Action": "sts:AssumeRoleWithSAML",
    "Condition": { "StringEquals": { "SAML:aud": [
      "https://eu-central-1.signin.aws.amazon.com/saml",
      "https://signin.aws.amazon.com/saml"
    ] } }
  }]
}

// permission.json
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "connect:GetFederationToken",
    "Resource": "arn:aws:connect:eu-central-1:<ACCOUNT_ID>:instance/<INSTANCE_ID>/user/${aws:userid}"
  }]
}

aws iam create-role --role-name connect-saml \
  --assume-role-policy-document file://trust.json \
  --max-session-duration 43200

aws iam put-role-policy --role-name connect-saml \
  --policy-name connect-getfederationtoken \
  --policy-document file://permission.json

Ce que ça fait :

• create-role crée le rôle, le fait faire confiance à l’IdP et autorise des sessions jusqu’à 12h
• put-role-policy lui donne le seul droit utile, celui d’ouvrir une session Connect (GetFederationToken)

Étape 3 : l’app côté HelloID

Ne partez surtout pas d’un mapping SAML générique, car il nettoie les : et / et ne sait donc pas émettre les noms d’attributs AWS. Partez plutôt du template AWS du catalogue HelloID (cherchez « AppStream », le mécanisme SAML est identique pour Connect), puis ouvrez Configuration → Configure Mapping Set → Change mappings :

https://aws.amazon.com/SAML/Attributes/Role
  → arn:aws:iam::<ACCOUNT_ID>:role/connect-saml,arn:aws:iam::<ACCOUNT_ID>:saml-provider/helloid
https://aws.amazon.com/SAML/Attributes/RoleSessionName
  → l'email de l'utilisateur

Role est une seule valeur : les deux ARN (le rôle, puis le provider) séparés par une virgule, sans espace. Côté paramètres SAML, renseignez ensuite :

Audience   : urn:amazon:webservices
ACS        : https://eu-central-1.signin.aws.amazon.com/saml
RelayState : https://eu-central-1.console.aws.amazon.com/connect/federate/<INSTANCE_ID>

Étape 4 : les utilisateurs Connect

Chaque agent doit exister dans Connect. Vous pouvez les créer à la main depuis la console d’administration (rubrique « User management »), ou en masse via l’import CSV, et la CLI ci-dessous est surtout pratique pour scripter le provisioning de plusieurs agents. Dans tous les cas, le nom d’utilisateur doit être identique à l’identité fédérée, c’est-à-dire l’email.

aws connect create-user \
  --instance-id <INSTANCE_ID> \
  --username jean.dupont@domaine.com \
  --phone-config '{"PhoneType":"SOFT_PHONE"}' \
  --routing-profile-id <ROUTING_PROFILE_ID> \
  --security-profile-ids <SECURITY_PROFILE_ID> \
  --identity-info '{"FirstName":"Jean","LastName":"Dupont"}' \
  --region eu-central-1

Ce que ça fait :

• Crée l’agent avec un username égal à son email exact, à la casse près, faute de quoi le login est refusé
• N’attend pas de mot de passe (l’authentification est fédérée) ni de champ Email dans identity-info, que l’API refuse sur une instance SAML

Débugger : lisez l’assertion

En cas d’erreur, la vérité est dans l’assertion. Ouvrez les DevTools sur l’onglet Network, activez « Preserve log », rejouez le login, puis ouvrez la requête POST vers .../saml et lisez le champ SAMLResponse (base64) : une fois décodé, il contient tout, de l’issuer à la signature en passant par l’audience, le recipient et les attributs.

Les 3 pièges

1. Les noms d’attributs doivent être des URN complets

Le mapping générique envoie RoleSessionName (le nom court) et oublie carrément Role, ce à quoi AWS répond Your request included an invalid SAML response. Fix : le template AWS de l’étape 3 porte les noms complets, et il ne reste qu’à remplacer les placeholders {Role ARN} et {Provider ARN}, qu’on laisse en l’état une fois sur deux.

2. Changer de template change l’issuer

Recréer l’application change le entityID (l’issuer) des métadonnées, et comme AWS associe une assertion à un provider par son issuer, l’ancien provider ne reconnaît plus rien. Fix : mettez le provider à jour, son ARN ne bouge pas :

aws iam update-saml-provider \
  --saml-provider-arn arn:aws:iam::<ACCOUNT_ID>:saml-provider/helloid \
  --saml-metadata-document file://nouvelles-metadonnees.xml

3. SAML:aud, c’est le Recipient, pas l’Audience

Le nom de la clé est trompeur : la condition SAML:aud matche le champ Recipient (l’URL ACS), pas l’élément <Audience>. Or Connect utilise l’ACS régional, donc le Recipient l’est aussi. Symptôme : vous passez l’écran de sélection de rôle, preuve que le SAML est validé, puis vous butez sur Not authorized to perform sts:AssumeRoleWithSAML. Fix : autorisez l’endpoint régional dans SAML:aud, ce qui est déjà fait dans la trust policy de l’étape 2.

---

Avant : des comptes locaux Connect, des mots de passe à gérer et aucun SSO. Après : un login fédéré HelloID, le MFA et l’accès conditionnel pilotés par l’IdP, et zéro mot de passe stocké côté Connect.

Une fois ces trois pièges franchis, la chaîne est solide et ne bouge plus. Besoin d’un coup de main pour fédérer votre centre de contact Amazon Connect ? Parlons-en.