Créer une page de proxy personnalisée pour la bibliothèque inter-domaines dans SharePoint

Article
04/08/2023

Lorsque vous créez des Compléments SharePoint, vous devez généralement incorporer des données en provenance de différentes sources. Pour des raisons de sécurité, il existe toutefois des mécanismes de blocage qui empêchent toute communication avec plusieurs domaines à la fois.

Vous pouvez utiliser la bibliothèque inter-domaines pour accéder aux données du complément distant si vous fournissez une page de proxy personnalisé qui est hébergée dans l’infrastructure du complément distant. En tant que développeur, vous êtes chargé d’implémenter la page de proxy personnalisé et de gérer une logique personnalisée (mécanisme d’authentification auprès du complément distant, par exemple). Utilisez la bibliothèque inter-domaines avec une page de proxy personnalisé si vous voulez que la communication ait lieu au niveau du client.

Conditions préalables à l’utilisation des exemples de cet article

Vous devez disposer d’un environnement de développement semblable à celui décrit dans l’article Commencer à créer des compléments hébergés par un fournisseur pour SharePoint.

Principaux concepts à connaître avant d’utiliser une page de proxy personnalisée avec des compléments SharePoint

Le tableau suivant contient des articles très utiles pour vous aider à comprendre les concepts impliqués dans un scénario multidomaines dans des compléments SharePoint.

Titre d’article	Description
Compléments	Découvrez le nouveau modèle de complément dans SharePoint qui vous permet de créer des compléments, c’est-à-dire de petites solutions simples d’utilisation pour les utilisateurs finaux.
Accès aux données sécurisé et modèles d’objet client pour les compléments SharePoint	Découvrez les options d'accès aux données des Compléments SharePoint. Cette rubrique contient des informations sur les principales options parmi lesquelles vous devez effectuer un choix lors de l'utilisation de données dans votre complément.
Héberger des sites web, des sites web de complément et des composants SharePoint dans SharePoint	Découvrez la différence entre les sites web hôtes et les sites web de complément. Découvrez les composants SharePoint pouvant être inclus dans un Complément SharePoint, les composants déployés sur le site web hôte, les composants déployés sur le site web de complément et la façon dont le site web de complément est déployé dans un domaine isolé.
Sécurité inter-domaines côté client	Découvrez les cas d'utilisation et les menaces inter-domaines, ainsi que les principes de sécurité qui s'appliquent aux demandes inter-domaines. Évaluez les risques que peut entraîner l'amélioration de l'accès inter-domaines à partir des applications web qui s'exécutent dans un navigateur.

Exemple de code : accès à des données distantes à l’aide d’une page de proxy personnalisé pour la bibliothèque inter-domaines

Pour lire les données à partir du service à distance, vous devez procéder comme suit :

Créez un projet de Complément SharePoint.
Modifiez le manifeste du complément pour autoriser une communication à partir du complément distant.
Créez une page de proxy personnalisé et une page de contenu dans le projet web.
Créez une page qui utilise la bibliothèque inter-domaines dans le projet de Complément SharePoint.

Création d’un projet de complément SharePoint

Ouvrez Visual Studio en tant qu’administrateur. (Pour cela, cliquez avec le bouton droit de la souris sur l’icône Visual Studio dans le menu Démarrer, puis sélectionnez Exécuter en tant qu’administrateur.)
Créez le complément SharePoint hébergé par un fournisseur, comme indiqué dans l’article Commencer à créer des compléments hébergés par un fournisseur pour SharePoint, et nommez-le ProxyPageApp.

Pour modifier le fichier manifeste du complément

Dans l’Explorateur de solutions, cliquez avec le bouton droit de la souris sur le fichier AppManifest.xml, puis sélectionnez Afficher le code.

Remplacez tout l'élément AppPrincipal par ce qui suit.

<AppPrincipal>
    <Internal AllowedRemoteHostUrl="~remoteAppUrl"/>
</AppPrincipal>

Remarque

L’attribut AllowedRemoteHostUrl sert à spécifier le domaine distant. Le jeton ~remoteAppUrl est résolu en URL de complément distant. Pour en savoir plus sur les jetons, consultez l’article Explorer la structure du manifeste de l’application et le package d’un complément SharePoint.

Pour créer une page proxy personnalisée

Une fois la solution Visual Studio créée, cliquez avec le bouton droit de la souris sur le projet d’application web (et non le projet de complément SharePoint), puis ajoutez un nouveau formulaire web en sélectionnant Ajouter>Nouvel élément>Web>Formulaire web. Nommez le formulaire Proxy.aspx.

Dans le fichier Proxy.aspx, remplacez l’ensemble de l’élément HTML et ses enfants par le code HTML suivant. Ne modifiez pas les balises situées au-dessus de l’élément HTML. Le code HTML contient des balises et un JavaScript qui effectue les tâches suivantes :

Fournit un espace réservé pour le fichier JavaScript de bibliothèque inter-domaines.
Extrait l'URL du site web du complément du référent.
Charge dynamiquement le fichier JavaScript de la bibliothèque inter-domaines dans l’espace réservé.
Fournit les paramètres pour l'objet RequestExecutorMessageProcessor.
Initialise l'objet RequestExecutorMessageProcessor.

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <meta http-equiv="X-UA-Compatible" content="IE=8" /> 
    <title>Custom Proxy Host Page</title>
    <script 
        src="http://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js" 
        type="text/javascript">
    </script>
    <script 
        type="text/javascript" 
        src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
    </script>

    <!-- Script to load the cross-domain library js file -->
    <script type="text/javascript">
        var hostweburl;

        $(document).ready(function(){
            //Get the URI decoded host web URL.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );

            // The cross-domain js file is in a URL in the form:
            // host_web_url/_layouts/15/SP.RequestExecutor.js
            var scriptbase = hostweburl + "/_layouts/15/";

            // Load the js file 
            $.getScript(scriptbase + "SP.RequestExecutor.js", initCustomProxy);
        });

        //Function to initialize the custom proxy page
        //  must set the appropriate settings and implement
        //  proper authentication mechanism
        function initCustomProxy() {
            var settings =
            {
                originAuthorityValidator: function (messageOriginAuthority) {
                    // This page must implement the authentication for the
                    //   remote add-in.
                    // You should validate if messageOriginAuthority is
                    //  an approved domain to receive calls from.
                    return true;
                }
            };
            SP.RequestExecutorMessageProcessor.init(settings);
        }

        // Function to retrieve a query string value.
        // For production purposes you may want to use
        //  a library to handle the query string.
        function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&amp;");
            var strParams = "";
            for (var i = 0; i < params.length; i = i + 1) {
                var singleParam = params[i].split("=");
                if (singleParam[0] == paramToRetrieve)
                    return singleParam[1];
            }
        }
    </script>
</head>
<body>

</body>
</html>

Importante

Dans un complément SharePoint de production, vous devez fournir la logique d’autorisation et renvoyer la valeur correspondante dans l’objet originAuthorityValidator des paramètres.

Pour créer un type de page

Cliquez avec le bouton droit sur le projet d’application web dans Explorateur de solutions, puis ajoutez un nouveau formulaire web en sélectionnant Ajouter un> nouveauformulaire web>d’élément>. Nommez le formulaire Content.aspx.
Copiez le code suivant et collez-le dans la méthode Page_Load du fichier code-behind. Le code effectue les tâches suivantes :
- Définit le content-type de sortie sur text/plain.
- Écrit le contenu dans la mémoire tampon de sortie.
- Met fin à la connexion.
```
string content;
content = "Just some text.";
Response.ContentType="text/plain";
Response.Write(content);
Response.End();
```

Pour créer une page web SharePoint qui utilise la bibliothèque inter-domaines

Cliquez avec le bouton droit de la souris sur le projet de complément SharePoint, puis sélectionnez Ajouter>Nouvel élément>Office/SharePoint>Module.
Nommez le module Pages, puis sélectionnez Ajouter.
Cliquez avec le bouton droit de la souris sur le dossier Pages, puis sélectionnez Ajouter>Nouvel élément>Office/SharePoint>Page.
Nommez la page Home.aspx, puis sélectionnez Ajouter.
Ouvrez la page Home.aspx si elle ne s’ouvre pas automatiquement.

Copiez le code ci-dessous et collez-le dans la balise de contenu PlaceHolderMain.

<!-- The page dynamically loads the cross-domain library's
    js file, rescript acts as the placeholder. -->
<script 
    type="text/javascript"
    id="rescript"
    src="../_layouts/15/SP.RequestExecutor.js">
</script>
    Data from the remote domain: <span id="TextData"></span>

    <!-- Main script to retrieve the host web's title -->
    <script type="text/javascript">
    (function () {
        var executor;
        var hostweburl;
        var remotedomain;

        remotedomain = "<your_remote_add-in_domain>";

        //Get the URI decoded host web URL.
        hostweburl =
            decodeURIComponent(
                getQueryStringParameter("SPHostUrl")
        );

        // Initialize the RequestExecutor with the custom proxy URL.
        executor = new SP.RequestExecutor(remotedomain);
        executor.iFrameSourceUrl = "Proxy.aspx?SPHostUrl=" + hostweburl;

        // Issue the call against the remote endpoint.
        // The response formats the data in plain text.
        // The functions successHandler and errorHandler attend the
        //      sucess and error events respectively.
        executor.executeAsync(
            {
                url:
                    remotedomain + "Content.aspx",
                method: "GET",
                headers: { "Accept": "text/plain" },
                success: successHandler,
                error: errorHandler
            }
        );
    })();

    // Function to handle the success event.
    // Prints the data to the placeholder.
    function successHandler(data) {
        document.getElementById("TextData").innerText =
            data.body;
    }

    // Function to handle the error event.
    // Prints the error message to the page.
    function errorHandler(data, errorCode, errorMessage) {
        document.getElementById("TextData").innerText =
            "Could not complete cross-domain call: " + errorMessage;
    }

    // Function to retrieve a query string value.
    // For production purposes you may want to use
    //  a library to handle the query string.
    function getQueryStringParameter(paramToRetrieve) {
        var params =
            document.URL.split("?")[1].split("&amp;");
        var strParams = "";
        for (var i = 0; i < params.length; i = i + 1) {
            var singleParam = params[i].split("=");
            if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
        }
    }
    </script>

Dans le code précédent que vous avez collé, recherchez la ligne remotedomain = "<your_remote_add-in_domain>";et remplacez l’espace réservé <your_remote_add-in_domain> par l’URL « localhost » que votre application web utilise lorsque vous exécutez le complément avec F5 dans Visual Studio. Pour trouver cette valeur, sélectionnez le projet d’application web dans l’Explorateur de solutions. La propriété URL se trouve dans le volet Propriétés . Utilisez la valeur entière, y compris le protocole, le port et la barre oblique fermante ; par exemple http://localhost:45072.
Enregistrez et fermez le fichier.
Ouvrez le fichier appmanifest.xml et définissez la valeur de Page de démarrage sur ProxyPageApp/Pages/Home.aspx.

Pour créer et exécuter la solution

Vérifiez que le projet de Complément SharePoint est défini en tant que projet de démarrage.
Sélectionnez la touche F5.

Remarque

Lorsque vous sélectionnez F5, Visual Studio génère la solution, déploie le complément et ouvre la page des autorisations pour le complément.
Sélectionnez le bouton Approuver.

La page d’accueil s’ouvre et doit ressembler à ce qui suit. La phrase « Just some text » peut mettre quelques secondes avant de s’afficher, car elle est extraite de la page Content.aspx du domaine distant.

Dépannage de la solution

Problème	Solution
Visual Studio n’ouvre pas le navigateur lorsque vous sélectionnez la touche F5.	Définissez le projet de Complément SharePoint en tant que projet de démarrage.
Exception non gérée SP n'est pas défini.	Assurez-vous que vous pouvez accéder au fichier SP.RequestExecutor.js dans une fenêtre du navigateur.