Controlar tokens de seguridad en los complementos de SharePoint de confianza baja hospedados por el proveedor

  • Artículo

Importante

Este artículo se dedica por completo al uso de tokens de seguridad en el sistema de autorización de confianza baja, no en el sistema de confianza alta. Para obtener información sobre el uso de tokens en el sistema de confianza alta, vea Crear y usar tokens de acceso en complementos de SharePoint de confianza alta hospedados por el proveedor.

Los complementos de SharePoint que usan el sistema de autorización de confianza baja para obtener acceso a los datos de SharePoint participan en un flujo de OAuth que implica pasar tokens de seguridad (con el formato JSON Web Token) entre SharePoint, Microsoft Azure Access Control Service (ACS), los componentes remotos del complemento de SharePoint y, en algunos casos, el explorador del usuario.

Importante

Azure Access Control (ACS), un servicio de Azure Active Directory (Azure AD), se retirará el 7 de noviembre de 2018. Esta retirada no afecta al modelo de complemento de SharePoint, que usa el nombre de https://accounts.accesscontrol.windows.net host (que no se ve afectado por esta retirada). Para obtener más información, vea Impacto de la retirada de Azure Access Control para Complementos de SharePoint.

Hay diferentes flujos según el diseño del complemento, pero todos ellos implican al menos los dos tipos de tokens siguientes:

  • Token de acceso. Se incluye en todas las solicitudes de creación, lectura, actualización o eliminación (CRUD) en los componentes remotos del complemento a SharePoint. SharePoint valida el token y atiende la solicitud.
  • Token de actualización. Se usa para obtener un primer token de acceso en el flujo de tokens de contexto y para reemplazar los tokens de acceso que expiren tanto en el flujo de tokens de contexto como en el flujo de código de autorización del sistema de autorización de confianza baja.

Según el flujo de OAuth que use el complemento, uno o el resto de los siguientes elementos también forma parte del proceso:

  • Token de contexto. En el flujo de tokens de contexto, se usa para proporcionar al componente remoto un token de actualización y la información que necesita para solicitar a Azure ACS un token de acceso.
  • Código de autorización. No se trata de un token sino de un código de autorización, único para cada par de usuario y aplicación. Se usa en el flujo de Código de autorización para obtener un primer token de acceso y un token de actualización.

Tokens de acceso

En el sistema de autorización de confianza baja, Azure ACS crea los tokens de acceso y los envía al componente remoto del complemento de SharePoint. (En el momento de redactarse este artículo, los tokens de acceso emitidos por ACS para SharePoint tenían una duración de 12 horas, pero esto podría cambiar). Las principales cosas que debe implementar el código en el complemento de SharePoint son:

  • Solicitar un token de acceso de Azure AD. Según el flujo de OAuth en el que se use, el complemento utiliza un código de autorización o la información que extrae de un token de contexto para realizar la solicitud.
  • Incluir el token de cada solicitud HTTP en 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.
  • Opcionalmente (pero recomendado), almacene en caché el token de acceso para reutilizarlo en solicitudes posteriores.
  • Opcionalmente, reenvíe el token de acceso a los sistemas back-end para que puedan obtener acceso directamente a SharePoint.

Debe realizar estas tareas con el código del lado servidor. Si usa código administrado, el código de ejemplo de algunas de estas tareas se encuentra en los archivos SharePointContext.cs (o .vb) y TokenHelper.cs (o .vb) que forman parte de Microsoft Office Developer Tools para Visual Studio. Para obtener un ejemplo de código PHP que realiza algunas de estas tareas, vea MSDN: SharePoint 2013 - Descripción y uso de la interfaz REST de SharePoint.

Almacenar en caché el token de acceso

Según la arquitectura del complemento de SharePoint y de la plataforma de hospedaje, hay varias maneras de almacenar en caché el token de acceso en el servidor.

Nota:

En la mayoría de los escenarios, no podrá usar términos tan sencillos como "AccessToken" como clave de almacenamiento en caché, ya el complemento debe mantener los tokens para distintos usuarios y espacios empresariales o granjas de SharePoint. Si su complemento usa el Flujo de tokens de contexto, existe una CacheKey que SharePoint proporciona y se puede usar para distinguir los tokens almacenados en caché. En esta sección se explica cuáles son los problemas y qué hacer cuando su aplicación no usa el flujo de tokens de contexto.

El almacenamiento en caché del token de acceso de estado de la sesión es adecuado para la mayoría de los escenarios. Si la aplicación web remota tiene acceso a otros servicios que usan OAuth (además de SharePoint) y su almacenamiento en caché de los distintos tokens de acceso en estado de sesión, asegúrese de usar claves de caché distintas para los tokens; por ejemplo, en lugar de "AccessToken", use "SharePoint_AccessToken", "Facebook_AccessToken", "SAP_Gateway_AccessToken", etc. (Si no usa el estado de la sesión o algún otro almacenamiento en caché que distinga automáticamente la caché de cada usuario, tendrá que relativizar las claves de los usuarios).

Si la aplicación tiene acceso a más de una granja de SharePoint o un espacio empresarial de SharePoint Online, puede usar el dominio de SharePoint como parte de la clave principal de almacenamiento en caché de la aplicación (SharePoint<mydomain>.sharepoint.com_AccessToken) o usar el dominio kerberos de la granja o el espacio empresarial (SharePoint<realmGUID>_AccessToken), ambos pueden leerse en el token de acceso. (El código debe invertir la codificación base 64 del token para leerlo. En el código administrado, el archivo TokenHelper.cs o .vb tiene código de ejemplo para este fin que usa clases de los espacios de nombres Microsoft.IdentityModel.S2S.Tokens y System.IdentityModel.Tokens ). Hay otra opción disponible cuando la aplicación usa el flujo de token de contexto, como se describe en el párrafo siguiente.

Es posible que existan escenarios en los que la aplicación tenga que almacenar en caché el token de acceso en algún lugar que esté disponible para la aplicación en todas las sesiones o después de que una sesión finalice. Por ejemplo, puede que la aplicación se diseñe para permitir que los usuarios programen las acciones que se producen después de que el usuario ha cerrado la aplicación. Si estas acciones incluyen el acceso a SharePoint, el complemento tiene que recuperar el token de acceso. En este tipo de escenarios, la aplicación debe mantener bien diferenciados los tokens de acceso de los distintos usuarios.

Si usa el flujo de tokens de contexto, se proporciona una cadena de clave de caché con esta finalidad en el token de contexto que SharePoint pasa al componente remoto del complemento de SharePoint al iniciar el complemento. Para obtener más información sobre la clave de caché especial y cómo usarla, vea Información sobre la clave de caché. También puede usar esta cadena en el escenario descrito anteriormente. El sistema de programación tiene algunos métodos de almacenamiento de los datos de configuración que necesita, por ejemplo, cuando se ejecuta el trabajo programado y lo que debe hacer. Use este almacenamiento para conservar la clave de caché del token de acceso.

Si la caché entre sesiones que usa también está compartida entre varias aplicaciones, las claves de caché tendrán que relativizarse para las aplicaciones, los usuarios y los dominios kerberos de SharePoint. La clave de caché que se proporciona en el token de contexto es exclusiva para las aplicaciones, los usuarios y los dominios kerberos de SharePoint.

Si la aplicación usa el flujo de Código de autorización, no hay ningún token de contexto y, por lo tanto, no se crea especialmente ninguna clave de caché. En ese escenario, tendrá que crear su propio sistema de claves para los datos en caché que se relativicen para uno o varios de los siguientes casos, según los posibles conflictos de nombres que se puedan dar en función de los casos de uso de la aplicación: el usuario, el dominio kerberos de SharePoint y la aplicación. Puede usar las notificaciones en el token de acceso con esta finalidad; por ejemplo, nameId y aud (vea las tablas siguientes). El código simplemente concatenará las cadenas o las usará como valores de inicialización para crear un hash único que pueda funcionar como clave de caché.

Por último, si la aplicación realiza llamadas de solo complemento o de usuario+complemento a SharePoint, tendrá dos tokens de acceso diferentes, por lo que necesitará distintas claves de caché. Una vez que haya decidido una clave de caché básica, simplemente anexe "_add solo" o "_add-in+user" a ella.

Advertencia

Almacenar el token de acceso en una cookie no es un procedimiento seguro. Normalmente se recomienda evitar que el token de acceso pase por el explorador.

Reenviar el token de acceso a los sistemas back-end

Es posible que un complemento de SharePoint tenga servidores back-end que no están hospedados en el mismo dominio que la aplicación web remota. Cuando un servidor back-end tiene que realizar operaciones CRUD en SharePoint, el complemento las realiza con mayor rapidez si estas operaciones pueden ir directamente del sistema back-end a SharePoint. Afortunadamente, el dominio solo tiene importancia cuando la aplicación obtiene un token de acceso de ACS. Cuando tiene el token, puede reenviarlo a los servicios back-end, que pueden usarlo para llamar a SharePoint.

El código de estos sistemas tiene que controlar los tokens de acceso expirados y enviar una solicitud para uno nuevo a la aplicación web principal que está registrada con ACS (vea Controlar los tokens de acceso expirados). Esta técnica solo puede usarse con los propios servidores back-end de la aplicación, no en los servicios web externos. Además, si usa esta técnica, considere la posibilidad de diseñar los servicios back-end para que usen llamadas solo de complemento siempre que sea posible.

Controlar los tokens de acceso expirados

Un token de acceso expira después de unas horas (12 horas en el momento en que se escribe este artículo, pero eso puede cambiar). Si la aplicación todavía tiene acceso a SharePoint una vez que expire el token de acceso, la primera solicitud a SharePoint después de la fecha de expiración ocasiona un error 401 No autorizado. El código debe controlar esta respuesta.

Como alternativa, el código puede comprobar la fecha de expiración del token de acceso antes de usarlo. El código usa el token de actualización para obtener otro token de acceso de ACS. En el flujo de tokens de contexto, el token de actualización se incluye en el token de contexto que el complemento recibe de SharePoint al inicio de su primera sesión con SharePoint. En el flujo de Código de autorización, se pasa a la aplicación con el primer token de acceso. El código debe almacenarse en caché para que esté disponible cuando sea necesario. El token de actualización dura unos meses y puede permanecer en una cookie o en un almacenamiento del lado servidor. Para obtener más información, vea Información sobre el control y el almacenamiento en caché de los tokens de actualización.

Ejemplos de tokens de acceso para el sistema de autorización de confianza baja

En esta sección se describen, con ejemplos, los tokens de acceso y se muestra en qué se diferencian según la directiva de autorización que se use.

Directiva de usuario+complemento

El siguiente es un ejemplo descodificado de un token de acceso de usuario y complemento generado por ACS que se usará para las llamadas a SharePoint con la directiva de usuario+complemento. Se ha agregado un espacio en blanco para mejorar la legibilidad. El token cumple con el protocolo de JSON Web Token. El objeto de notación de objetos JavaScript (JSON) del token se llama conjunto de notificaciones (vea la tabla 1 para obtener más información sobre las propiedades del conjunto de notificaciones).

Todos los valores deben estar en minúsculas. (Los tokens de acceso de usuario+complemento son los mismos del flujo de tokens de contexto y el flujo de código de autorización).

{
 "aud": "00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss": "00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf": 1377549246,
 "exp": 1377592446,
 "nameid": "2303000085ff9abc",
 "actor": "964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73",
 "identityprovider": "urn:federation:microsoftonline"
}

Tabla 1: Notificaciones de tokens de acceso de usuario y complemento emitidas por ACS

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 audience principal ID/SharePoint domain@SharePoint realm, donde id. de entidad de seguridad de audiencia es un identificador de entidad de seguridad permanente para SharePoint (vea Constantes de entidad de seguridad de aplicaciones de productos de Microsoft).

Dominio kerberos de SharePoint es el GUID del espacio empresarial de SharePoint Online o la granja de SharePoint local en donde se usa el token de acceso para tener acceso. Este GUID funciona como identificador del dominio kerberos para el emisor del token, en este caso Azure ACS.		 00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss Abreviatura de "emisor". Representa a la entidad de seguridad que creó el token. El formato es Issuer GUID@SharePoint realm GUID.En el sistema de autorización de confianza baja, el emisor es Azure ACS y su GUID es 00000001-0000-0000-c000-000000000000. 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
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. De forma predeterminada, se establece en el momento en que se crea el token (vea Valores de hora de JWT). 1377549246
exp Abreviatura de "expiración". Representa la hora en que expira el token. De forma predeterminada, es doce horas después de la hora nbf (vea Valores de hora de JWT). 1377592446
nameid Identificador único del usuario para el que se emitió el token. El formato varía según el proveedor de identidades. En este ejemplo, el proveedor es Microsoft Online, pero si fuera Active Directory, el identificador tendría un aspecto similar a s-1-5-21-2127521184-1604012920-1887927527-415149. 2303000085ff9abc
actor Entidad que intenta acceder a la granja o el espacio empresarial de SharePoint. Tiene el formato Client ID of Application@SharePoint realm. 964de6ad-6d28-4dc7-8e05-3acd8006e5c9@040f2415-e6e3-4480-96ce-26ef73275f73
identityprovider Nombre único del proveedor de identidades tal y como se registró con la autoridad de asignación de números de Internet (IANA). Para un complemento que se instala en SharePoint Online, el valor suele ser el mismo de este ejemplo. Para un complemento instalado en una granja local, suele ser un proveedor de identidades local, como urn:office:idp:activedirectory. urn:federation:microsoftonline

Directiva de solo complemento

El siguiente es un ejemplo descodificado de un token de acceso de solo complemento generado por ACS que se usará para las llamadas a SharePoint con la directiva de solo complemento. Se ha agregado un espacio en blanco para mejorar la legibilidad. El token cumple con el protocolo de JSON Web Token. Vea la tabla 2 para obtener más información sobre las propiedades del conjunto de notificaciones. (La directiva de solo complemento no está disponible para las aplicaciones que utilizan el Flujo de código de autorización, ya que no tienen un archivo de manifiesto de complemento y, por lo tanto, no pueden solicitar permiso para usar llamadas de solo complemento).

{
 "aud":"00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":1403304705,
 "exp":1403347905,
 "nameid":"c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73",
 "sub":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "oid":"1d47ac31-498b-4988-8aac-85fc9bd2e1ce",
 "trustedfordelegation":"false",
 "identityprovider":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73"
}

Tabla 2: Notificaciones de token de acceso de solo complemento emitidas por ACS

Notificación Descripción Valor correspondiente en el ejemplo de token de acceso
aud Igual que el token de usuario y complemento de la tabla 1. 00000003-0000-0ff1-ce00-000000000000/company.sharepoint.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss Igual que el token de usuario y complemento de la tabla 1. 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf Igual que el token de usuario y complemento de la tabla 1. 1403304705
exp Igual que el token de usuario y complemento de la tabla 1. 1403347905
nameid Identificador único del complemento, y no del usuario, porque la identidad del usuario no importa en la directiva de solo complemento. El formato es client ID@SharePoint realm. c76da14e-07fd-4638-a723-1ff60ce70d63@040f2415-e6e3-4480-96ce-26ef73275f73
sub Abreviatura de "firmante". firmante del token, que es la entidad de seguridad que quiere obtener acceso a SharePoint (en este caso, la aplicación web remota). Se usa el identificador de objeto para el valor. Vea la notificación oid. 1d47ac31-498b-4988-8aac-85fc9bd2e1ce
oid Abreviatura de "object ID". Este es el Identificador de objeto de Azure Active Directory para la aplicación web remota. En un token de acceso de solo complemento, el firmante y el ID. de objeto representan el mismo valor. 1d47ac31-498b-4988-8aac-85fc9bd2e1ce
trustedfordelegation Valor booleano que especifica si SharePoint debe confiar en el complemento de SharePoint para autenticar y autorizar al usuario. Su valor es falso en las llamadas de solo complemento porque la identidad de usuario no es lo importante. false
identityprovider Nombre único del proveedor de identidades. Dado que se trata del complemento, y no de un usuario, cuya identidad se proporciona, ACS es el proveedor de identidades. El formato es ACS GUID@SharePoint realm. 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73

Tokens de contexto

Un token de contexto solo se utiliza en el flujo de tokens de contexto del sistema de autorización de confianza baja. Cuando el complemento de SharePoint se inicia en SharePoint, este solicita que Azure ACS cree un token de contexto que SharePoint pasará luego al componente remoto del complemento de SharePoint. El token se pasa como un parámetro de formulario oculto denominado SPAppToken en una solicitud de SharePoint de la página de inicio del componente remoto. El token se firma con un secreto de cliente que solo ACS y el complemento de SharePoint conocen.

El token de contexto incluye un token de actualización que el complemento utiliza, junto con otra información del token de contexto, para solicitar un token de acceso de ACS. (En el momento de redactarse este artículo, los tokens de contexto emitidos por ACS tenían una duración de doce horas, pero esto podría cambiar).

Las principales tareas del código en el complemento de SharePoint son las siguientes:

  • Usar el secreto de cliente del complemento para validar el token de contexto.
  • Almacenar en caché el token de contexto (o extraer y almacenar por separado en caché el token de actualización, así como otros elementos que contenga).
  • Use el token de actualización y otra información para solicitar un token de acceso de ACS (que luego se almacenará en caché).
  • Almacenar en caché la clave CacheKey del token de contexto.

Importante

Las dos primeras tareas deben producirse antes de que el usuario actualice la página o vaya a otra página, o de que el token se pierda. Por ejemplo, en una aplicación de formularios web ASP.NET, considere la posibilidad de realizar las tareas en el método Page_Load (en un bloque de código condicional que solo se ejecuta cuando la solicitud no es un postback). En una aplicación ASP.NET MVC, considere la posibilidad de realizar estas tareas en el método de controlador predeterminado.

Si usa código administrado, el código de ejemplo de algunas de estas tareas está en los archivos SharePointContext.cs (o .vb) y TokenHelper.cs (o .vb) que se incluyen en Microsoft Office Developer Tools para Visual Studio. Solo tiene que hacer llamadas simples a los miembros de la clase TokenHelper. Por ejemplo, su código puede realizar la primera tarea con la siguiente línea de código:

SharePointContextToken contextToken =
    TokenHelper.ReadAndValidateContextToken(contextTokenString,
    Request.Url.Authority);

Almacenar en caché el token de contexto o partes de este

Puede almacenar en caché todo el token de contexto (o bien solo el token de actualización y otros elementos que contiene y que usa el código para obtener tokens de acceso) en un almacenamiento del lado servidor o del lado cliente. Para simplificar, en este artículo se presupone que el token de contexto se almacena en caché como una unidad.

Importante

Se lo recordamos una vez más, porque es realmente importante: no use almacenamiento en caché del lado cliente para el token de acceso. Su uso solo resulta seguro para el token de contexto.

Tiene las mismas opciones de almacenamiento en caché del lado del servidor que las indicadas anteriormente para el token de acceso. Las opciones del lado del cliente incluyen una cookie y un campo de formulario oculto en una página HTML. Otra opción consiste en almacenar el token de contexto en la memoria caché de la sesión, pero almacenar en el cliente el valor de CacheKey obtenido de él.

Si la aplicación tiene acceso a SharePoint después de que finalice una sesión, no podrá usar ni el almacenamiento en caché de la sesión ni el almacenamiento en caché del lado cliente, ya que el token de actualización tiene que estar disponible para la aplicación en caso de que el token de acceso original haya expirado cuando se ejecute el trabajo posterior a la sesión. En este escenario, se necesita una memoria caché duradera (entre sesiones) compartida entre varios usuarios, dominios kerberos de SharePoint o aplicaciones. Por lo que el código tiene que usar claves de caché que distingan el usuario, el dominio kerberos de SharePoint o la aplicación, tal y como se explicó anteriormente en Almacenar en caché el token de acceso.

Puede usar la clave de caché especial que se encuentra en el token de contexto con esta finalidad, del mismo modo que se usa con el token de acceso (vea la sección siguiente Información sobre la clave de caché).

Información sobre la clave de caché

La clave de caché es una cadena opaca exclusiva de la combinación de usuario, emisor de nombres de usuario, complemento y granja de SharePoint o espacio empresarial de SharePoint Online. Antes de que se cifre, tiene el siguiente formato, donde Realm es el GUID de la granja de SharePoint local o el espacio empresarial de SharePoint Online.

UserNameId + "," + UserNameIdIssuer + "," + ApplicationId + "," + Realm

La clave de caché no contiene información de dirección URL del sitio. Cada espacio empresarial de SharePoint Online (o granja de SharePoint local) tiene un dominio kerberos único, por lo tanto, la clave de caché es exclusiva para cada combinación de nombre de usuario, emisor de nombres de usuario, aplicación y granja. En el token de contexto de ejemplo, el valor de la clave de caché cifrada es:

KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=

Dado que la aplicación puede almacenar varios elementos en la caché, como el token de acceso y el token de contexto en la misma memoria caché con la misma clave de caché, puede usar la clave de caché como recurso al que anexar o anteponer una cadena específica, como "AccessToken" o "ContextToken", según sea necesario para formar una clave de caché completa.

Otra opción consiste en crear una clase con propiedades para los diferentes elementos que quiera almacenar en caché y, después, almacenar en caché un objeto de ese tipo.

Una tercera opción, si usa una base de datos como memoria caché, es usar una tabla con una columna CacheKey y columnas adicionales para los elementos almacenados en caché (AccessToken, ContextToken, etc.).

Por supuesto, su aplicación no tiene que usar la misma memoria caché para todo lo que almacena en caché. Un modelo habitual es almacenar el token de acceso en la memoria caché de sesión, el token de contexto (o el token de actualización incluido en él) en una base de datos y el valor de CacheKey en una cookie.

Usar el token de contexto para obtener un token de acceso

Para obtener un token de contexto, su aplicación envía una solicitud directamente a ACS. La solicitud incluye tres partes de información que se extraen del token de contexto (y otra información):

  • El token de actualización
  • El GUID de entidad de seguridad de la aplicación de SharePoint.
  • El GUID de dominio kerberos de la granja de SharePoint o el espacio empresarial de SharePoint Online al que el complemento quiere acceso

El archivo TokenHelper.cs (o .vb) contiene código que crea esta solicitud. Para obtener un ejemplo de código PHP que haga esto, vea SharePoint: Realizar operaciones en la biblioteca de documentos de SharePoint desde el sitio PHP.

La aplicación puede obtener el dominio kerberos del espacio empresarial o la granja de SharePoint en el tiempo de ejecución como alternativa a analizarlo desde el token del contexto. Si usa código administrado, hay un método TokenHelper.GetRealmFromTargetUrl para obtener el dominio kerberos. No olvide almacenar en caché el valor para que el código no realice otra llamada de red para volver a obtenerlo.

Obtener un nuevo token de contexto

Si necesita un nuevo token de contexto, normalmente porque el token de actualización (que se incluye en los tokens de contexto) ha expirado, el código puede obtener uno nuevo redireccionando el explorador a una página especial en todos los sitios web de SharePoint, AppRedirect.aspx. Hay que asociar dos parámetros de consulta a la dirección URL de esta página:

  • client_id: Identificador de cliente del complemento de SharePoint.
  • redirect_uri: URI al que quiere redirigir el explorador después de obtener el nuevo token de contexto. SharePoint publicará el token de contexto en este URI. Suele ser la misma página, método de controlador o método de servicio web que solicitó el nuevo token de contexto. El valor debe estar codificado como URL.

En el ejemplo siguiente se muestra la estructura de la dirección URL:

https://<SharePointDomain> /_layouts/15/appredirect.aspx?client_id=<app_client_GUID> &amp;redirect_uri=<URL-encoded_redirect_URI>

El siguiente es un ejemplo de cómo crear la solicitud en ASP.NET con el archivo TokenHelper:

Response.Redirect(TokenHelper.GetAppContextTokenRequestUrl(sharePointUrl, Server.UrlEncode(Request.Url.ToString())));

Ejemplo de un token de contexto

A continuación, se muestra un ejemplo de firma. El pequeño objeto de notación de objetos JavaScript (JSON) del principio contiene metadatos sobre el token. Estas propiedades son las mismas de los tokens de acceso (vea anteriormente). El valor de la propiedad alg es el nombre del algoritmo que se usa para generar la firma que ACS anexa al token. Vea la tabla 3 para obtener más información sobre las propiedades de la carga del token. Todos los valores deben estar en minúsculas. (Se ha agregado un espacio en blanco para mejorar la legibilidad).

{"typ":"JWT","alg":"HS256"}
.
{
 "aud":"a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73",
 "iss":"00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "nbf":"1335822895",
 "exp":"1335866095",
 "appctxsender":"00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73",
 "appctx":"{
            \"CacheKey\":\"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\",
            \"SecurityTokenServiceUri\":\"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
           }",
 "refreshtoken":"IAAAAC1Lv5w0OrcFAmJx0xk6aaBdhgsw3VPnPzNEDAWypTHtCYytZ2/dBBUKj+HLK8YB3IUCUfDxYpAque
NHKtgs4rYJJ5AegQpNMOJR1yYK8ngivQx0oetj7aSPuGVb+k6at6G0Kx5LZ5vhxkAq8iUSwu8p4L2cvNMzDF1mDKfMivqxgrIZkr2nbf9as0SJFL6VG5hZnDE4HKq
xJnejSW3umatKM4fsfY1MClVCxrkXb2EQ8H/TmwaJc388YW063GEVUS/3BTSgSIRBKQUmXJuJ6BZY7WTm84LaGrx3mIjnUTM/jnqPoPG55JbCC9sS/MeGNPtzPPCDg
6Vv7dVhQ1Dq5Y3fQ65e9LpJ580jCgzYYvpIFT+Wx5V+17mjY2T8wug04K2ts87Znsr+GfFCorf7NS/lj5HjoxRAQ2tva/8dwguSLwxcUwi/Q9MbpR0NNtlpwVazqi9O
hJ4Df7gVhUDdJ0Dtc6aFCPbl5ZLDDRs42xK2",
 "isbrowserhostedapp": "true"
}

Las notificaciones aud, iss, nbf y exp son exactamente iguales a las de un token de acceso que se describen en la tabla 1.

Las notificaciones appctxsender, appctx, CacheKey, SecurityTokenServiceUri, refreshtoken y isbrowserhostedapp se describen en la siguiente tabla.

Tabla 3. Notificaciones e información de un token de contexto

Notificación Descripción Valor correspondiente en el token de contexto de ejemplo
aud a044e184-7de2-4d05-aacf-52118008c44e/fabrikam.com@040f2415-e6e3-4480-96ce-26ef73275f73
iss 00000001-0000-0000-c000-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
nbf 1335822895
exp 1335866095
appctxsender Abreviatura de "remitente de contexto de aplicación". Representa la aplicación que envió el token de contexto al complemento de SharePoint. Tiene el formato GUID of principal@SharePoint realm, donde GUID de la entidad de seguridad es el identificador de constante de la entidad de seguridad de la aplicación; puede ser SharePoint, Exchange, Lync o Workflow. 00000003-0000-0ff1-ce00-000000000000@040f2415-e6e3-4480-96ce-26ef73275f73
appctx Abreviatura de "contexto del complemento". Es un objeto JSON que contiene los valores de CacheKey y SecurityTokenServiceURI. CacheKey:"KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=\", SecurityTokenServiceUri:"https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2\"
CacheKey Valor único que se puede usar como clave en una memoria caché estructurada de claves y valores para almacenar y recuperar el token de contexto. También se podría usar como valor de una columna de clave en una fila de una base de datos. KQAIUpDUD0sm5Tr83U+jZGYVuPPCPu8BGwoWiAACqNw=
SecurityTokenServiceURI El URI del servicio emisor de tokens. https://accounts.accesscontrol.windows-int-sn1-004.accesscontrol.aadint.windows-int.net/tokens/OAuth/2
refreshtoken El token de actualización del complemento. IAAAAC1Lv5w0OrcFAmJx0xk6???
isbrowserhostedapp Campo Boolean que especifica si la solicitud al complemento que contiene el token de contexto procede de un explorador (true) o de un receptor de eventos remotos (false). true

Usar el token de contexto para limitar el acceso solo a usuarios de SharePoint

Si desea limitar el acceso al componente remoto, como un servicio WCF, a los usuarios de SharePoint, el código puede validar simplemente el token de contexto en la solicitud HTTP. (Si usa código administrado, solo tendrá que llamar a TokenHelper.ReadAndValidateContextToken()).

El código puede comprobar que la notificación de actor del token empieza por 00000003-0000-0ff1-ce00-000000000000, si quiere asegurarse de que es SharePoint (y no, por ejemplo, Exchange, Lync o Workflow). Si quiere realizar una validación adicional que requiera una devolución de llamada a SharePoint (como limitar el acceso a los usuarios con un determinado rol en SharePoint), puede almacenar en caché el hecho de que ha realizado esta validación para un determinado usuario (mediante el objeto CacheKey del token de contexto) para que solo tenga que hacerlo una vez.

Tokens de actualización

Un token de actualización se incluye en el token de contexto que SharePoint publica en la aplicación web al iniciarse. El token de actualización es un token cifrado que no podrá descifrar el complemento de SharePoint. El código lo usa, junto con otra información, para obtener un nuevo token de acceso cuando expire el token actual. También se utiliza para obtener el primer token de acceso del Flujo de tokens de contexto. (En el momento de redactarse este artículo, los tokens de actualización emitidos por ACS tenían una duración de seis meses, pero esto podría cambiar).

Dado que un token de acceso dura varias horas (normalmente, doce) y un usuario final obtiene uno nuevo cada vez que inicia el complemento de SharePoint desde SharePoint, solo necesita el token de actualización en uno de estos escenarios:

  • Los usuarios mantienen sesiones largas con el complemento, y este realiza llamadas a SharePoint muchas horas después de que se inicia (actualmente más de 12).

  • El diseño del complemento permite a los usuarios programar el acceso a SharePoint del complemento en un momento posterior a que finalice la sesión.

Los dos escenarios requieren que el complemento almacene en caché el token de actualización y el segundo escenario requiere una caché del lado servidor que sea duradera entre sesiones. Las opciones de almacenamiento en caché son iguales a las del token de acceso y, en el flujo de tokens de contexto, se puede usar la clave de caché del token de contexto. (En el flujo de token de contexto, solo tiene que almacenar en caché el token de contexto. Contiene el token de actualización y otra información que necesita para obtener un nuevo token de acceso. En el flujo de código de autorización, no hay ningún token de contexto, por lo que se almacena en caché el propio token de actualización).

Si guarda en caché el token de actualización en un almacenamiento que persiste entre sesiones de un usuario específico con su complemento, asegúrese de reemplazarlo por el token de actualización más reciente. En los flujos de código de autorización y de hospedado en la nube, el usuario obtiene un nuevo token de actualización cada vez que inicia el complemento.

Si el token de actualización ha expirado, una solicitud a ACS de un nuevo token de acceso ocasiona un error 401 No autorizado. El complemento debería responder a este error obteniendo un nuevo token de actualización y usándolo para obtener un nuevo token de acceso. (Como el token de actualización está cifrado, el código no puede comprobar la fecha de expiración antes de usarlo).

En el flujo de tokens de contexto, el complemento obtiene un nuevo token de actualización al obtener un nuevo token de contexto. En el flujo de código de autorización, el complemento obtiene un nuevo token de actualización al reiniciar el flujo. Concretamente, el código debe responder al error redirigiendo al usuario a la página OAuthAuthorize.aspx de SharePoint, tal y como se describe en Información sobre el flujo de OAuth para complementos que solicitan permisos al instante.

Códigos de autorización

En el flujo de código de autorización, el proceso de autorización comienza con un código de autorización que emite ACS, a petición de SharePoint, y que SharePoint pasa a la aplicación remota como parámetro de consulta. El código de autorización es exclusivo para cada par de usuario y aplicación remota. (En el momento de redactarse este artículo, los tokens de autorización emitidos por ACS tenían una duración de cinco minutos, pero esto podría cambiar).

La lógica de la aplicación debe obtener el código de autorización de los parámetros de consulta y usarlo en una solicitud a ACS de un token de acceso. Si usa código administrado, el código de ejemplo para crear el token se encuentra en el archivo TokenHelper.cs (y .vb). El código de ejemplo para leer el parámetro de consulta se encuentra en Obtener código subyacente de ejemplo para una página que obtenga acceso a SharePoint. ACS invalida el código de autorización inmediatamente después de emitir el token de acceso, por lo que solo se puede usar una vez y no tiene sentido almacenarlo en caché.

Valores de hora de JWT

Las notificaciones nbf y exp tienen el formato establecido por la especificación JWT. Se escriben como el número de segundos transcurridos desde el 1 de enero de 1970. En C#, puede traducir estos valores con el código siguiente, donde jWTTimeStamp corresponde al valor del token, como, por ejemplo, 1335822895.

DateTime exp = new DateTime(1970,1,1).AddSeconds(jWTTimeStamp);

Solución de problemas de control de tokens

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 decodifica automáticamente los tokens de acceso en las solicitudes.

Consulte también