Procedura: creare un token personalizzato

Questo argomento illustra come creare un token di protezione personalizzato utilizzando la classe SecurityToken e come integrarlo in un provider e un autenticatore di token di protezione personalizzati.

Un token di protezione è essenzialmente un elemento XML utilizzato dal framework di protezione di Windows Communication Foundation (WCF) per rappresentare le attestazioni relative a un mittente contenuto nel messaggio SOAP. Il framework di protezione di WCF fornisce vari tipi di token per le modalità di autenticazione fornite dal sistema. Alcuni esempi sono il token di protezione basato su certificato X.509 rappresentato dalla classe X509SecurityToken o il token di protezione del nome utente rappresentato dalla classe UserNameSecurityToken.

Talvolta una determinata modalità di autenticazione o credenziale non è supportata dai tipi di token disponibili. In tal caso è necessario creare un token di protezione personalizzato per fornire una rappresentazione XML della credenziale personalizzata nel messaggio SOAP.

Le procedure seguenti illustrano come creare un token di protezione personalizzato e come integrarlo nell'infrastruttura di protezione di WCF. In particolare, questo argomento illustra la creazione di un token di carta di credito utilizzato per passare al server le informazioni della carta di credito del client.

Per ulteriori informazioni sulle credenziali personalizzate e sul gestore del token di protezione, vedere Procedura: creare credenziali client e del servizio personalizzate.

Per un elenco di altre classi utilizzate per rappresentare token di protezione, vedere lo spazio dei nomi System.IdentityModel.Tokens.

Per ulteriori informazioni sulle credenziali, sul gestore del token di protezione e sulle classi di provider e autenticatore, vedere Architettura della protezione.

Procedure

È necessario fornire a un'applicazione client un modo per specificare le informazioni sulla carta di credito per l'infrastruttura di protezione. Per consentire all'applicazione di specificare queste informazioni viene utilizzata una classe di credenziali client personalizzata. Il primo passaggio consiste nel creare una classe che rappresenta le informazioni di carta di credito come credenziali client personalizzate.

Per creare una classe che rappresenta informazioni di carta di credito come credenziali client

1. Definire una nuova classe che rappresenta le informazioni di carta di credito dell'applicazione. Nell'esempio seguente tale classe viene denominata CreditCardInfo.

2. Aggiungere alla classe le proprietà appropriate per consentire a un'applicazione di impostare le informazioni necessarie per il token personalizzato. In questo esempio la classe presenta tre proprietà: CardNumber, CardIssuer e ExpirationDate.

È quindi necessario creare una classe che rappresenti il token di protezione personalizzato. Questa classe viene utilizzata dalle classi del serializzatore, dell'autenticatore e del provider del token di protezione per scambiare informazioni sul token di protezione con l'infrastruttura di protezione WCF.

Per creare una classe di token di protezione personalizzato

1. Definire una nuova classe derivata dalla classe SecurityToken. In questo esempio viene creata una classe denominata CreditCardToken.

2. Eseguire l'override della proprietà Id. Questa proprietà viene utilizzata per ottenere l'identificatore locale del token di protezione utilizzato dagli altri elementi contenuti nel messaggio SOAP per puntare alla rappresentazione XML del token di protezione. In questo esempio è possibile passare ad esso un identificatore del token come un parametro di costruttore oppure generarne uno casuale ogni volta che viene creata un'istanza del token di protezione.

3. Implementare la proprietà SecurityKeys. Questa proprietà restituisce un insieme di chiavi di protezione rappresentate dall'istanza del token di protezione. Tali chiavi possono essere utilizzate da WCF per firmare o crittografare parti del messaggio SOAP. In questo esempio, il token di protezione della carta di credito non può contenere chiavi di protezione. Pertanto, l'implementazione restituisce sempre un insieme vuoto.

4. Eseguire l'override delle proprietà ValidFrom e ValidTo. Queste proprietà vengono utilizzate da WCF per determinare la validità dell'istanza del token di protezione. In questo esempio, il token di protezione della carta di credito presenta solo una data di scadenza ("ValidTo"), pertanto la proprietà ValidFrom restituisce un oggetto DateTime che rappresenta la data e l'ora di creazione dell'istanza.

Quando si crea un nuovo tipo di token di protezione è necessario implementare per tale tipo la classe SecurityTokenParameters. Questa implementazione viene utilizzata nella configurazione dell'elemento di associazione di protezione per rappresentare il nuovo tipo di token. La classe dei parametri del token di protezione rappresenta il modello rispetto a cui confrontare l'istanza effettiva del token di protezione quando viene elaborato un messaggio. Nel modello vengono fornite proprietà aggiuntive che un'applicazione può utilizzare per specificare i criteri che il token di protezione deve soddisfare per essere utilizzato o autenticato. Nell'esempio seguente non vengono aggiunte altre proprietà, di conseguenza la corrispondenza viene creata solo con il tipo di token di protezione quando l'infrastruttura WCF cerca un'istanza del token di protezione da utilizzare o convalidare.

Per creare una classe di parametri del token di protezione personalizzato

1. Definire una nuova classe derivata dalla classe SecurityTokenParameters.

2. Implementare il metodo CloneCore. Copiare tutti i campi interni definiti nella classe, se presenti. In questo esempio non viene definito alcun campo aggiuntivo.

3. Implementare la proprietà di sola lettura SupportsClientAuthentication. Questa proprietà restituisce true se il tipo di token di protezione rappresentato da questa classe può essere utilizzato per autenticare un client presso un servizio. In questo esempio, il token di protezione della carta di credito può essere utilizzato a tale scopo.

4. Implementare la proprietà di sola lettura SupportsServerAuthentication. Questa proprietà restituisce true se il tipo di token di protezione rappresentato da questa classe può essere utilizzato per autenticare un servizio presso un client. In questo esempio, il token di protezione della carta di credito non può essere utilizzato a tale scopo.

5. Implementare la proprietà di sola lettura SupportsClientWindowsIdentity. Questa proprietà restituisce true se il tipo di token di protezione rappresentato da questa classe può essere associato a un account Windows. In questo caso, il risultato dell'autenticazione è rappresentato da un'istanza della classe WindowsIdentity. In questo esempio, il token non può essere associato a un account Windows.

6. Implementare il metodo CreateKeyIdentifierClause. Questo metodo viene chiamato dal framework di protezione di WCF quando quest'ultimo richiede un riferimento all'istanza del token di protezione rappresentato da questa classe di parametri del token di protezione. Sia l'istanza del token di protezione effettivo sia lo stile SecurityTokenReferenceStyle che specifica il tipo del riferimento richiesto vengono passati a questo metodo come argomenti. In questo esempio, il token di protezione della carta di credito supporta soltanto riferimenti interni. Poiché la classe SecurityToken offre funzionalità in grado di creare riferimenti interni, l'implementazione non richiede codice aggiuntivo.

7. Implementare il metodo InitializeSecurityTokenRequirement. Questo metodo viene chiamato da WCF per convertire l'istanza della classe di parametri del token di protezione in un'istanza della classe SecurityTokenRequirement. Il risultato della conversione viene utilizzato dai provider di token di protezione per creare l'istanza appropriata del token di protezione.

I token di protezione vengono trasmessi all'interno di messaggi SOAP. Ciò richiede un meccanismo di conversione fra la rappresentazione dei token di protezione in memoria e la rappresentazione dei token di protezione trasmessi. A tale scopo, WCF utilizza un serializzatore di token di protezione. A ogni token personalizzato è necessario associare un serializzatore di token di protezione personalizzato in grado di serializzare il token di protezione personalizzato nel messaggio SOAP nonché di eseguire l'operazione inversa.

Per creare un serializzatore di token di protezione personalizzato

1. Definire una nuova classe derivata dalla classe WSSecurityTokenSerializer.

2. Eseguire l'override del metodo CanReadTokenCore che si basa su un oggetto XmlReader per leggere il flusso XML. Il metodo restituisce true se l'implementazione del serializzatore può deserializzare il token di protezione in base all'elemento corrente del lettore. In questo esempio, il metodo verifica se il nome e lo spazio dei nomi dell'elemento XML corrente del lettore XML sono corretti. In caso contrario, viene chiamata l'implementazione della classe base di questo metodo per la gestione dell'elemento XML.

3. Eseguire l'override del metodo ReadTokenCore. Tramite questo metodo viene letto il contenuto XML del token di protezione e viene creata la rappresentazione in memoria appropriata di tale token. Se non riconosce l'elemento XML correntemente esaminato dal lettore XML specificato, tale metodo chiama l'implementazione della classe di base per elaborare i tipi di token forniti dal sistema.

4. Eseguire l'override del metodo CanWriteTokenCore. Questo metodo restituisce true se può convertire la rappresentazione in memoria del token (passata come argomento) nella rappresentazione XML. In caso contrario, tale metodo chiama l'implementazione della classe di base.

5. Eseguire l'override del metodo WriteTokenCore. Questo metodo converte una rappresentazione in memoria del token di protezione in una rappresentazione XML. Qualora questa conversione risultasse impossibile, tale metodo chiama l'implementazione della classe di base.

Dopo aver completato le quattro procedure precedenti, integrare il token di protezione personalizzato nel provider, nell'autenticatore e nel gestore di token di protezione nonché nelle credenziali client e server.

Per integrare il token di protezione personalizzato in un provider di token di protezione

1. Il provider del token di protezione crea, modifica (se necessario) e restituisce un'istanza del token. Per creare un provider personalizzato per il token di protezione personalizzato, creare una classe che eredita dalla classe SecurityTokenProvider. Nell'esempio seguente viene eseguito l'override del metodoGetTokenCore per restituire un'istanza del token CreditCardToken. Per ulteriori informazioni sui provider di token di protezione personalizzati, vedere Procedura: creare un provider di token di protezione personalizzati.

Per integrare il token di protezione personalizzato in un autenticatore del token di protezione

1. L'autenticatore del token di protezione convalida il contenuto del token di protezione quando quest'ultimo viene estratto dal messaggio. Per creare un autenticatore personalizzato per il token di protezione personalizzato, creare una classe che eredita dalla classe SecurityTokenAuthenticator. Nell'esempio seguente viene eseguito l'override del metodo ValidateTokenCore. Per ulteriori informazioni sugli autenticatori dei token di protezione personalizzati, vedere Procedura: creare un autenticatore del token di protezione personalizzato.

Per integrare il token di protezione personalizzato in un gestore del token di protezione

1. Il gestore del token di protezione crea le istanze del provider di token, dell'autenticatore di protezione e del serializzatore di token appropriati. Per creare un gestore del token personalizzato, creare una classe che eredita dalla classe ClientCredentialsSecurityTokenManager. I metodi primari della classe utilizzano SecurityTokenRequirement per creare le credenziali del servizio o del client e il provider appropriati. Per ulteriori informazioni sui gestori dei token di protezione personalizzati, vedere Procedura: creare credenziali client e del servizio personalizzate.

Per integrare il token di protezione personalizzato in credenziali client e server personalizzate

1. È necessario aggiungere le credenziali del client e del servizio personalizzate per fornire un'API che consenta all'applicazione di specificare informazioni sul token personalizzato che l'infrastruttura dei token di protezione personalizzati creata in precedenza utilizza per fornire e autenticare il contenuto del token di protezione personalizzato. Negli esempi seguenti viene illustrato come eseguire questa operazione. Per ulteriori informazioni sulle credenziali del client e del servizio personalizzate, vedere Procedura: creare credenziali client e del servizio personalizzate.

La classe dei parametri del token di protezione personalizzato creata in precedenza viene utilizzata per specificare nel framework di protezione WCF la necessità di utilizzare un token di protezione personalizzato quando si comunica con un servizio. La procedura seguente illustra come eseguire questa operazione.

Per integrare il token di protezione personalizzato nell'associazione

1. La classe dei parametri del token di protezione personalizzato deve essere specificata in uno degli insiemi di parametri di token esposti nella classe SecurityBindingElement. Nell'esempio seguente viene utilizzato l'insieme restituito dall'elemento SignedEncrypted. Dopo aver crittografato e firmato automaticamente il contenuto del token personalizzato della carta di credito, il codice aggiunge quest'ultimo a ogni messaggio inviato dal client al servizio.

Vedere anche

Attività

Procedura: creare un provider di token di protezione personalizzati

Riferimenti

SecurityToken
SecurityTokenParameters
WSSecurityTokenSerializer
SecurityTokenProvider
SecurityTokenAuthenticator
IAuthorizationPolicy
SecurityTokenRequirement
SecurityTokenManager
ClientCredentials
ServiceCredentials
SecurityBindingElement

Concetti

Procedura: creare credenziali client e del servizio personalizzate
Procedura: creare un autenticatore del token di protezione personalizzato
Architettura della protezione