Procédure pas à pas : implémentation d'un fournisseur d'authentification unique enfichable

Par défaut, Microsoft Office SharePoint Server 2007 fournit le service d'authentification unique Microsoft Single Sign-On (SSO) pour le stockage et le mappage des informations d'identification à utiliser lors de la connexion à un système principal ou tiers. La plupart des entreprises ont déjà développé un système de stockage d'informations d'identification en interne ou utilisent une autre solution que le service d'authentification unique Microsoft Single Sign-On. Pour éviter de devoir conserver le mappage des informations d'identification à deux endroits, Office SharePoint Server 2007 offre un mécanisme appelé authentification unique enfichable, qui permet de spécifier un autre fournisseur d'authentification unique que celui d'Office SharePoint Server 2007.

Conditions préalables requises

Avant de créer le fournisseur d'authentification unique, vous devez configurer votre environnement. Cette procédure pas à pas suppose que vous avez configuré Office SharePoint Server 2007, installé une copie de la base de données AdventureWorks 2000 à partir du Centre de téléchargement Microsoft et vérifié que le nom de domaine correspond à LITWAREINC. Si vous utilisez un autre nom de domaine, vous devez modifier les exemples de code de cette procédure pas à pas.

Les groupes et comptes de domaine contenus dans le tableau ci-après sont supposés exister.

Pour obtenir des instructions complètes pour configurer la base de données et les comptes d'utilisateurs nécessaires, voir le fichier README.txt fourni avec la base de données AdventureWorks 2000.

Implémentation d'un fournisseur d'authentification unique

Remplacer le fournisseur d'authentification unique d'Office SharePoint Server 2007 implique l'implémentation de l'interface Microsoft.SharePoint.Portal.SingleSignon.ISsoProvider****, son installation dans le Global Assembly Cache et l'inscription du nouveau fournisseur d'authentification unique auprès d'Office SharePoint Server 2007.

Vous ne pouvez inscrire qu'un seul fournisseur d'authentification unique pour Office SharePoint Server 2007. L'inscription d'un nouveau fournisseur d'authentification unique entraîne le remplacement de la classe SpsSsoProvider par défaut dans Office SharePoint Server 2007. Étant donné qu'un seul fournisseur ne peut être utilisé à la fois, il est conseillé d'arrêter le service d'authentification unique Microsoft Single Sign-On lors de l'utilisation d'un fournisseur personnalisé.

Vous devez implémenter les méthodes GetCredentials et GetSsoProviderInfo de l'interface ISsoProvider pour créer un fournisseur d'authentification unique avec un niveau fonctionnel minimal. Cette procédure pas à pas montre comment créer un fournisseur d'authentification unique simple et l'utiliser pour accéder aux données via le catalogue de données métiers.

Dans cette procédure pas à pas, le fournisseur d'authentification unique mappe les utilisateurs du groupe InternalSales au compte d'utilisateur InternalAccess pour extraire les données des produits de la base de données AdventureWorks 2000.

Création du fournisseur

Cette section montre comment créer et installer un fournisseur d'authentification unique simple. Elle décrit également la gestion des exceptions du fournisseur.

Téléchargements    Pour télécharger l'exemple de fournisseur, voir Kit de développement logiciel (SDK) de SharePoint Server 2007 Server .

Exemple

Vous devez créer un assembly de fournisseur d'authentification unique dans Microsoft Visual Studio 2005 en créant un projet Bibliothèque de classes. Vous devez ensuite ajouter dans cotre projet une référence au fichier Microsoft.SharePoint.Portal.SingleSignon.dll (situé dans le répertoire %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\12\ISAPI). Vous devez enfin implémenter l'interface ISsoProvider, comme illustré dans le code ci-après.

using System;
using System.Collections.Generic;
using System.Reflection;
using System.Text;
using System.Web;
using System.Web.Services;
using Microsoft.SharePoint.Portal.SingleSignon;

namespace SampleSSOProvider
{
    /// <summary>
    /// SimpleSSOProvider
    /// </summary>
    public class SimpleSSOProvider: ISsoProvider
    {
        public Application.ApplicationInfo[] GetApplicationDefinitions()
        {
            //NOTE: Used by SpsSsoProvider, not necessary for SimpleSSOProvider
            throw new NotSupportedException();
        }
        public Application.ApplicationField[] GetApplicationFields(string AppID)
        {
            //NOTE: Used by SpsSsoProvider, not necessary for SimpleSSOProvider
            throw new NotSupportedException();
        }

public Application.ApplicationInfo GetApplicationInfo(string AppID)
        {
            Application.ApplicationInfo applicationInfo = new Application.ApplicationInfo("SimpleSSOProvider", "SimpleSSOProvider", Application.ApplicationType.GroupWindows, "sso@litwareinc.com");

            Application.ApplicationInfo applicationInfo = new Application.ApplicationInfo("SimpleSSOProvider","SimpleSSOProvider",Application.ApplicationType.GroupWindows,"sso@litwareinc.com", (SsoCredentialContents)((Int32)SsoCredentialContents.UserName + (Int32)SsoCredentialContents.Password + (Int32)SsoCredentialContents.WindowsCredentials));
            */

            return applicationInfo;
        }
        public Uri GetCredentialManagementURL(string AppID)
        {
            //NOTE: Used by SpsSsoProvider, not necessary for SimpleSSOProvider
            throw new NotSupportedException();
        }
        public SsoCredentials GetCredentials(string AppID)
        {
            //Note: Used by SpsSsoProvider, necessary for any SimpleSSO Provider. Implementation discussed in detail in the next section of this topic
        }
        public SsoCredentials GetCredentialsUsingTicket(string Ticket, string AppID)
        {
            //NOTE: Used by SpsSsoProvider, necessary for Simple SSO Provider when used by Excel Services.
            //TODO: Implement Ticket management code; currently just return SsoCredentials
            return GetCredentials(AppID);
        }
        public string GetCurrentUser()
        {
            //NOTE: Used by SpsSsoProvider, not necessary for SimpleSSOProvider
            throw new NotSupportedException();
        }

public SsoCredentials GetSensitiveCredentials(string AppID)
{
    //NOTE: Used by SpsSsoProvider, necessary for Simple SSOProvider when used by Excel Services

    //TODO: Implement Sensitive Credential method, for sample just returning basic credentials
    return GetCredentials(AppID);
}
        public SsoProviderInfo GetSsoProviderInfo()
        {
            //TODO: Used by SpsSsoProvider, necessary for any SimpleSSOProvider
        }
        public string GetTicket()
        {
            //NOTE: Used by SpsSsoProvider, necessary for SimpleSSOProvider when used by Excel Services
            //TODO: Implement Ticket management code; currently just return a string
            return "No Ticket Management";
        }
        public void PutIdentityOnRequest(ref System.Web.Services.Protocols.HttpWebClientProtocol request, string AppID)
        {
            //NOTE: Used by SpsSsoProvider, not necessary for SimpleSSOProvider
            throw new NotSupportedException();
        }
        public void PutIdentityOnRequestUsingTicket(ref System.Web.Services.Protocols.HttpWebClientProtocol request, string Ticket, string AppID)
        {
            //NOTE: Used by SpsSsoProvider, not necessary for SimpleSSOProvider
            throw new NotSupportedException();
        }
    }
}

Vous devez au moins implémenter les méthodes GetCredentials et GetSsoProviderInfo. La SimpleSSOProvider classe que nous avons créée retourne les nouvelles informations d'identification selon l'utilisateur actuel et l'identificateur d'application (AppID) spécifiés. Nous pouvons obtenir des informations sur l'utilisateur actuel à l'aide de la propriété CurrentPrincipal property du thread d'exécution (System.Threading.Thread.CurrentPrincipal). Le code ci-après illustre l'implémentation de la méthode GetCredentials.

public SsoCredentials GetCredentials(string AppID)
{
    //NOTE: Used by SpsSsoProvider, necessary for any SimpleSSOProvider
    System.Diagnostics.Trace.WriteLine("Entering SimpleSSOProvider::GetCredentials");
    System.Diagnostics.Trace.Indent();
    // Retrieve the logged in user's information
    string domain = System.Environment.UserDomainName;
    System.Diagnostics.Trace.WriteLine("User domain is " + domain);
    
    try {
        System.Diagnostics.Trace.WriteLine("Context user:" + System.Threading.Thread.CurrentPrincipal.Identity.Name);
        // Start building an SsoCredentials object to store two values - UserName and Password
        SsoCredentials creds = new SsoCredentials();
        creds.Evidence = new System.Security.SecureString[2];

        switch (AppID){
            case "AdventureWorks":
                System.Diagnostics.Trace.WriteLine("Application is AdventureWorks");

                if (System.Threading.Thread.CurrentPrincipal.IsInRole("InternalSales"))
                {
                    System.Diagnostics.Trace.WriteLine("User is in InternalSales? " + System.Threading.Thread.CurrentPrincipal.IsInRole("InternalSales"));
                    // Provide components for the InternalAccess account token
                    creds.Evidence[0] = MakeSecureString(domain + "\\InternalAccess");
                    creds.Evidence[1] = MakeSecureString("pass@word1");
                }
                else
                {
                    // Provide components for the ExternalAccess account token
                    creds.Evidence[0] = MakeSecureString(domain + "\\ExternalAccess");
                    creds.Evidence[1] = MakeSecureString("pass@word1");
                }
                break;

            default:
                throw new SingleSignonException(SSOReturnCodes.SSO_E_APPLICATION_NOT_FOUND);
        }

        // Put the UserName/Password values into the credential object
        creds.UserName = creds.Evidence[0];
        creds.Password = creds.Evidence[1];

        System.Diagnostics.Trace.Unindent();
        return creds;
    }
    catch(SingleSignonException ex) {
        System.Diagnostics.EventLog.WriteEntry("SimpleSSOProvider", "Caught SSO Exception: " + ex.ToString());
        throw;
    }
    catch(Exception ex) {
        System.Diagnostics.EventLog.WriteEntry("SimpleSSOProvider", "Caught Exception: " + ex.ToString());
        throw new SingleSignonException(SSOReturnCodes.SSO_E_EXCEPTION, ex);
    }
}

Bien que l'implémentation de SsoProvider ne requière pas SsoCredentialsContents, certaines autres applications clientes peuvent attendre cette valeur. Dans l'exemple fourni, Services Excel tentera de se connecter aux ressources à l'aide d'une connexion Windows utilisant les UserName et Password spécifiés. Si aucune valeur n'est spécifiée pour WindowsCredentials, les UserName et Password doivent être définis sur la chaîne de connexion.

La méthode GetSsoProviderInfo retourne juste des informations sur le fournisseur, telles que le nom de l'éditeur (vendor) et la version, comme illustré dans le code ci-après.

        public SsoProviderInfo GetSsoProviderInfo()
        {
            //NOTE: Used by SpsSsoProvider, necessary for any SimpleSSOProvider
            SsoProviderInfo ssoProvInfo = new SsoProviderInfo();

            ssoProvInfo.AssemblyName = Assembly.GetExecutingAssembly().FullName;
            ssoProvInfo.Vendor = "AdventureWorks";
            ssoProvInfo.Version = "1.0";            

            return ssoProvInfo;
        }

Si le fournisseur d'authentification unique sera utilisé par Services Excel, vous devez également fournir une implémentation des méthodes GetCredentialsUsingTicket et GetTicket.

La classe SimpleSsoProvider que nous avons créée illustre un exemple très simple de fournisseur d'authentification unique. Dans la réalité, une implémentation doit récupérer les informations d'identification à partir d'un référentiel sécurisé et protéger les valeurs lors de leur mise en mémoire.

L'objet SsoCredentials, retourné par GetCredentials, utilise la classe SecureString pour stocker les propriétés UserName et Password, ainsi que les valeurs Evidence. SecureString chiffre ses données de sorte qu'elles ne puissent pas être déchiffrées facilement.

Gestion des exceptions

Le fournisseur SimpleSSOProvider génère une instance de SingleSignonException et utilise les champs SSOReturnCodes standard s'il ne parvient pas à déterminer correctement l'AppID. Le tableau ci-après contient quelques champs SSOReturnCodes courants pour plusieurs cas d'erreur.

Inscription du fournisseur

Pour installer le fournisseur SimpleSSOProvider, vous devez l'inscrire dans le Global Assembly Cache, puis l'inscrire à l'aide de l'application console ProviderAdmin (située dans le répertoire bin de l'installation Office SharePoint Server 2007). L'application ProviderAdmin remplace le fournisseur d'authentification unique actuel par celui spécifié. Dans un environnement de batterie de serveurs, vous devez inscrire le nouveau fournisseur d'authentification unique auprès de chaque ordinateur de la batterie. Les procédures ci-après montrent comment inscrire le fournisseur, le supprimer et rétablir le fournisseur d'origine.

Pour inscrire le fournisseur SimpleSSOProvider

• L'outil ProviderAdmin utilise le nom d'assembly complet de la classe qui implémente l'interface ISsoProvider. Pour inscrire le fournisseur SimpleSSOProvider dans notre exemple, l'outil ProviderAdmin exécute la commande ci-après.

  Microsoft.SharePoint.Portal.SingleSignon.ProviderAdmin.exe 
  "SampleSSOProvider, Version=1.0.0.0, Culture=neutral, 
  PublicKeyToken=e447e624e7099fd1" 
  "SampleSSOProvider.SimpleSSOProvider"
  

Pour supprimer un fournisseur d'authentification unique personnalisé et rétablir le fournisseur d'origine

• Pour supprimer un fournisseur d'authentification unique personnalisé et rétablir le fournisseur d'origine dans Office SharePoint Server 2007, annulez l'inscription du fournisseur d'authentification unique à l'aide de la commande ci-après.

  Microsoft.SharePoint.Portal.SingleSignon.ProviderAdmin.exe /u
  

Accès au fournisseur d'authentification unique

Les composants WebPart ou les autres types de composants ayant besoin d'accéder à un fournisseur d'authentification unique ne doivent plus utiliser l'objet Credentials. L'utilisation de l'objet Credentials ne permet que la récupération du fournisseur d'authentification unique par défaut d'Office SharePoint Server 2007, et ce même si un nouveau fournisseur a été inscrit à l'aide de l'outil ProviderAdmin. Pour obtenir une référence au ISsoProvider actuellement inscrit, effectuez la procédure ci-après.

Pour obtenir une référence au fournisseur d'authentification unique actuellement inscrit

• Utilisez la méthode GetSsoProvider de la classe SsoProviderFactory pour obtenir une référence au ISsoProvider actuellement inscrit. Le code peut avoir recours à la méthode GetCredentials de l'interface ISsoProvider pour obtenir les informations d'identification de l'application, comme illustré ci-après.

  ISSOProvider issop;
  issop = SsoProviderFactory.GetSsoProvider();
  SsoCredentials ssocred = issop.GetCredentials("AdventureWorks");
  

La classe SsoCredentials fournit un accès aux informations d'identification au moyen de la classe SecureString. Vous pouvez utiliser plusieurs méthodes différentes pour convertir une instance SecureString en format utilisable, telle que la méthode SecureStringToBSTR, comme illustré dans l'exemple ci-après.

ISsoProvider provider = SsoProviderFactory.GetSsoProvider();
SsoCredentials creds = provider.GetCredentials("AdventureWorks");
IntPtr pUserName = IntPtr.Zero;
try
{
pUserName = System.Runtime.InteropServices.Marshal.SecureStringToBSTR(creds.UserName);
//NOTE: After this has been converted to a String object, it remains in 
//memory until the garbage collector collects it.
String userName = System.Runtime.InteropServices.Marshal.PtrToStringBSTR(pUserName);
}
finally
{
// Free zero out and free the BSTR pointers.
if (IntPtr.Zero != pUserName)
{
System.Runtime.InteropServices.Marshal.ZeroFreeBSTR(pUserName);
}
}

Utilisation du fournisseur d'authentification unique à partir du catalogue de données métiers

Outre l'accès au fournisseur d'authentification unique par défaut par le biais des composants WebPart, vous pouvez également utiliser le fournisseur d'authentification unique personnalisé à partir des applications inscrites dans le catalogue de données métiers.

Pour utiliser le fournisseur d'authentification unique avec le catalogue de données métiers

• Pour utiliser le fournisseur d'authentification unique personnalisé avec un système métier de base de données, modifiez le schéma du catalogue de données en ajoutant les propriétés SsoApplicationId et SsoProviderImplementation à la balise XML LOBSystemInstance, comme illustré ci-après.

  <LobSystemInstance Name="AdventureWorks2000(SampleSSO)">
  <Properties>
  <Property Name="AuthenticationMode" Type="System.String">WindowsCredentials</Property>
  <Property Name="SsoApplicationId" Type="System.String">AdventureWorks</Property>
  <Property Name="SsoProviderImplementation" Type="System.String">SampleSSOProvider.SimpleSSOProvider, SampleSSOProvider, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e447e624e7099fd1</Property>
  
  <!—Database connection properties elided -->
  </Properties>
  </LobSystemInstance>
  

Étant donné que notre fournisseur retourne des informations d'identification Windows, la propriété AuthenticationMode est définie sur WindowsCredentials. Lorsque le catalogue de données métiers récupère les informations d'identification du fournisseur d'authentification unique, il exécute un appel LogonUser() pour configurer l'emprunt d'identité avant de tenter d'accéder à la base de données.

Dans notre exemple, un utilisateur est mappé au compte InternalAccess ou ExternalAccess pour extraire des données de produits d'une base de données AdventureWorks 2000.

Pour plus d'informations sur le schéma du catalogue de données métiers, notamment sur la configuration nécessaire pour implémenter l'authentification unique pour des systèmes métier de service Web, voir LobSystemInstance dans la rubrique Catalogue de données métiers : modèle de métadonnées.

Étapes suivantes

La possibilité de remplacer le fournisseur d'authentification unique par défaut d'Office SharePoint Server 2007 vous permet de mieux intégrer vos sites SharePoint dans les investissements déjà réalisés dans votre entreprise. Vous pouvez avoir recours aux banques d'informations d'identification préexistantes développées en interne ou fournies dans une solution tierce. Des composants WebPart ou des objets de catalogue de données métiers peuvent alors accéder à votre fournisseur personnalisé pour en tirer pleinement parti.