Registrar os suplementos do SharePoint

Registre seus Suplementos do SharePoint no Azure ACS usando Visual Studio, o Painel do Vendedor ou uma página AppRegNew.aspx e recupere informações de registro.

Importante

O Controle de Acesso do Azure (ACS), um serviço do Azure Active Directory (Azure AD) será desativado em 7 de novembro de 2018. Essa desativação não afeta o modele do Suplemento do SharePoint que usa o nome de host https://accounts.accesscontrol.windows.net (que não é afetado por ela). Para saber mais, confira Impacto da desativação do Controle de Acesso do Azure para Suplementos do SharePoint.

Para que os componentes remotos de um suplemento do SharePoint hospedado pelo provedor interajam com o SharePoint usando OAuth, primeiro o suplemento deve se registrar no serviço baseado em nuvem Azure ACS e no Serviço de Gerenciamento de Aplicativos do locatário ou do farm. (Este recurso se chama "Serviço de Gerenciamento de Aplicativos" porque os Suplementos do SharePoint eram originalmente chamado de "aplicativos do SharePoint").

Observação

Isso não é necessário para suplementos hospedados pelo SharePoint.

Para registrar seu suplemento no Azure ACS, especifique as seguintes informações:

• Um GUID para o suplemento, chamado de ID do cliente.
• Uma senha para o suplemento, chamada um segredo do cliente.
• Um nome para exibição do suplemento que é usado na página de consentimento, em que o usuário é solicitado a confiar no suplemento.
• Uma URL para o domínio no qual o suplemento remoto está hospedado.
• Uma URL de redirecionamento.

Depois de registrar seu suplemento, ele tem uma identidade de suplemento e é uma entidade de segurança, chamado de entidade de segurança de suplemento. Ao instalar seu suplemento, os administradores do SharePoint podem recuperar informações sobre essa entidade de segurança de suplemento específica.

Quando um usuário concede permissões de suplemento para acessar os recursos do SharePoint (o que pode ocorrer durante a instalação ou o tempo de execução, dependendo do design do aplicativo), o SharePoint obtém informações sobre o suplemento do Azure ACS. Em seguida, o SharePoint armazena essas informações no banco de dados do Serviço de Gerenciamento de Aplicativos do locatário ou farm do SharePoint. O segredo do cliente só é armazenado no Azure ACS. O SharePoint não sabe o segredo do suplemento. O serviço de banco de dados de conteúdo e outros componentes, como o serviço de perfil de usuário, podem obter o nome de exibição e outras informações básicas sobre o suplemento diretamente do serviço compartilhado de gerenciamento de aplicativos. Para saber mais, confira Recuperar informações sobre registros de suplemento e entidades de segurança de suplemento.

Observação

Este artigo presume que você está familiarizado com os conceitos básicos e princípios por trás da Estrutura OAuth 2.0. Para saber mais, consulte OAuth.net e Protocolo de autorização da Web (oauth).

Registrar seu suplemento do SharePoint no Azure ACS

Você pode registrar seu suplemento de uma destas três maneiras, dependendo de onde você está no ciclo de vida de desenvolvimento do suplemento, da arquitetura do seu suplemento e de como você pretende comercializá-lo.

Método de registro	Detalhes
Use o Visual Studio e o Microsoft Office Developer Tools para Visual Studio para criar uma identidade de suplemento temporária.	As Ferramentas para Desenvolvedores do Office do assistente do Visual Studio criam um registro temporário para o seu suplemento com o ACS e o Serviço de Gerenciamento de Aplicativos do seu site de teste do SharePoint. Quando você executa o suplemento no Visual Studio (F5), essa identidade é usada. As ferramentas também inserem a ID do cliente e o segredo nos arquivos web.config e AppManifest.xml. Quando você estiver pronto para publicar seu suplemento, você pode usar o assistente de publicação do Visual Studio para acessar o Painel do Vendedor para registrá-lo. Se você não for comercializar seu suplemento do SharePoint na Office Store, use AppRegNew.aspx para registrá-lo. (As etapas exatas estão na próxima seção.) Observação: se o suplemento solicitar permissão para acessar recursos do SharePoint dinamicamente em tempo de execução, em vez de na instalação do suplemento, você não poderá usar o Visual Studio para criar identidades de suplemento.
Registre o suplemento usando o Painel do Vendedor.	Se você pretende usar o seu suplemento em mais de um locatário ou farm do SharePoint, use o Painel do Vendedor para registrar seu suplemento, independentemente de você comercializá-lo na Office Store ou disponibilizá-lo através do catálogo de suplementos. Quando você se registra no Painel do Vendedor, é possível projetar seu suplemento com uma arquitetura multilocatário sem que os administradores do locatário ou do farm precisem registrá-lo separadamente. Além disso, se você planeja publicar seu suplemento na Office Store, é preciso usar o Painel do Vendedor para registrar seu suplemento. Você não precisa usar a loja para publicar um suplemento que está registrado no Painel do Vendedor. Saiba mais em Criar ou atualizar IDs e segredos do cliente no Painel do Vendedor.
Use a página AppRegNew.aspx.	Use o formulário AppRegNew para registrar seu suplemento do SharePoint se estiver usando o suplemento somente em um locatário ou farm. Por exemplo, se você estiver criando suplementos para uma única organização e vai distribuí-los através do catálogo de suplementos da organização, você pode usar a página AppRegNew.aspx de qualquer site em um locatário ou farm para registrar o suplemento. Não é possível publicar um suplemento registrado no AppRegNew.aspx na Office Store. Para os suplementos publicados na Office Store, você deve obter uma identidade no Painel do Vendedor.

Para registrar usando AppRegNew.aspx

1. Vá para <site collection url>/_layouts/15/AppRegNew.aspx usando um navegador da web.

   Formulário da página AppRegNew

   

2. Insira valores para os seguintes campos do formulário:

   • ID de suplemento. Também conhecida como ID de cliente; um GUID que pode ser gerado (quando você seleciona Gerar) ou colado em AppRegNew.aspx. O valor deve ser exclusivo de cada suplemento, e deve estar em letra minúscula.

   • Segredo do suplemento. Também conhecido como segredo do cliente, uma cadeia de caracteres opaca. É gerado na página AppRegNew.aspx usando o botão Gerar. Veja a seguir um exemplo de um segredo de suplemento: xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=.

     Importante

     Os segredos de suplemento expiram. Se você registrar o suplemento no Painel do Vendedor, poderá definir o vencimento para até três anos. No painel, também é possível adicionar novos segredos quando os antigos atingem a data de vencimento. O novo segredo será habilitado em todas as instâncias do suplemento. Se você registrar o suplemento com AppRegNew.aspx, o segredo vencerá em um ano. Confira os detalhes em Substituir um segredo do cliente prestes a expirar em um Suplemento do SharePoint.

   • Título. Um título amigável ao usuário; por exemplo, suplemento de impressão de fotos da Contoso. Os usuários são solicitados a conceder ou negar as permissões que o suplemento solicita. O título aparece como o nome do suplemento na solicitação de consentimento.

   • Domínio do suplemento. O nome do host do componente remoto do suplemento do SharePoint. Se o aplicativo remoto não estiver usando a porta 443, o domínio do suplemento também deve incluir o número da porta. O domínio do suplemento deve corresponder às associações de URL que você para o seu aplicativo Web. Não inclua o protocolo (“https:”) ou caracteres “/”nesse valor. Se o seu host de aplicativo Web estiver usando um alias CNAME DNS, use esse alias. Alguns exemplos:

     • www.contoso.com:3333
     • www.fabrikam.com

   • URI de redirecionamento:. O ponto de extremidade no seu aplicativo ou serviço remoto para o qual o ACS envia um código de autenticação. A rigor, os suplementos do SharePoint não usam esse valor. O URI de redirecionamento é necessário para aplicativo Web que não iniciados fora do SharePoint e que usam o Fluxo de Código de Autenticação para obter acesso autorizado a dados do SharePoint.

     O URI de redirecionamento é ignorado para suplementos do SharePoint verdadeiros (que são iniciados do SharePoint e usam o Fluxo de Token de Contexto).

     O URI de redirecionamento é geralmente a mesma página, método de controlador ou método de serviço Web que solicitou o código de autenticação do ACS, mas pode ser um ponto de extremidade diferente. O ponto de extremidade deve ter uma lógica que obtém o código de autorização da Resposta HTTP enviada pelo ACS e, em seguida, usa esse código para solicitar um token de acesso e atualização. Para saber mais, consulte Fluxo OAuth do código de autorização para suplementos do SharePoint.

     O formulário requer que você insira um valor válido, mesmo para suplementos do SharePoint verdadeiros, embora esse valor não seja usado. O valor deve ser uma URL de ponto de extremidade completa, incluindo o protocolo, que deve ser HTTPS. Por exemplo:

     • https://www.contoso.com/Default.aspx
     • https://www.fabrikam.com/RedirectAccept.aspx
     • https://www.northwindtraders.com/home/index
     • https://adventureworks.com/

3. Selecione Criar no formulário. A página é recarregada e mostra uma confirmação dos valores que foram inseridos. Faça um registro desses valores em um formulário que seja fácil de copiar e colar. Você precisará inserir os valores nos arquivos AppManifest.xml ou no assistente Publicar do Visual Studio.

Independentemente de como você registrar seu suplemento do SharePoint, quando estiver pronto para implantá-lo em um ambiente de preparo ou produção, será necessário Inserir os valores de registro nos arquivos web.config e AppManifest.xml. Se estiver usando o Visual Studio, o Microsoft Office Developer Tools para Visual Studio fará essa configuração automaticamente.

Inserir os valores de registo nos arquivos web.config e AppManifest.xml

Antes de empacotar o suplemento do SharePoint e antes de implantar seus componentes remotos, insira alguns dos valores de registro nos arquivos AppManifest.xml e web.config.

Dica

Se você publicar seu suplemento do SharePoint usando o assistente Publicar do Visual Studio, o Visual Studio solicitará uma ID de cliente e um segredo de cliente durante o processo de publicação e colocará essas informações nos lugares corretos para você.

1. No arquivo Web.config do seu projeto do Visual Studio, insira o valor da ID de suplemento como o valor de ClientId (substituindo o valor temporário inserido pelas ferramentas).

   Importante

   Todas as letras no GUID do emissor devem estar em minúsculas.

   Apresentamos um exemplo a seguir.

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     .  .  .
   </appSettings>
   

2. Insira o valor do segredo do suplemento como o valor de ClientSecret (substituindo o valor temporário inserido pelas ferramentas).

   Veja a seguir um exemplo de como os valores são usados no arquivo Web.config de um aplicativo Web.

   <appSettings>
     <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
     <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
   </appSettings>
   

3. No arquivo AppManifest.xml do seu projeto do Visual Studio, insira o valor da ID do suplemento como o valor de ClientId, com letras minúsculas.

   Observação

   O manifesto do suplemento não se aplica a aplicativos Web que solicitam permissão para acessar os recursos do SharePoint instantaneamente. Eles não são “suplementos do SharePoint” verdadeiros. Eles não estão instalados no SharePoint e não têm um manifesto de suplemento. Para saber mais, consulte Fluxo OAuth do código de autorização para suplementos do SharePoint.

   O exemplo a seguir mostra como o valor ClientId é usado no arquivo AppManifest.xml.

   <AppPrincipal>
     <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
   </AppPrincipal>
   

4. As Ferramentas para Desenvolvedores do Office usam o token ~remoteAppUrl no elemento StartPage. (Por exemplo, <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>.) Esse token será resolvido para a URL do componente remoto se você estiver usando o assistente Publicar no Visual Studio. Se você não usar o assistente (ou se usar, mas estiver publicando o componente remoto no Azure), é necessário substituir manualmente o token pelo valor de Domínio de suplemento usado ao registrar o suplemento. Ele deve ser exatamente o mesmo valor, incluindo o número da porta, se houver, com a diferença de que você deve incluir o protocolo HTTPS também. Apresentamos um exemplo a seguir.

   <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   

5. Considere usar para o elemento Title no arquivo AppManifest.xml o mesmo valor para o campo Título em AppRegNew.aspx. O valor do elemento Title é o nome do suplemento que os usuários visualizarão após a sua instalação. Se o suplemento tiver nomes diferentes na caixa de diálogo de consentimento e na interface do usuário do SharePoint, os usuários poderão ficar confusos.

   O exemplo a seguir mostra esses valores no manifesto de suplemento.

   <Properties>
     <Title>Contoso photo printing app</Title>
     <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
   </Properties>
   

Usar a URL de redirecionamento em um suplemento que solicita permissões dinamicamente

Se o seu aplicativo Web é iniciado fora do SharePoint (e, portanto, não é um suplemento do SharePoint verdadeiro), ele precisa ser projetado para solicitar permissões do SharePoint em tempo de execução. Ele deve ter um código que usa o URI de redirecionamento, juntamente com outras informações, para obter um token de acesso do ACS. Localize o local em que esse URI está definido e use o valor exato que você usou para o campo URI de redirecionamento no AppRegNew.aspx ou no Painel do Vendedor. O local pode ser um arquivo de código ou um arquivo de configuração.

Recuperar informações sobre registros de suplemento e entidades de segurança de suplemento

Você pode recuperar informações sobre o registro de suplementos e as entidades de segurança de suplementos para os suplementos que instalou ou registrou no SharePoint.

Para pesquisar informações sobre o registro de um suplemento que você registrou, acesse http://<SharePointWebsite>/_layouts/15/AppInv.aspx.

Para fazer uma pesquisa, você precisa se lembrar da ID do cliente (também conhecida como a ID do suplemento) que foi usada para registrar o suplemento. A pesquisa retorna as seguintes informações para uma ID de cliente específica:

• Título
• Domínio do suplemento
• URL de redirecionamento (equivale ao URI de redirecionamento)

A pesquisa não retorna o valor do segredo do suplemento.

Para ver uma lista de entidades de segurança de suplemento registradas, acesse: http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx.

Confira também

• Três sistemas de autorização para Suplementos do SharePoint
• Introdução à criação de suplementos do SharePoint hospedados pelo provedor
• Autorização e autenticação de Suplementos do SharePoint