Integrar Cloud incorporado sem expor credenciais

O problema: incorporar não é entregar credenciais

Integrar gestor de ficheiros com iframe e API costuma começar com uma necessidade simples: mostrar ficheiros, pastas, transformações ou descarregamentos dentro de um produto existente. O erro habitual é assumir que, se a interface aparece no navegador, as chaves que permitem operar sobre o Cloud também devem viajar para o navegador. Essa mistura quebra a separação básica entre experiência de utilizador e autoridade de execução. O iframe deve servir para apresentar uma sessão controlada; a API REST deve ser usada a partir do servidor quando for necessário gerir recursos, utilizadores, configuração ou trabalhos de transformação.

A Apification oferece três modalidades principais para este cenário: API REST, webhooks assinados e Cloud incorporado. O Cloud incorporado integra-se através de uma sessão controlada e personalizada, com sessões iframe assinadas, temas e permissões efetivas, e comunicação JavaScript com o host. Isto não equivale a replicar todo o armazenamento nem a expor rotas internas. Também não deve ser confundido com uma sincronização contínua de fontes externas: quando Google Drive, OneDrive ou Dropbox atuam como fontes, a importação copia ficheiros selecionados para o Cloud da Apification.

• Não coloques chaves API no JavaScript do cliente.
• Não transformes um iframe num proxy sem regras de negócio.
• Não trates a incorporação como uma cópia total do armazenamento externo.

Mapa de responsabilidades: frontend, backend e Cloud

O frontend deve tratar da experiência: abrir a área incorporada, reagir a eventos permitidos, mostrar estados e pedir ações ao backend. Um iframe, segundo a definição geral da plataforma web, é um contexto de navegação aninhado que incorpora outra página dentro da atual. Cada iframe tem o seu próprio documento e navegação, e consome memória e recursos adicionais, por isso convém usá-lo quando oferece uma experiência completa e não como mecanismo indiscriminado para cada operação mínima.

O backend deve guardar credenciais, aplicar as regras próprias do produto e chamar a API REST da Apification de forma servidor a servidor. A integração REST contempla chaves API com scopes, operações de escrita idempotentes e trabalhos assíncronos do File Transformer. O Apification Cloud, por sua vez, mantém o espaço de trabalho organizado e versionado, os recursos partilháveis, as permissões, os utilizadores, grupos, funções e visibilidade que controlam quem pode consultar ou modificar cada elemento.

• Frontend: interface, iframe, mensagens JavaScript limitadas e visualização de estado.
• Backend: autenticação própria, autorização, scopes, idempotência e chamadas REST.
• Apification Cloud: ficheiros, serviços, permissões efetivas, versões e resultados transformados.

Quando usar iframe, JavaScript, REST API ou OpenAPI

Usa o Cloud incorporado quando quiseres que o utilizador navegue por uma experiência de gestão de ficheiros dentro do teu produto sem reconstruir toda a interface. A Apification permite sessões iframe assinadas com acesso temporário, e o servidor resolve o tema e as permissões efetivas antes de abrir o Cloud. Isto encaixa em portais de cliente, painéis de SaaS e backoffices onde o utilizador deve ver uma parte controlada do workspace, descarregar originais ou transformados, ou trabalhar dentro de uma experiência visual coerente com o produto anfitrião.

Usa a API REST quando a ação tiver consequências de negócio ou deva ser executada com regras do servidor: criar um trabalho de transformação, gerir recursos Cloud, aplicar configuração ou coordenar utilizadores. Usa JavaScript apenas para comunicação limitada entre a página host e o iframe, não para executar autoridade sensível. Usa o contrato OpenAPI 3.1 descarregável para alinhar esquemas de pedido e resposta, gerar clientes internos ou validar integrações, lembrando que as credenciais com scopes continuam a pertencer ao servidor.

• Iframe: melhor para uma experiência completa e controlada do Cloud.
• JavaScript: útil para coordenação de interface, não para segredos.
• REST API: adequada para automação, regras de backend e trabalhos.
• OpenAPI: útil para contrato técnico, tipos, testes e revisão de alterações.

Padrão recomendado: backend como mediador

O padrão operacional mais robusto começa com um pedido do utilizador à tua aplicação. O backend valida a sessão própria, verifica o que esse utilizador pode fazer segundo o teu modelo de negócio e decide se corresponde abrir o Cloud incorporado ou executar uma ação via API. Se o Cloud for aberto, o servidor prepara uma sessão assinada e temporária, com o tema e as permissões efetivas resolvidos antes de entregar a experiência ao navegador. O cliente recebe o necessário para mostrar o iframe, não uma credencial reutilizável.

Para operações de escrita ou transformação, o backend usa uma credencial com scopes e concede apenas as permissões de leitura e escrita necessárias. Quando a ação puder repetir-se por novas tentativas do navegador ou problemas de rede, usa operações idempotentes para evitar duplicados. Em fluxos pesados, como importações, transformações ou renders, a Apification pode processar trabalhos em segundo plano. A sequência recomendada fica clara: credencial com scopes, pedido idempotente, trabalho assíncrono, evento assinado e resultado autenticado.

• Valida o utilizador no teu backend antes de criar uma sessão incorporada.
• Mapeia permissões de negócio para permissões efetivas do Cloud.
• Usa scopes mínimos para a credencial do servidor.
• Desenha as escritas para tolerar novas tentativas sem duplicar ações.

Permissões, temas e restrições sem ampliar acesso

A segurança de uma integração incorporada depende menos do iframe em si e mais de como as permissões são resolvidas antes de o abrir. A Apification usa utilizadores, grupos, funções e visibilidade como controlos para decidir quem pode consultar ou modificar cada elemento. Numa integração, esses controlos devem alinhar-se com o teu produto: se um cliente só pode ver um projeto, a sessão incorporada não deve permitir-lhe navegar para recursos de outro cliente, mesmo que conheça um identificador ou manipule parâmetros no URL.

O tema visual também deve ser resolvido a partir do servidor quando se prepara a sessão incorporada, porque faz parte da experiência controlada. Do lado do navegador, considera os atributos padrão de iframe como parte da defesa de interface: allow define uma Permissions Policy para funções disponíveis segundo a origem, e sandbox pode impor restrições ao conteúdo incorporado. A recomendação geral é não confiar no cliente como fonte de permissões, e ter cuidado com combinações de sandbox que anulem o seu valor de segurança em cenários de mesma origem.

• Verifica utilizador, grupo, função e visibilidade antes de abrir ou executar ações.
• Não aceites permissões, tema ou âmbito final apenas a partir de parâmetros do cliente.
• Restringe as funções do iframe ao necessário para a experiência.
• Revê se os descarregamentos de originais ou transformados pertencem ao utilizador correto.

Fluxos de exemplo: seletor, transformação e descarga

Um fluxo de seletor incorporado pode funcionar assim: o utilizador entra no teu portal, seleciona um projeto e clica em “abrir ficheiros”. O teu backend valida que esse utilizador pertence ao projeto e solicita uma sessão incorporada com permissões efetivas adequadas. O frontend insere o iframe e, através de comunicação JavaScript limitada com o host, pode receber um sinal de seleção ou fecho. A ação posterior não deve basear-se cegamente num ID enviado pelo navegador; o backend deve verificar se o elemento selecionado pertence ao âmbito permitido.

Um fluxo de transformação segue outra lógica. O utilizador solicita converter, dividir, unir, otimizar ou processar um documento, imagem, vídeo, áudio ou dado através de uma ação do teu produto. O backend valida proprietário e permissão, chama a API REST para criar o trabalho assíncrono do File Transformer e regista um estado interno como “em curso”. Quando o resultado estiver disponível, o utilizador deve aceder através de um resultado autenticado, não por rotas internas de armazenamento. Se o ficheiro original mudar, o histórico de elementos e versões do Cloud ajuda a conservar uma fonte organizada.

• Seletor: sessão incorporada, seleção limitada e validação posterior no backend.
• Transformação: permissão, trabalho assíncrono, estado visível e resultado autenticado.
• Descarga: original ou transformado apenas para o utilizador ou grupo autorizado.

Webhooks e ações assíncronas sem duplicados

Os webhooks da Apification permitem reagir a eventos relevantes sem consultar continuamente recursos ou trabalhos em segundo plano. Incluem payloads assinados com HMAC, histórico de entregas, novas tentativas e eventos de transformação concluída. Para os usar bem, precisas de um endpoint HTTPS acessível e estável. Esse endpoint não deve limitar-se a aceitar qualquer carga: deve validar a assinatura, registar o evento recebido e relacioná-lo com o trabalho ou recurso que o teu backend criou previamente.

Como há novas tentativas, o teu recetor deve ser idempotente. Na prática, regista uma chave de entrega ou uma referência do evento e evita que uma mesma transformação concluída dispare duas vezes a mesma ação de negócio. Também convém separar o estado técnico do estado visível: “recebido”, “a processar”, “concluído” ou “falhado” nos teus registos internos; “o teu ficheiro está a ser preparado” ou “não foi possível concluir a transformação” na interface. Assim, o utilizador entende o progresso sem ver detalhes internos nem rotas de armazenamento.

• Exige HTTPS estável para o endpoint de webhook.
• Valida HMAC antes de confiar no payload.
• Guarda histórico de entregas e resultado de processamento.
• Faz com que o manipulador seja idempotente perante novas tentativas.

Casos de falha e checklist antes de produção

As falhas mais perigosas aparecem quando a equipa tenta simplificar a integração saltando o backend. Uma chave API em JavaScript pode ser extraída do cliente. Um proxy genérico que reenvia qualquer operação para a API pode ampliar permissões sem querer. Um endpoint que confia em IDs enviados pelo navegador cai em problemas de autorização ao nível do objeto: o utilizador altera um identificador e acede a um recurso alheio. A mesma lógica aplica-se a propriedades: nem todo o campo que chega do cliente deve ser aceite como editável.

Também há falhas operacionais. Se não registares trabalhos em curso, erros de integração ou transformações falhadas, o utilizador vê apenas silêncio. Se não limitares ações pesadas, podes facilitar um consumo de recursos não previsto. Se não distinguires incorporação de importação a partir de fontes externas, podes prometer uma sincronização que não corresponde. Antes de produção, revê se o teu backend é a única peça com credenciais, se cada ação valida proprietário e permissão, e se originais e resultados transformados mantêm uma única fonte de verdade no Cloud.

• Credenciais: nenhuma chave API no navegador.
• Autorização: validar objeto, proprietário, grupo, função e visibilidade no backend.
• Scopes: conceder apenas a leitura e a escrita necessárias.
• Proxy: permitir apenas operações previstas pelo teu produto.
• Assincronia: registar trabalhos, webhooks, novas tentativas e erros visíveis para suporte.
• Recursos: controlar ações pesadas e evitar execuções duplicadas.
• Mensagens ao utilizador: mostrar estados compreensíveis sem expor detalhes internos.

Perguntas frequentes