Provisionnement personnalisé d’Office 365

Découvrez comment configurer le provisionnement personnalisé Azure AD pour fournir un accès à votre environnement Office 365 à l’aide de l’intégration Auth0.

La configuration par défaut d’Office 365 comprend Active Directory et les services DirSync/Azure AD Sync, qui synchronisent et provisionnent les utilisateurs AD présents dans votre Azure AD afin d’assurer l’SSO. Dans cette configuration, Auth0 est le fournisseur d’identité et fournit l’authentification unique (SSO) à ces utilisateurs.

Mais que faire si vous souhaitez permettre à des sous-traitants, des partenaires ou même à des clients d’accéder à votre environnement Office 365 (par ex., SharePoint) ? Dans ce cas, l’approche par défaut n’est pas idéale, car ces utilisateurs devraient être créés dans votre environnement AD. Vous devez plutôt effectuer un provisionnement personnalisé des utilisateurs Azure AD à l’aide des Rules Auth0.

Le provisionnement personnalisé vous permet de créer des utilisateurs dans Azure AD (et donc, concrètement, dans Office 365) au moment même où ils se connectent à partir de n’importe quelle connexion disponible dans Auth0. (Dans ce cas, votre règle remplit le rôle de DirSync pour tout type de connexion avec lequel DirSync ne fonctionnerait pas.) Cette configuration vous permet d’offrir diverses options de connexion (notamment Facebook, LinkedIn et Google Workspace) pour votre environnement Office 365.

​

Prérequis

Avant de pouvoir configurer le provisionnement personnalisé, vous devez :

• Configurer Office 365 : enregistrer un domaine personnalisé et configurer Office 365 comme application tierce dans Auth0.

​

Configurer Azure AD

Le provisionnement personnalisé utilise l’API Graph d’Azure AD pour provisionner de nouveaux utilisateurs dans Azure AD. Pour accéder à l’API Graph d’Azure AD, vous devez créer une application dans l’annuaire Azure AD qui a été liée à l’abonnement Office 365 :

1. Connectez-vous à l’Azure Portal.

2. Choisissez Azure Active Directory dans le menu de navigation de gauche.

3. Sélectionnez App registrations dans le nouveau menu.

4. Cliquez sur New application registration.

5. Remplissez le formulaire :

   1. Entrez un nom pour l’application (par exemple Auth0 Provisioning)
   2. Sélectionnez Web app / API comme Type d’application.
   3. Saisissez une URL de connexion. Vous pouvez entrer n’importe quelle URL valide; elle ne sera pas vraiment utilisée.

6. L’application nouvellement créée apparaîtra dans la liste App registrations. Sélectionnez-la.

7. Dans le volet Settings (Microsoft appelle ces sections des « blades »), choisissez Keys.

8. Entrez une Description (par exemple Auth0 Provision), puis choisissez une Duration pour la nouvelle clé. Si vous choisissez d’émettre une clé non permanente, notez la date d’expiration et créez un rappel pour remplacer la clé avant son expiration.

9. Cliquez pour enregistrer la clé, puis copiez l’App Key. Cette clé ne sera affichée qu’une seule fois et elle est nécessaire pour la règle Auth0.

10. Choisissez Required permissions, puis cliquez sur Add dans le nouveau volet.

11. Sélectionnez l’API Microsoft Graph, puis cochez Read and write directory data sous Application Permissions.

12. De retour dans Required permissions, cliquez sur le bouton Grant Permissions, puis sur Yes pour accorder les autorisations demandées.

​

Créez la règle de provisionnement Azure AD

La règle suivante illustre le processus de provisionnement :

1. Si l’utilisateur provient de la connexion AD, ignorez le processus de provisionnement (car il sera pris en charge par DirSync).
2. Si l’utilisateur a déjà été provisionné dans Azure AD, poursuivez simplement la transaction de connexion.
3. Utilisez le Client ID et la clé Azure AD pour obtenir un jeton d’accès pour la Graph API.
4. Créez un utilisateur dans Azure AD.
5. Attribuez une licence à l’utilisateur.
6. Poursuivez la transaction de connexion.

Le nom d’utilisateur est généré par la fonction createAzureADUser, qui, par défaut, génère un nom d’utilisateur au format [e-mail]. Vous pouvez le modifier comme bon vous semble; assurez-vous simplement que cette valeur est unique pour tous vos utilisateurs.

Assurez-vous de définir les bonnes valeurs pour AUTH0_OFFICE365_CLIENT_ID, AAD_CUSTOM_DOMAIN, AAD_DOMAIN, AAD_APPLICATION_ID et AAD_APPLICATION_API_KEY dans votre objet de configuration afin de rendre ces valeurs accessibles dans le code de votre règle. Pour en savoir plus, consultez Store Configuration for Rules.

Dans le code, vous verrez aussi que la règle attend environ 15 secondes après le provisionnement de l’utilisateur. C’est parce qu’il faut quelques secondes avant que l’utilisateur provisionné soit disponible dans Office 365.

function (user, context, callback) {
  // Importer les packages Node.js que nous allons utiliser.
  // Consultez ce site Web pour obtenir la liste complète des packages disponibles :
  // https://auth0-extensions.github.io/canirequire/
  var rp = require('request-promise');
  var uuidv4 = require('uuid');

  // Le nom de votre connexion Active Directory (si vous en utilisez une)
  var AUTH0_AD_CONNECTION = 'Travel0AD';
  // Le client_id de votre intégration SSO Office 365
  // Vous pouvez l'obtenir depuis l'URL lors de la modification de l'intégration SSO,
  // elle ressemblera à
  // https://manage.auth0.com/#/externalapps/{the_client_id}/settings
  var AUTH0_OFFICE365_CLIENT_ID = configuration.AUTH0_OFFICE365_CLIENT_ID;
  // Le domaine principal de notre entreprise.
  var YOUR_COMPANY_DOMAIN = 'mycompanyurl.com';
  // Votre domaine Azure AD.
  var AAD_DOMAIN = configuration.AAD_DOMAIN;
  // L'ID d'application généré lors de la création de l'application Azure AD.
  var AAD_APPLICATION_ID = configuration.AAD_APPLICATION_ID;
  // La clé API générée pour l'application Azure AD.
  var AAD_APPLICATION_API_KEY = configuration.AAD_APPLICATION_API_KEY;
  // L'emplacement des utilisateurs qui accéderont aux produits Microsoft.
  var AAD_USAGE_LOCATION = 'US';
  // Azure AD ne reconnaît pas l'utilisateur instantanément, il faut quelques secondes
  var AAD_USER_CREATE_DELAY = 15000;
  // La clé représentant la licence à attribuer au nouvel utilisateur.
  // Consultez l'URL suivante pour obtenir la liste des licences existantes :
  // https://gist.github.com/Lillecarl/3c4727e6dcd1334467e0
  var OFFICE365_KEY = 'O365_BUSINESS';

  // N'exécuter cette règle que pour l'intégration SSO Office 365.
  if (context.clientID !== AUTH0_OFFICE365_CLIENT_ID) {
    return callback(null, user, context);
  }

  // Ignorer le provisionnement personnalisé pour les utilisateurs AD.
  if (context.connection === AUTH0_AD_CONNECTION) {
    return callback(null, user, context);
  }

  // Si l'utilisateur est déjà provisionné dans Microsoft AD, nous ignorons
  // le reste de cette règle
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.office365Provisioned) {
    return connectWithUser();
  }

  // Variables globales utilisées dans les différentes étapes du
  // provisionnement d'un nouvel utilisateur.
  var token;
  var userPrincipalName;
  var mailNickname = user.email.split('@')[0];
  var uuid = uuidv4.v4();
  var immutableId = new Buffer(uuid).toString('base64');
  var userId;

  // Toutes les étapes effectuées pour provisionner de nouveaux utilisateurs Microsoft AD.
  // La définition de chaque fonction se trouve ci-dessous.
  getAzureADToken()
    .then(createAzureADUser)
    .then(getAvailableLicenses)
    .then(assignOffice365License)
    .then(saveUserMetadata)
    .then(waitCreateDelay)
    .then(connectWithUser)
    .catch(callback);

  // Demande un jeton d'accès pour interagir avec l'API Windows Graph.
  function getAzureADToken() {
    var options = {
      method: 'POST',
      url: 'https://login.windows.net/' + AAD_DOMAIN + '/oauth2/token?api-version=1.5',
      headers: {
        'Content-type': 'application/json',
        },
      json: true,
      form: {
        client_id: AAD_APPLICATION_ID,
        client_secret: AAD_APPLICATION_API_KEY,
        grant_type: 'client_credentials',
        resource: 'https://graph.windows.net'
      },
    };

    return rp(options);
  }

  // Récupère le jeton d'accès demandé ci-dessus et prépare une nouvelle requête
  // pour provisionner le nouvel utilisateur Microsoft AD.
  function createAzureADUser(response) {
    token = response.access_token;
    userPrincipalName = 'auth0-' + uuid + '@' + YOUR_COMPANY_DOMAIN;

    var options = {
      url: 'https://graph.windows.net/' + AAD_DOMAIN + '/users?api-version=1.6',
      headers: {
        'Content-type': 'application/json',
        'Authorization': 'Bearer ' + token
      },
      json: true,
      body: {
        accountEnabled: true,
        displayName: user.nickname,
        mailNickname: mailNickname,
        userPrincipalName: userPrincipalName,
        passwordProfile: {
          password: immutableId,
          forceChangePasswordNextLogin: false
        },
        immutableId: immutableId,
        usageLocation: AAD_USAGE_LOCATION
      },
    };

    return rp(options);
  }

  // Après avoir provisionné l'utilisateur, nous envoyons une requête pour obtenir la liste
  // des licences de produits Microsoft disponibles.
  function getAvailableLicenses(response) {
    userId = response.objectId;
    var options = {
      url: 'https://graph.windows.net/' + AAD_DOMAIN + '/subscribedSkus?api-version=1.6',
      json: true,
      headers: {
        'Content-type': 'application/json',
        'Authorization': 'Bearer ' + token
      }
    };
    return rp(options);
  }

  // À partir de la liste des licences, nous la parcourons pour obtenir l'identifiant (skuId) de la
  // licence à attribuer au nouvel utilisateur (Office 365 dans ce cas).
  // Nous envoyons également une nouvelle requête à l'API Graph pour associer l'utilisateur
  // à la licence.
  function assignOffice365License(response) {
    var office365License;

    for (var i = 0; i < response.value.length; i++) {
      if (response.value[i].skuPartNumber === OFFICE365_KEY) {
        office365License = response.value[i].skuId;
        break;
      }
    }

    var options = {
      url: ' https://graph.windows.net/' + AAD_DOMAIN + '/users/' + userId + '/assignLicense?api-version=1.6',
      headers: {
        'Content-type': 'application/json',
        'Authorization': 'Bearer ' + token
      },
      json: true,
      body: {
        'addLicenses': [
          {
            'disabledPlans': [],
            'skuId': office365License
          }
        ],
        'removeLicenses': []
      }
    };
    return rp(options);
  }

  // Après avoir provisionné l'utilisateur et lui avoir attribué une licence, nous enregistrons
  // (dans Auth0) que cet utilisateur Google Workspace a déjà été provisionné. Nous
  // enregistrons également le nom d'utilisateur principal et l'immutableId de l'utilisateur pour
  // le rediriger correctement lors des connexions futures.
  function saveUserMetadata() {
    user.app_metadata = user.app_metadata || {};

    user.app_metadata.office365Provisioned = true;
    user.app_metadata.office365UPN = userPrincipalName;
    user.app_metadata.office365ImmutableId = immutableId;

    return auth0.users.updateAppMetadata(user.user_id, user.app_metadata);
  }

  // Comme mentionné, l'API Windows Graph a besoin d'environ 10 secondes pour terminer
  // le provisionnement des nouveaux utilisateurs (même si elle retourne immédiatement un statut ok)
  function waitCreateDelay() {
    return new Promise(function (resolve) {
      setTimeout(function() {
        resolve();
      }, AAD_USER_CREATE_DELAY);
    });
  }

  // Ajoute le nom d'utilisateur principal et l'immutableId à l'objet `user` et termine
  // la règle.
  function connectWithUser() {
    user.upn = user.app_metadata.office365UPN;
    user.inmutableid = user.app_metadata.office365ImmutableId;
      return callback(null, user, context);
  }
}

Ce code illustre le processus de provisionnement d’un nouvel utilisateur, mais vous pouvez aussi l’adapter pour synchroniser les métadonnées d’utilisateurs existants.

​

Expérience utilisateur

Le moyen le plus simple pour vos utilisateurs externes de s’authentifier consiste à utiliser la connexion initiée par le fournisseur d’identité.

Vous devez rediriger vos utilisateurs vers l’URL suivante (p. ex. en utilisant un “smart link” comme https://office.travel0.com) :

Cela leur affichera la page de connexion Auth0, après quoi ils seront redirigés vers Office 365. Il est important d’expliquer aux utilisateurs externes qu’il s’agit de la seule façon pour eux de s’authentifier, puisque la page de connexion d’Office 365 ne prend pas en charge Home Realm Discover pour ces utilisateurs. Cela signifie aussi que, lorsqu’ils essaieront d’ouvrir un lien, ils devront d’abord passer par le smart link avant de pouvoir accéder au lien qu’ils ont tenté d’ouvrir.

Dans cet exemple, Travel0 a activé quelques comptes de réseaux sociaux et une connexion de base de données pour son application tierce Office 365 dans Auth0.

​

Liens profonds

Certaines mises en œuvre peuvent nécessiter des liens profonds (par exemple, vers SharePoint Online). Dans ce cas, il faut créer un smart link qui mène d’abord à la page de connexion d’Office 365 :

https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr={yourCustomDomain}&wreply={deepLink}

Le premier paramètre, {yourCustomDomain}, doit correspondre au domaine que vous avez configuré dans Azure AD pour l’authentification unique (SSO) (p. ex., travel0.com). En le spécifiant comme whr, Azure AD saura qu’il doit rediriger vers Auth0 au lieu d’afficher la page de connexion.

Le paramètre DEEP_LINK doit être une URL encodée dans Office 365 (par exemple, une page de SharePoint Online ou d’Exchange).

Exemple d’URL :

https://login.microsoftonline.com/login.srf?wa=wsignin1.0&whr=travel0.com&wreply=https%3A%2F%2Ftravel0%2Esharepoint%2Ecom