Compartir a través de

Crear y usar tokens de acceso en complementos de SharePoint de confianza alta hospedados por el proveedor

  • Artículo

Importante

Este artículo se dedica por completo al uso de tokens de acceso en el sistema de autorización de confianza alta, no en el sistema ACS. Para obtener información sobre el usuario de tokens de seguridad en el sistema ACS, vea Controlar tokens de seguridad en los complementos de SharePoint de nivel de confianza bajo hospedados en el proveedor.

Los complementos de SharePoint que usan el sistema de autorización de confianza alta para obtener acceso a SharePoint tienen que pasar un token de acceso (con el formato JSON Web Token) a SharePoint con cada solicitud de creación, lectura, actualización o eliminación (CRUD). SharePoint valida el token y atiende la solicitud.

En este artículo se ofrece información sobre cómo el código crea y pasa el token de acceso.

En el sistema de autorización de confianza alta, el componente remoto del complemento de SharePoint crea el token de acceso. Si el componente remoto usa código administrado para el código del lado servidor, la mayor parte de la codificación para crear los tokens se realiza automáticamente en los archivos SharePointContext.cs (o .vb) y TokenHelper.cs (o .vb) que se incluyen en Office Developer Tools para Visual Studio.

Como los clientes de un complemento de SharePoint de confianza alta tienen SharePoint local, es probable que no tengan problemas en usar ASP.NET, IIS y Windows Server como pila de hospedaje para el componente remoto. Plantéese usar esta pila, ya que los dos archivos generados le ahorrarán mucho trabajo de codificación y pruebas.

Si el componente remoto necesita usar un lenguaje distinto de .NET, y tanto el componente remoto como la granja de SharePoint están conectados a Internet, plantéese usar el sistema de autorización de confianza baja y no el de confianza alta. En el sistema de Microsoft Azure Access Control Service (ACS), toda la creación de tokens la realiza ACS, por lo que le ahorra mucho trabajo.

El resto de este artículo está dedicado principalmente a proporcionar directrices a los desarrolladores que crean complementos de SharePoint con componentes remotos que no son .NET y que usan el sistema de autorización de confianza alta. También ofrece información útil para la depuración de complementos de SharePoint basados en .NET que usan el sistema de confianza alta.

Control de los tokens de acceso

Nota:

Al leer este artículo, especialmente en relación con las tareas que el código tiene que realizar, recuerde que, si usa código administrado, Microsoft Office Developer Tools para Visual Studio agregará a todos los proyectos de complemento de SharePoint dos archivos de código generado, SharePointContext.cs (o .vb) y TokenHelper.cs (o .vb), que realizan la mayor parte de estas tareas automáticamente El código de control de tokens de la aplicación suele consistir en unas cuantas llamadas a las clases en estos archivos

El objetivo de este tema es ayudar a los desarrolladores que no usan código administrado (y a los que tratan de solucionar problemas de tokens). Encontrará vínculos a bibliotecas de OAuth para diferentes lenguajes y plataformas en OAuth 2.0 (desplácese hasta Bibliotecas de cliente). Para obtener más información, busque "OAuth 2" y "JSON Web Token" (sin comillas) en GitHub.

El código debe:

  1. Crear un token de acceso. Las subtareas para crear este token varían en función de que la aplicación web remota solo realice llamadas de complemento a SharePoint, llamadas de usuario y de complemento, o ambas. Para obtener más información, vea Tipos de directivas de autorización de complementos en SharePoint.

    • Si el complemento realiza llamadas de usuario y complemento, la creación del token de acceso incluye las subtareas siguientes:

      1. Cree un token de actor que identifique el complemento de SharePoint e indique a SharePoint que delegue la autenticación y autorización de usuarios en el complemento y codifíquelo con codificación Base 64. Encontrará información sobre las notificaciones y la estructura del token de actor en la tabla 2. Encontrará información sobre cómo codificar y firmar el token en Encoding and signing tokens.
      2. Firme el token de actor con las credenciales de un certificado x509 que un administrador de granja de SharePoint haya configurado como de confianza para SharePoint.
      3. Incluya el token de actor en el token de acceso.
      4. Agregue otras notificaciones necesarias al token de acceso. Encontrará información sobre las notificaciones y la estructura del token en la tabla 1.

    • Si el complemento realiza llamadas de solo complemento, el código solo tiene que hacer las dos primeras subtareas. El token de actor funciona como token de acceso.

    • Si el complemento hace algunas llamadas de usuario+complemento y algunas llamadas de solo complemento, debe crear un token de actor simple para las llamadas de solo complemento y un token de acceso anidado mayor para las llamadas de usuario+complemento. No se puede usar el mismo token para ambas.

  2. Incluya el token de acceso en cada solicitud HTTP a SharePoint. El token se agrega como encabezado Authorization en la solicitud. El valor del encabezado es la palabra "Bearer" seguida de un espacio y del token de acceso con codificación Base 64.

  3. Opcionalmente, almacenar en caché el token de acceso para reutilizarlo en siguientes solicitudes.

Debe realizar estas tareas con el código del lado servidor. Si usa código administrado, el código de ejemplo para algunas de estas tareas se encuentra en los archivos SharePointContext.cs (o .vb) y TokenHelper.cs (o .vb) que generan Microsoft Office Developer Tools para Visual Studio.

Almacenar en caché el token de acceso

Una vez creado, el token se puede reutilizar en llamadas posteriores a SharePoint hasta que expire. Según la arquitectura y la plataforma de hospedaje del componente remoto de SharePoint, hay varias maneras de almacenar en caché el token de acceso en el servidor.

Si el almacenamiento en caché se comparte con distintas sesiones de usuario, como la caché de la aplicación, asegúrese de usar una clave de caché exclusiva de la sesión.

Si la caché se comparte entre varias aplicaciones, el código también debe relativizar la clave de caché para esa variable. También es posible que el complemento tenga acceso a distintas granjas de SharePoint. Se necesitan distintos tokens de acceso para cada una de ellas, por lo que en ese escenario sería necesario relativizar la clave de caché para la granja.

En general, puede que necesite claves de caché que se basen en uno o varios de los siguientes elementos: identificador de usuario, identificador de aplicación y dominio o territorio de SharePoint. Plantéese usar una clave de caché similar a la que usan los complementos de SharePoint que utilizan el sistema de autorización de confianza baja. Para obtener más información, vea Información sobre la clave de caché.

Básicamente, se concatenan uno o varios de estos tres identificadores (y, opcionalmente, se crea un hash del resultado en una cadena más corta) para que funcione como clave de caché.

Controlar los tokens de acceso expirados

El token de acceso tiene una fecha de expiración que el código puede establecer en el valor que se prefiera. Si el complemento crea un token de acceso para cada una de las solicitudes, cada token solo tiene que durar lo suficiente para ser validado por SharePoint, no más de unos segundos, a menos que la LAN del cliente esté habitualmente atascada. Puede configurar la fecha de expiración en años en el futuro, pero, incluso en el escenario "todo en local" en el que se diseñan complementos de confianza alta, hay cierto riesgo de que los tokens de acceso se roben. Por lo que debe plantearse establecer la fecha de expiración en tan solo unas cuantas horas. (Si trabaja con código administrado, el código de creación de tokens de ejemplo del archivo TokenHelper.cs [o .vb] establece la expiración en doce horas).

Si una sesión de usuario con el complemento de SharePoint tiene una duración mayor que el token de acceso almacenado en caché, la primera solicitud a SharePoint después de la expiración del token ocasiona un error 401 No autorizado. El código debe controlar esta respuesta. Si no, puede comprobar la fecha de expiración del token de acceso antes de usarlo. El código debe responder a un token de acceso expirado creando otro token de acceso y repitiendo la solicitud que no se ha realizado.

Estructura de los tokens de acceso

El siguiente es un ejemplo de token de acceso generado por un complemento de SharePoint de confianza alta; en concreto, este token ha sido generado por el código de ejemplo del archivo TokenHelper.cs (o .vb) que forma parte de la plantilla de proyecto de complemento de SharePoint creada por Office Developer Tools para Visual Studio. El token se ha descodificado y se ha agregado un espacio en blanco para mejorar la legibilidad. Los tokens de acceso utilizados en el sistema de confianza alta son compatibles con MS-SPS2SAUTH: Protocolo de autenticación de OAuth 2.0: Perfil de SharePoint, que también se denomina protocolo de servidor a servidor o S2S. Esta información tiene por objeto ayudar a los desarrolladores que usan código administrado a depurar complementos de SharePoint de confianza alta y ofrecer algunas instrucciones sobre cómo crear los tokens a desarrolladores que usan otros idiomas.

Este token de acceso se genera si el complemento realiza una llamada a SharePoint mediante la directiva de usuario y complemento. Si el complemento usa la directiva de solo complemento y realiza una llamada de solo complemento a SharePoint, el token de actor (que es un token secundario dentro del token de acceso de usuario+complemento que se describe más adelante), se convierte en el token de acceso (y no hay ningún token principal).

Nota:

Tenga en cuenta que los tokens de acceso de confianza alta que su código crea son diferentes de los que Azure ACS crea cuando se usa el sistema de autorización de confianza baja:

  • La notificación alg del encabezado es "none", ya que el token de acceso de una llamada de usuario+complemento desde un complemento de confianza alta no está firmado.
  • La URL del complemento del valor aud de este ejemplo se encuentra en un servidor local, que es lo habitual en el sistema de confianza alta.
  • No hay ninguna notificación identityprovider, pero hay un nii (emisor de identidades de nombre) con el mismo tipo de valores que los tokens de acceso de la notificación identityprovider usan en el sistema de autorización de confianza baja. (Para obtener información sobre este valor cuando el proveedor de identidades está basado en SAML, vea las entradas de blog de Steve Peschka Seguridad en complementos de SharePoint: parte 8 y Usar complementos de SharePoint con sitios SAML y FBA en SharePoint 2013.
  • No hay ninguna notificación actor, pero hay una notificación actortoken que contiene un token interno con codificación Base 64 con una duración de doce horas.

El encabezado tiene dos propiedades. "typ" es el tipo de token. El código de la aplicación web remota debe establecer siempre este valor en "JWT". "alg" es el algoritmo que se usa para iniciar el token. Dado que el token exterior de una llamada de usuario+complemento desde un complemento de confianza alta no está firmado, establezca este valor en "none". Vea la tabla 1 para obtener información sobre los valores incluidos en la parte del cuerpo del token de acceso de confianza alta.

{"typ":"JWT", "alg":"none"} 
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"s-1-5-21-2127521184-1604012920-1887927527-2963467",
 "nii":"urn:office:idp:activedirectory",
 "actortoken":"6sMZhbw … [remainder of long base 64 string omitted] … "
}

En la tabla siguiente se incluyen algunas instrucciones sobre las propiedades que el código debe incluir en el token de acceso y los valores que tiene que establecer para ellos. Si usa código administrado, los archivos SharePointContext.cs (o .vb) y TokenHelper.cs (o .vb) crean los tokens automáticamente. Por ejemplo, el código realiza una sola llamada al método SharePointContext.CreateUserClientContextForSPHost. A su vez, llama a los métodos de la clase TokenHelper que crean el token de acceso, que luego se incluye en todas las llamadas que realiza a SharePoint el objeto de contexto de cliente de SharePoint que SharePointContext.CreateUserClientContextForSPHost devuelve.

Tabla 1: Notificaciones de tokens de acceso emitidas por aplicaciones

Notificación Descripción Valor correspondiente en el ejemplo de token de acceso
aud Abreviatura de "audiencia", que indica la entidad de seguridad a la que está dirigido el token.

El formato es id. de entidad de seguridad de audiencia/nombre de dominio completo de SharePoint@dominio kerberos de SharePoint.

La entidad de seguridad de audiencia de un complemento de SharePoint siempre es 00000003-0000-0ff1-ce00-000000000000.

Como los complementos de SharePoint de confianza alta suelen usarse en escenarios totalmente locales, el nombre de dominio completo de SharePoint suele ser un nombre de servidor. El dominio de SharePoint es el GUID de la granja de SharePoint local a la que se usa el token de acceso para acceder (o el GUID del inquilino, si la granja de servidores se ha configurado para tenencias).

Busque el dominio kerberos de SharePoint ejecutando el cmdlet Get-SPAuthenticationRealm de PowerShell en el servidor de SharePoint y úselo directamente en el código o guardarlo en un archivo de configuración donde el código pueda leerlo, como la sección app.Settings de un archivo Web.config.

Como alternativa, el código puede detectar dinámicamente el dominio kerberos de SharePoint en tiempo de ejecución enviando un desafío de autenticación en SharePoint. Para obtener un ejemplo de cómo hacerlo en código administrado, vea el método GetRealmFromTargetUrl en el archivo TokenHelper.cs (o .vb).		 00000003-0000-0ff1-ce00-000000000000/MarketingSharePointServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
iss Abreviatura de "emisor". Representa a la entidad de seguridad que creó el token.

El formato es GUID de emisor@GUID de dominio kerberos de SharePoint. En el sistema de confianza alta, el emisor es el propio complemento, por lo que se usa el identificador de cliente del complemento de SharePoint como GUID de emisor.

Todas las letras del identificador de emisor deben estar en minúsculas.		 c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
nbf Abreviatura de "no antes de". Representa la hora en la que el token empieza a ser válido, en segundos desde la medianoche del 1 de enero de 1970. El código debe establecerla en el momento en que se crea el token. 1403212820
exp Abreviatura de "expiración". Representa la hora a la que expira el token, en segundos desde la medianoche del 1 de enero de 1970. 1403256020
nameid Identificador único del usuario para el que se emitió el token. El formato varía en función del proveedor de identidad. En este ejemplo, el proveedor es Active Directory. s-1-5-21-2127521184-1604012920-1887927527-2963467
nii Emisor del identificador de nombre. El nombre único del proveedor de identidad tal y como se registró con la autoridad de asignación de números de Internet (IANA). Para un complemento de SharePoint de confianza alta, suele ser un proveedor de identidades local, como Active Directory en este ejemplo. urn:office:idp:activedirectory
actortoken Token JWT codificado en base 64 que identifica el Complemento de SharePoint e indica a SharePoint que confíe en el complemento independientemente del usuario que esté ejecutándolo. Véalo a continuación.

Seguidamente se muestra el actortoken descodificado. El pequeño objeto de encabezado de notación de objetos JavaScript (JSON) del principio contiene metadatos sobre el token, incluido el tipo de token y el algoritmo que se usa para iniciar sesión. La propiedad x5t del encabezado es un resumen de la huella digital del certificado X.509 que es oficialmente el emisor del token. Para crear este valor, el código hace lo siguiente:

  1. Obtiene la versión de la matriz (no la cadena) de bytes de la huella digital del certificado. Se trata de un resumen SHA1 del certificado. (En el código administrado, esto puede hacerse con el método GetCertHash(). Se requiere un equivalente en el lenguaje que se use).

  2. Codifica la matriz de bytes con una codificación de direcciones URL Base 64.

  3. Establezca el valor de la propiedad x5t en el resumen codificado.

En la tabla 2 se describen las notificaciones que el código tiene que incluir en el cuerpo del token y los valores para establecerlas.

{"typ":"JWT","alg":"RS256","x5t":"7MjK99QvkVdwz6UrKldx8AG7ydM"}
.
{
 "aud":"00000003-0000-0ff1-ce00-000000000000/MarketingServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "iss":"11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "nbf":"1403212820",
 "exp":"1403256020",
 "nameid":"c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2",
 "trustedfordelegation":"true"
}

Nota:

Si el complemento de confianza alta usa la directiva de solo complemento y realiza una llamada de solo complemento a SharePoint, el token que se muestra aquí es en realidad el token de acceso. No hay ningún token exterior. Además, no hay ninguna notificación trustedfordelegation porque los permisos del usuario son irrelevantes para una llamada de solo complemento.

Tabla 2: Notificaciones actortoken emitidas por certificado

Notificación Descripción Valor correspondiente en el ejemplo de token de acceso
aud Igual que en el token de acceso primario. 00000003-0000-0ff1-ce00-000000000000/MarketingSharePointServer@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
iss Mismo significado que en el token de acceso primario, pero el GUID de emisor no es el identificador de cliente de la aplicación web. Se trata del GUID del certificado.

Aunque el código de la aplicación crea el token de actor, se considera que el certificado es el emisor del token de actor.

Tenga en cuenta que el GUID de emisor de este ejemplo es una cadena GUID fácil de recordar que el administrador de granja usa al registrar el certificado X.509 como emisor de tokens de confianza en SharePoint. Es frecuente cuando se usa el mismo certificado como emisor de tokens de actor para todos los complementos de SharePoint de confianza alta de la granja.

Un administrador puede elegir también tener distintos certificados para cada complemento de SharePoint. En ese caso, usaría utilizaría distintos GUID generados aleatoriamente para los certificados.

Todas las letras del GUID de emisor deben estar en minúsculas.		 11111111-1111-1111-1111-111111111111@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
nbf Mismo significado que en el token de acceso primario. El mismo valor que el token de acceso primario.
exp El mismo significado que en el token de acceso primario. Mismo valor que el token de acceso primario.
nameid Identificador único del complemento de SharePoint, ya que es el "actor" en el sistema de confianza alta. El formato es client_ID@SharePoint_realm. c3ab8885-458f-4864-8804-1608145e2ac4@52aa6841-b76b-4ed4-a3d7-a259fce1dfa2
trustedfordelegation Valor booleano que especifica si SharePoint debe confiar en el complemento de SharePoint para autenticar y autorizar al usuario. Suele ser TRUE en el sistema de confianza alta. No incluya esta notificación en una llamada de solo complemento en el sistema de confianza alta. true

Codificación y firma tokens

Cuando el código haya agregado todas las propiedades y los valores a los objetos JSON del encabezado y el cuerpo, tiene que codificarlos, combinarlos en un JSON Web Token (JWT) y firmarlos. Estos son los pasos que deben seguirse.

  1. Codifique el encabezado con codificación de direcciones URL Base 64.
  2. Codifique la carga con codificación de URL en base 64.
  3. Concatene el cuerpo codificado después del encabezado codificado con un carácter "." entre ellos. Este es el JWT.
  4. Cree una firma SHA256 mediante el JWT y la clave privada del certificado.
  5. Codifique la firma con codificación de direcciones URL Base 64.
  6. Anexe la firma al final del JWT, con un carácter "." entre ellos.

En un token de actor que se usa con una llamada de solo complemento, el token de actor funciona como token de acceso. No hay ningún token exterior. En un token de acceso que se usa con una llamada de usuario+complemento, los pasos anteriores se utilizan para crear un token de actor, que luego se inserta en el cuerpo de un token de acceso como valor de la propiedad actortoken. El token de acceso completo se codifica y crea luego con los tres primeros pasos anteriores, pero no se firma, por lo que no se usan los pasos restantes del token exterior.

Solución de problemas de tokens de acceso

La herramienta Fiddler gratuita puede usarse para capturar las solicitudes HTTP enviadas por el componente remoto del complemento a SharePoint. Hay una extensión gratuita para la herramienta que descodifica automáticamente los tokens de acceso de las solicitudes.

Ver también