Flujo de OAuth de tokens de contexto para complementos de SharePointContext Token OAuth flow for SharePoint Add-ins

En SharePoint, el flujo de autorización y autenticación OAuth para un complemento de baja confianza hospedado por el proveedor implica una serie de interacciones entre el complemento, SharePoint, el servidor de autorización y el explorador en el tiempo de ejecución.In SharePoint, the OAuth authentication and authorization flow for a provider-hosted, low-trust, add-in involves a series of interactions among your add-in, SharePoint, the authorization server, and the browser at runtime. El servidor de autorización en este escenario es Microsoft Azure Access Control Service (ACS).The authorization server in this scenario is Microsoft Azure Access Control Service (ACS).

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 del complemento de SharePoint, que usa el nombre de host https://accounts.accesscontrol.windows.net (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.Azure Access Control (ACS), a service of Azure Active Directory (Azure AD), will be retired on November 7, 2018. This retirement does not impact the SharePoint Add-in model, which uses the https://accounts.accesscontrol.windows.net hostname (which is not impacted by this retirement). For more information, see Impact of Azure Access Control retirement for SharePoint Add-ins.

Con un complemento hospedado por el proveedor, tiene una aplicación web remota o un servicio web remoto independientes de SharePoint, que no forman parte de la granja de SharePoint ni del espacio empresarial de SharePoint Online.With a provider-hosted add-in, you have a remote web application or service that is separate from SharePoint, and not part of the SharePoint farm or SharePoint Online tenancy. Puede estar hospedado en la nube o en un servidor local.It can be hosted in the cloud or on an on-premises server. En este artículo, el componente remoto se denomina Contoso.com.In this article, the remote component is called Contoso.com.

Nota

El componente remoto puede hospedar también receptores de eventos que responden a los eventos que se produzcan en elementos de SharePoint, como listas o elementos de lista.The remote component can also host event receivers that respond to events that occur to SharePoint items, such as lists or list items. Los ejemplos de eventos remotos que Contoso.com podría querer responder son eventos de lista, como agregar o quitar un elemento de lista, o eventos web, como agregar o eliminar un sitio.Examples of remote events that Contoso.com might want to respond to are list events, such as adding or removing a list item; or web events, such as adding or deleting a site. Para obtener más información sobre cómo crear receptores de eventos remotos, vea Crear un receptor de eventos remotos en complementos de SharePoint.For more information about how to create remote event receivers, see Create a remote event receiver in SharePoint Add-ins.

Contoso.com utiliza el modelo de objetos de cliente (CSOM) de SharePoint o las API REST de SharePoint para realizar llamadas a SharePoint.Contoso.com uses the SharePoint client object model (CSOM) or the SharePoint REST APIs to make calls to SharePoint. La aplicación de Contoso.com usa un flujo de transmisión de tokens de OAuth para autenticarse con SharePoint.The Contoso.com application uses an OAuth token-passing flow to authenticate with SharePoint. SharePoint y Contoso.com no confían entre sí; pero ambos confían en ACS y aceptarán los tokens emitidos por ACS.SharePoint and Contoso.com do not trust each other; but both trust ACS and accept tokens issued by ACS.

Intervienen tres tokens: SharePoint hace que ACS cree un token de contexto que SharePoint reenvía a Contoso.com.There are three tokens involved: SharePoint has ACS create a context token that SharePoint forwards to Constoso.com. Contoso.com valida que ACS emitió el token de contexto porque confía en él.Contoso.com validates that the context token was issued by ACS so it trusts it. Después, Contoso.com extrae un token de actualización del token de contexto y lo usa para obtener un token de acceso directamente desde ACS.Contoso.com then extracts a refresh token from the context token and uses it to get an access token directly from ACS. Incluye el token de acceso en todas las solicitudes a SharePoint.It includes the access token in all its requests to SharePoint. SharePoint valida que ACS emitió el token de acceso, por lo que responde a las solicitudes de Contoso.com.SharePoint validates that the access token was issued by ACS, so it responds to the requests from Contoso.com.

El código de administración de tokens se proporciona en el componente remoto (pero si el componente remoto está hospedado en .NET, Microsoft Office Developer Tools para Visual Studio proporciona código de ejemplo que realiza automáticamente la mayor parte del trabajo).You provide the token-handling code in the remote component (but if your remote component is hosted on .NET, the Microsoft Office Developer Tools for Visual Studio provide sample code that does most of the work for you). Para obtener más información sobre el código de control de tokens, vea Controlar tokens de seguridad en los complementos de SharePoint de baja confianza hospedados por el proveedor.For more information about token-handling code, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.

Requisitos previosPrerequisites

Hay que completar los pasos preliminares siguientes para que un complemento de SharePoint pueda usar el flujo de tokens de contexto.The following preliminary steps must be completed before a SharePoint Add-in can use the Context Token flow:

  • Si el complemento de SharePoint se va a instalar en una granja de SharePoint local, estos requisitos de configuración no son pertinentes si solo se instala en SharePoint Online:If the SharePoint Add-in is to be installed to an on-premises SharePoint farm, these setup requirements don't apply if it is only installed to SharePoint Online:

  • Independientemente de que el complemento se instale en SharePoint Online o en una granja de SharePoint local, el complemento de SharePoint debe registrarse con ACS.Regardless of whether the add-in is installed to SharePoint Online or to an on-premises SharePoint farm, the SharePoint Add-in must be registered with ACS. Para obtener más información sobre cómo puede hacerse, vea Registrar complementos de SharePoint. Entre otras cosas, el complemento proporciona a ACS el identificador de cliente y el secreto de cliente como parte del registro.For details about how this can be done, see Register SharePoint Add-ins. Among other things, the add-in provides ACS with its client ID and client secret as part of the registration.

Flujo de tokens de contextoContext Token flow steps

En la ilustración siguiente se muestra el flujo de autorización y autenticación OAuth para un complemento de SharePoint hospedado por el proveedor.The OAuth authentication and authorization flow for a SharePoint provider-hosted add-in is shown in the following figure.

Flujo de tokens de contexto de OAuthOAuth Context Token flow

Flujo de proceso de autorización OAuth

Estos son los pasos que corresponden a los números de la figura:These are the steps that correspond to the numbers in the figure:

  1. Un usuario inicia el complemento de SharePoint desde SharePoint. El diseño del complemento determina cómo se realiza esta acción:A user launches the SharePoint Add-in from SharePoint. The design of the add-in determines how this is done:
  • Si el complemento se ha diseñado para exponer la aplicación web remota (en Contoso.com) en un elemento de complemento (que es básicamente un contenedor alrededor de un IFRAME), el inicio del complemento simplemente implica navegar a una página de SharePoint que contiene el elemento de complemento.If the add-in is designed to surface the remote web application (at Contoso.com) in an add-in part (which is essentially a wrapper around an IFRAME), launching the add-in simply means navigating to a SharePoint page that contains the add-in part. (Si el usuario no ha iniciado sesión todavía, SharePoint pide al usuario que inicie sesión). SharePoint procesa la página y detecta que hay un componente de la aplicación de Contoso.com en ella.(If the user is not already signed in, SharePoint prompts the user to sign in.) SharePoint processes the page and detects that there is a component from the Contoso.com application on the page. Para obtener más información sobre los elementos de complemento, vea Crear elementos de complemento para instalarlos con el complemento de SharePoint.(For more information about add-in parts, see Create add-in parts to install with your SharePoint Add-in.)

  • Si el complemento se ha diseñado para usarse como página completa en el explorador, el usuario selecciona el icono del complemento en la página Contenidos del sitio del sitio web de SharePoint para iniciarlo.If the add-in is designed to use as a full page in the browser, the user launches it by selecting its add-in tile on the SharePoint website's Site Contents page. (Una variante de esto se produce cuando en el complemento incluye un menú personalizado o un elemento de cinta que inicia el componente remoto).(A variation of this is when the add-in includes a custom menu or ribbon item that launches the remote component.)

  1. Independientemente de cómo se inicie el complemento, SharePoint debe obtener un token de contexto que pueda enviar a la aplicación de Contoso.com, por lo que pide a ACS que cree un token de contexto con información sobre el contexto de SharePoint, incluido el usuario actual, la dirección URL de la aplicación remota y otra información.Regardless of how the add-in is launched, SharePoint must get a context token that it can send to the Contoso.com application, so it asks ACS to create a context token that contains information about the SharePoint context, including the current user, the remote application URL, and other information. El token de contexto contiene también un token de actualización cifrado.The context token also contains an encrypted refresh token.

  2. ACS firma el token de contexto con un algoritmo que usa el secreto del complemento de Contoso.com y lo devuelve a SharePoint.ACS signs the context token by using an algorithm that uses the Contoso.com add-in secret, and returns it to SharePoint. Solo ACS y el complemento de Contoso.com saben el secreto.Only ACS and the Contoso.com add-in know the secret.

  3. Si la aplicación de Contoso.com se exponga en un elemento de complemento, SharePoint representa la página que hospeda el elemento de complemento y agrega el token de contexto a la dirección URL a la que el IFRAME del complemento llama para obtener su contenido.If the Contoso.com application is surfaced in an add-in part, SharePoint renders the page that hosts the add-in part and adds the context token to the URL that the IFRAME in the add-in part calls to get its contents. Si la aplicación de Contoso.com es una página completa, SharePoint redirige el explorador a Contoso.com e incluye el token de contexto como parte de la respuesta de redireccionamiento.If the Contoso.com application is full page, SharePoint redirects the browser to Contoso.com and includes the context token as a part of the redirect response.

  4. El token de contexto se incluye en la solicitud del explorador que se envía al servidor de Contoso.com.The context token is included in the browser request that is sent to the Contoso.com server.

  5. El servidor de Contoso.com obtiene el token de contexto y valida la firma, lo que puede hacer porque conoce el secreto de cliente.The Contoso.com server gets the context token and validates the signature, which it can do because it knows the client secret. Esto asegura a Contoso.com que el token fue emitido por ACS y no se trata de un impostor que pretende pasar por SharePoint.This assures Contoso.com that the token was issued by ACS and not an imposter pretending to be SharePoint. Contoso.com extrae el token de actualización del token de contexto y lo envía, junto con otra información, como el identificador de cliente y el secreto de cliente, a ACS en una solicitud de un token de acceso que le permita tener acceso a SharePoint.Contoso.com extracts the refresh token from the context token and sends it, along with other information, including its client ID and client secret, to ACS in a request for an access token that allows it to access SharePoint.

  6. ACS valida el token de actualización para que quede claro que emitió el token y luego devuelve un token de acceso a Contoso.com.ACS validates the refresh token so that it is assured that it issued the token, and then it returns an access token to Contoso.com. Contoso.com también puede almacenar este token de acceso en caché para no tener que pedir a ACS un token de acceso cada vez que acceda a SharePoint.Optionally, Contoso.com can cache this access token so it doesn't have to ask ACS for an access token every time that it accesses SharePoint. De forma predeterminada, los tokens de acceso son válidos durante unas horas cada vez.By default, access tokens are good for a few hours at a time. (En el momento de redactarse este artículo, los tokens de acceso emitidos por ACS para SharePoint tenían una expiración predeterminada de 12 horas, pero esto podría cambiar).(When this article was written, the default expiration for ACS-issued access tokens to SharePoint was 12 hours, but that could change.)

Cada token de acceso es específico de la cuenta de usuario indicada en la solicitud de autorización original y únicamente concede acceso al servicio (en este caso, SharePoint) que se especifica en dicha solicitud.Each access token is specific to the user account that is specified in the original request for authorization, and grants access only to the service (in this case, SharePoint) that is specified in that request. Los tokens de actualización tienen una duración mayor (seis meses en el momento de redactarse este artículo) y también se pueden almacenar en caché.Refresh tokens are longer lived (six months when this article was written) and can also be cached. Por lo tanto, el mismo token de actualización se puede canjear por un nuevo token de acceso de ACS hasta que el token de actualización expire.So, the same refresh token can be redeemed for a new access token from ACS until the refresh token itself expires. Para obtener más información sobre el almacenamiento de tokens en caché, vea Controlar tokens de seguridad en los complementos de SharePoint de baja confianza hospedados por el proveedor.(For more information about caching tokens, see Handle security tokens in provider-hosted low-trust SharePoint Add-ins.)

Cuando el token de actualización expira, Contoso.com puede obtener uno nuevo mediante un nuevo token de contexto.When the refresh token expires, Contoso.com can get a new one by obtaining a new context token. Para obtener más información, vea Obtener un nuevo token de contexto.For more information, see Get a new context token.

  1. Contoso.com usa el token de acceso para realizar una llamada de API REST de SharePoint o una solicitud de CSOM a spnv.Contoso.com uses the access token to make a SharePoint REST API call or CSOM request to spnv. Para ello, pasa el token de acceso de OAuth en el encabezado Authorization de HTTP.It does this by passing the OAuth access token in the HTTP Authorization header. (Si el componente remoto está hospedado en una plataforma. NET, en Office Developer Tools para Visual Studio se ofrece código de ejemplo para crear el encabezado).(Sample code for creating the header is provided in the Office Developer Tools for Visual Studio if your remote component is hosted on a .NET platform.)

  2. SharePoint valida el token de acceso para que quede claro que ACS emitió el token. Después, envía a Contoso.com los datos que Contoso.com solicitó, o lleva a cabo la operación de crear, leer, actualizar o eliminar (CRUD) que Contoso.com solicitó.SharePoint validates the access token so that it is assured the token was issued by ACS. It then sends the data that Contoso.com requested to Contoso.com or performs the create, read, update, or delete (CRUD) operation that Contoso.com requested.

  3. La página de la aplicación de Contoso.com se representa en el explorador (o en el IFRAME del elemento de complemento).The Contoso.com application page renders in the browser (or in the IFRAME of the add-in part).

Ver tambiénSee also