Ir para o conteúdo

Links de entrada no Jitterbit App Builder

Introdução

Os desenvolvedores podem precisar vincular o App Builder a fontes externas, como as seguintes:

  • Outros aplicativos
  • Mensagens de email
  • Portais
  • iframes

Esses links podem direcionar o usuário para o aplicativo padrão ou para um aplicativo específico. Eles podem permitir que o usuário escolha como se autenticar ou iniciar o processo de login com um provedor de segurança específico. O desenvolvedor pode controlar esses comportamentos construindo os links de forma apropriada.

Normalmente, ao vincular ao App Builder, os desenvolvedores construirão uma URL para o diretório raiz do App Builder. A URL pode parecer algo assim:

https://example.com/Vinyl/

Este link assume que o App Builder está hospedado em um diretório Vinyl abaixo do diretório raiz do site. Em muitos casos, o App Builder estará hospedado na raiz do site.

Quando um usuário segue um link desse tipo, o App Builder redirecionará o navegador para o formulário de login. No entanto, se um provedor de autenticação externo foi configurado como o Provedor de Autenticação Padrão, o App Builder ignorará o formulário de login, redirecionando o navegador para o provedor de autenticação externo.

Independentemente disso, uma vez que o usuário tenha feito login com sucesso, o App Builder determinará o aplicativo padrão apropriado com base nos privilégios do usuário. O App Builder então redirecionará o navegador para a página inicial do aplicativo.

Um "link profundo" é uma URL que aponta para um aplicativo ou página específica. Um exemplo de um link profundo pode parecer algo assim:

https://example.com/Vinyl/app/Sales/Leads

Neste exemplo, Sales corresponde ao nome do aplicativo; Leads, ao nome da página. Observe que estes estão codificados em URL conforme o RFC 3986, seção 2 (https://tools.ietf.org/html/rfc3986#section-2).

O App Builder suporta links profundos. Especificamente, os desenvolvedores podem construir links que apontam para um aplicativo ou página específica dentro do App Builder. Assim como os links de nível superior que apontam para a raiz do site, o App Builder determinará automaticamente se o usuário precisa se autenticar, redirecionando o navegador para o formulário de login ou provedor de autenticação externo. Uma vez que o usuário tenha feito login com sucesso, o App Builder redirecionará o navegador para a URL do link profundo.

A maneira mais simples de construir um link profundo é navegar até a página de destino. A barra de endereços do navegador conterá uma URL que se parece com isto:

https://example.com/Vinyl/app/Sales/Leads?$activepanel=Leads&Leads.LeadId=123456

A parte da URL que começa com o ponto de interrogação (?) é a string de consulta. O App Builder usa a string de consulta para rastrear painéis e linhas selecionados, critérios de filtragem e pesquisa, etc. Remova a string de consulta para construir a URL canônica para a página.

String de consulta usada na URL

Ao construir a URL exata da página, o App Builder faz o que é necessário para manter todo o contexto da sua sessão. Em geral, existem diferentes componentes de uma determinada página do App Builder que podem acabar incluídos como parte da URL da string de consulta. Os componentes que acabam na URL podem incluir: Chaves Primárias, Nome da Página, Nome do Painel e Nome do Controle.

Dicas para encurtar a URL

Existem casos em que o App Builder gera uma URL muito longa para Páginas. Nesta seção, forneceremos algumas dicas gerais a serem consideradas para ajudar a encurtar a URL.

  • Defina suas Chaves Primárias. O App Builder usará na URL o que considera como PKs para acompanhar os registros selecionados, e às vezes o App Builder usará todas ou a maioria das colunas se deixadas implícitas na regra. Por essa razão, sempre certifique-se de encontrar as colunas únicas reais necessárias para identificar seu registro.

    • Se você decidir usar uma string mais longa como sua Chave Primária, saiba que isso ocupará mais espaço na URL.

  • Mantenha seus Nomes curtos para Página, Painéis e Controles. Se você precisar que eles sejam exibidos como valores de nome mais longos, use o campo Rótulo (que não será incluído como parte da URL da consulta).

Além das dicas listadas, as configurações do IIS podem valer a pena serem revisadas pelo seu Administrador de Sistema. O IIS impõe algumas limitações no comprimento da URL por padrão, e algumas configurações são configuráveis para permitir URLs mais longas. As configurações a serem revisadas incluem:

  • maxAllowedContentLength: Tamanho máximo de upload de arquivo. O padrão é 30000000.
  • maxUrl: Comprimento máximo da URL. O padrão é 4096.
  • maxQueryString: Comprimento máximo da string de consulta da URL. O padrão é 2048.

Veja o artigo da Microsoft sobre Limites de Solicitação <requestLimits> para mais informações.

Aviso

Alterar o nome de um aplicativo ou página quebrará links profundos existentes.

Autenticação

Como mencionado acima, o App Builder redirecionará automaticamente usuários anônimos para o formulário de login ou para um provedor de autenticação externo. Na maioria dos cenários, esse é o comportamento desejado. No entanto, pode haver situações que exigem que o usuário faça login com um provedor de segurança específico. Exemplos incluem:

  • O link profundo aponta para uma página que requer uma autorização específica. Por exemplo, a página de destino pode exibir dados recuperados do Salesforce. Nesse caso, o usuário precisará se autenticar no Salesforce antes de acessar a página.
  • O usuário já se autenticou com um provedor de autenticação de único sinal (SSO). Por exemplo, o usuário pode seguir um link dentro de um portal. Para acessar o portal, o usuário fez login com os Serviços de Federação do Active Directory (ADFS). Supondo que o App Builder também esteja configurado para autenticar usuários via ADFS, o usuário pode efetivamente contornar o formulário de login ao seguir o link.

URLs de Desafio

Para forçar os usuários a se autenticarem com um provedor de segurança específico, o link deve ser construído de tal forma que acione um desafio. O seguinte exemplo demonstra um desafio para um provedor de autenticação específico:

Chamaremos isso de URL de desafio. A URL de desafio é construída da seguinte forma:

<vinyl-root>/service/authentication/external?provider=<provider-name>&returnUrl=<response-url>

Onde:

  • <vinyl-root>: Esta é a URL absoluta para o diretório raiz da aplicação web do App Builder. Não inclui a barra final. Neste exemplo, vinyl-root é https://example.com/Vinyl.
  • <provider-name>: Este é o nome do provedor de segurança conforme definido dentro do App Builder. No exemplo acima, provider-name é SAML. Observe que provider-name deve ser codificado em URL.
  • <response-url>: Esta é a URL de callback da aplicação web do App Builder. Não é o link profundo. A response-url precisa ser codificada em URL.

No exemplo acima, decodificar a response-url produz:

https://example.com/Vinyl/auth/authenticated?returnUrl=%2Fapp%2FSales%2FLeads

A response-url é composta pelos seguintes elementos:

<vinyl-root>/auth/authenticated/?returnUrl=<relative-link>

Onde:

  • <vinyl-root>: URL absoluta da raiz da aplicação web App Builder (veja acima).
  • <relative-link>: Esta é a parte relativa à raiz da aplicação web App Builder do link profundo. Está codificada em URL.

No exemplo acima, o relative-link é o seguinte:

%2Fapp%2FSales%2FLeads

Decodificando o relative-link, obtemos:

/app/Sales/Leads

Como mencionado acima, isso é relativo ao diretório raiz da aplicação web App Builder (vinyl-root neste exemplo).

Construindo uma URL de desafio

Para construir uma URL de desafio, precisamos reverter o processo:

  1. Comece com o link profundo e remova vinyl-root para obter relative-link. Deve começar com /app. Codifique em URL o relative-link.

  2. Construa a response-url a partir do seguinte:

    <vinyl-root>/auth/authenticated/?returnUrl=<relative-link>

    Codifique em URL a response-url.

  3. Construa a challenge-url a partir do seguinte:

    <vinyl-root>/service/authentication/external?provider=<provider-name>&returnUrl=<response-url>

Fiddle para gerar a URL de desafio

O seguinte JSFiddle pode ser usado para gerar uma URL de desafio:

https://jsfiddle.net/8s8gkufh/1/

HTML

Link:<br>
<input data-bind="value: link"><br>
Provider<br>
<input data-bind="value: provider"><br>
Challenge URL:
<input data-bind="value: challenge" readonly>

JavaScript

function ViewModel() {
  this.link = ko.observable("http://example.com/Vinyl/app/Northwind");
  this.provider = ko.observable("SAML");

  var startOfRelativeLink = ko.computed(function() {
    return this.link().indexOf("/app");
  }, this);

  var root = ko.computed(function() {
    return this.link().substr(0, startOfRelativeLink());
  }, this);

  var relativeLink = ko.computed(function() {
    return this.link().substr(startOfRelativeLink());
  }, this);

  var response = ko.computed(function() {
    return root() + "/auth/authenticated?returnUrl=" + encodeURIComponent(relativeLink());
  }, this);

  this.challenge = ko.computed(function() {
    return root() + "/service/authentication/external?provider=" + encodeURIComponent(this.provider()) + "&returnUrl=" + encodeURIComponent(response());
  }, this);
}

ko.applyBindings(new ViewModel());