Connexion d'entreprise¶

Avec une connexion d'entreprise, les personnes de votre organisation se connectent à OS avec le compte qu'elles ont déjà chez votre propre fournisseur d'identité, comme Microsoft Entra ID, Google Workspace ou Okta, par OpenID Connect ou SAML. Cette page montre comment configurer une connexion d'entreprise, l'essayer, la rendre obligatoire, qui peut se connecter sans elle, qui peut s'affilier de lui-même et comment la supprimer. Il n'y a pas encore d'écran pour cela : un administrateur utilise l'API d'OS, avec les routes ci-dessous.

Qui peut faire quoi¶

Un org-admin de l'organisation peut configurer, modifier et supprimer la connexion d'entreprise. Qui la configure doit aussi pouvoir gérer le domaine auquel elle appartient (Gérer les rôles). Chaque membre peut lire où en est la connexion.

Une organisation a au plus une connexion d'entreprise. Elle appartient à un domaine que votre organisation a prouvé, par exemple jansen.fr (Domaines et adresses). Prouvez donc d'abord le domaine.

Configurer une connexion OpenID Connect¶

1. Chez votre fournisseur d'identité, créez une application pour OS. Vous obtenez un identifiant client et un secret.

2. Configurez la connexion avec PUT /api/v1/organisations/{id}/company-login et l'en-tête If-Match: "0" :

   Champ	Ce que vous renseignez
   kind	oidc
   display_name	le nom sur la page de connexion, 64 caractères au plus, par exemple Jansen
   domain	le domaine prouvé, par exemple jansen.fr
   authorization_url, token_url, jwks_url, issuer	les adresses de votre fournisseur ; elles figurent dans son document de découverte (/.well-known/openid-configuration)
   client_id, client_secret	ce que votre fournisseur vous a donné
   client_auth_method	client_secret_basic ou client_secret_post, comme votre fournisseur le demande

3. OS répond 202 avec la connexion, au statut pending. Lisez redirect_uri dans la réponse et ajoutez cette adresse chez votre fournisseur comme adresse de redirection de l'application. Elle se termine par /broker/os-<identifiant de votre organisation>/endpoint.

Chaque adresse doit commencer par https://, nommer un nom d'hôte (pas une adresse IP), n'avoir aucun port sauf 443 et faire 2 048 caractères au plus. Aucune réponse ne contient le secret : OS le conserve chiffré jusqu'à ce que la connexion soit active, puis le jette.

Configurer une connexion SAML¶

Configurez la connexion avec la même route et kind: saml :

Donnez ensuite à votre fournisseur l'adresse de metadata_url dans la réponse : elle contient tout ce que votre fournisseur doit savoir d'OS. OS demande des réponses signées et l'adresse e-mail comme NameID.

Ce que dit le statut¶

OS met la connexion dans Keycloak, le service de connexion d'OS, puis la relit. GET /api/v1/organisations/{id}/company-login montre où l'on en est :

Quand le service de connexion refuse la modification d'une connexion qui fonctionnait déjà, la version précédente continue de fonctionner : applied_version nomme cette version. Quand il a accepté les nouveaux réglages et qu'une étape suivante a échoué, les nouveaux réglages s'appliquent déjà ; vérifiez-les et configurez de nouveau la connexion, avec le secret.

Essayer la connexion¶

OS n'appelle jamais lui-même votre fournisseur, il n'y a donc pas de bouton qui teste la connexion. Essayez-la vous-même : ouvrez une fenêtre privée, allez sur OS et connectez-vous avec une adresse de votre domaine. La réponse nomme aussi sign_in_hint ; avec lui, OS envoie directement quelqu'un chez votre fournisseur. Faites-le avant de rendre la connexion obligatoire.

Rendre la connexion obligatoire¶

Quand la connexion est obligatoire, un membre n'accède à votre organisation que s'il s'est connecté par la connexion d'entreprise. Activez-le avec PATCH /api/v1/organisations/{id}/company-login et {"required": true}, avec dans If-Match la version que vous avez lue.

OS refuse (409) tant que la connexion n'est pas active, ou si vous ne vous êtes pas connecté vous-même par la connexion, n'êtes pas une exception et ne gérez pas l'organisation d'en haut. Ainsi vous ne vous enfermez pas dehors avec une connexion qui ne fonctionne pas.

Un membre qui s'est connecté autrement reçoit 403 avec le type de problème company-login-required et le sign_in_hint de votre connexion ; OS le déconnecte alors et le reconnecte par la connexion d'entreprise. Un administrateur d'un partenaire qui gère votre organisation d'en haut relève de la règle de sa propre organisation, pas de la vôtre.

Exceptions¶

Pour le jour où votre fournisseur ne fonctionne pas, vous pouvez désigner au plus trois membres qui peuvent aussi se connecter autrement. PUT /api/v1/organisations/{id}/company-login/exemptions/{membership_id} ajoute un membre, DELETE sur la même adresse le retire. La réponse les nomme sous exemptions. Une exception prend fin quand l'appartenance est désactivée ou supprimée. Chaque fois qu'une exception se connecte autrement, cela figure dans le journal d'audit.

Vous pouvez aussi inviter une personne dont l'adresse est hors du domaine que votre connexion dirige, par exemple un conseiller externe, avec l'une des trois exceptions : "company_login_exempt": true dans le corps de POST /api/v1/organisations/{id}/invitations. L'invitation compte alors parmi les trois et figure aussitôt sous exemptions ; la personne la garde en acceptant, et elle prend fin quand l'invitation est retirée ou expire.

S'affilier soi-même¶

joining décide de ce qui arrive à une personne qui se connecte par la connexion d'entreprise avec une adresse de votre domaine mais n'est pas encore membre :

Modifiez-le avec PATCH et {"joining": "automatic"}. L'affiliation fonctionne aussi pour une personne qui se connecte pour la première fois par la connexion d'entreprise : OS accepte pour cela son adresse parce qu'elle se trouve dans votre domaine prouvé et que la personne est entrée par votre propre connexion.

Modifier la connexion¶

Renvoyez toute la connexion avec PUT, avec dans If-Match la version que vous avez lue, et le secret avec. Le type (oidc ou saml) ne peut pas changer ; supprimez alors la connexion et configurez-en une nouvelle. Tant que le service de connexion n'accepte pas la modification, la version précédente continue de fonctionner.

Supprimer la connexion¶

DELETE /api/v1/organisations/{id}/company-login, avec If-Match, supprime la connexion. Elle n'est alors plus obligatoire aussitôt, et les exceptions prennent fin. Les membres et leurs comptes restent : qui a aussi un mot de passe se connecte avec ; qui se connectait seulement par la connexion d'entreprise définit un mot de passe par Mot de passe oublié ? sur la page de connexion. Si vous abandonnez le domaine, la connexion disparaît avec lui (Domaines et adresses).

Quand OS refuse¶

Ce qu'OS surveille¶

Toutes les cinq minutes, OS vérifie que votre connexion dans le service de connexion est toujours telle qu'OS l'a mise en place, et rétablit ce que quelqu'un a changé en dehors d'OS. Vous n'avez rien à faire pour cela. Chaque modification que vous faites figure dans le journal d'audit, sans le secret.