Recursos
Guias
Referências
Exemplos
Documentação API
Registo de aplicações
ProgrammableWeb
Postman
Videos
Jasmin Recursos
Recursos
Recursos
Recursos
Nesta área encontra informações sobre a tecnologia de integração Jasmin, bem como guias de ajuda com exemplos simples e práticos sobre como iniciar o desenvolvimento de uma solução. Também encontra informações sobre todos os aspetos da Web API necessários ao desenvolvimento de aplicações, desde tópicos de referência até funcionalidades mais avançadas.
Jasmin Documentação API
Documentação API
Documentação API
Jasmin Documentação API
Documentação API
Documentação API
DOCUMENTAÇÃO API

API

O Jasmin disponibiliza uma Web API REST que lhe permite aceder aos dados de uma subscrição. Esta API cobre todos os módulos do produtos (Vendas, Compras, Impostos, etc.) e permite tanto a consulta de dados como a criação e atualização de entidades e transações (documentos). Deste modo é possível criar soluções que integrem o Jasmin com qualquer outro sistema.

Ver mais

Jasmin Registo de aplicações
Registo de aplicações
Registo de aplicações
Jasmin Registo de aplicações
Registo de aplicações
Registo de aplicações
REGISTO DE APLICAÇÕES

O sistema de autenticação de utilizadores e de segurança do Jasmin requer que todas as aplicações integradas sejam registadas no sistema. Essa informação é utilizada no acesso à Web API para assegurar o acesso aos dados da subscrição de um determinado cliente.O registo da aplicação permite ao developer ter acesso ao token de autorização que deve ser utilizado em todas as chamadas à Web API.Pode registar uma nova aplicação ou aceder aos registos já efetuados na área de gestão de aplicações, seguindo o seguinte link:

Ver mais

Jasmin ProgrammableWeb
ProgrammableWeb
ProgrammableWeb
Jasmin ProgrammableWeb
ProgrammableWeb
ProgrammableWeb
PROGRAMMABLEWEB

O ProgrammableWeb é uma plataforma que permite acompanhar todas as novidades e informações sobre a Web API do Jasmin.

Ver mais

Jasmin Postman
Postman
Postman
Jasmin Postman
Postman
Postman
POSTMAN

COMPRAS E VENDAS

Nesta coleção vais encontrar exemplos de utilização da WebAPI para as áreas de compras e vendas.

EXPEDIÇÃO E INVENTÁRIO

Nesta coleção vais encontrar exemplos de utilização da WebAPI para as áreas de inventário e expedição de mercadoria.

IMPOSTOS E FINANÇAS

Nesta coleção vais encontrar exemplos de utilização da WebAPI para as áreas de pagamentos, recebimentos e impostos.

PLATAFORMA E ENTIDADES BASE

Nesta coleção vais encontrar exemplos de utilização da WebAPI para a área de plataforma.

Jasmin Videos
Videos
Videos
Jasmin Videos
Videos
Videos
Vídeos
Jasmin RecursosReferências
RecursosReferências
Referências
Voltar | Lista de artigos
Como funciona a autorização OAuth 2.0?

O OAuth 2.0 é um protocolo standard de autorização que permite que aplicações acedam de forma limitada à conta de um utilizador num serviço Web (HTTP), como a Web API Jasmin.

O protocolo delega a autenticação do utilizador ao serviço que detém a conta do utilizador e autoriza o acesso de aplicações externas a essa conta do utilizador. O protocolo disponibiliza fluxos de autorização para aplicações Web, aplicações desktop e aplicações mobile.

De seguida descreve-se o funcionamento básico do protocolo na perspetiva do developer de uma aplicação.

OAuth Roles

O protocolo define 4 roles (papéis):

  • Resource owner: trata-se do utilizador que autoriza o acesso da aplicação à sua conta. Esse acesso fica limitado ao scope da autorização dada pelo utilizador.
  • Client: é a aplicação que pretende aceder à conta do utilizador.
  • Resource server: corresponde ao servidor que hospeda as contas do utilizador.
  • Authorization server: é o servidor que verifica a identidade do utilizador e atribui tokens de autorização ao cliente (a aplicação).

Do ponto de vista do developer de uma aplicação, a Web API que pretende consumir cumpre tanto o papel de resource server como o papel de authorization server. Por isso é comum combinarem-se os dois papéis e chamar-lhe de Service (serviço) ou simplesmente API.

Fluxo genérico de autorização

Tipicamente o fluxo de autorização de uma aplicação externa seguirá os seguintes passos:

  1. A aplicação solicita autorização para aceder aos recursos do utilizador.
  2. Se o utilizador já autorizou esse pedido, a aplicação recebe um authorization grant.
  3. A aplicação solicita ao authorization server um access token, apresentando a identidade do utilizador e o authorization grant.
  4. Se a identidade da aplicação estiver autenticada e o authorization grant for válido, o authorization server atribuirá um acess token à aplicação e o fluxo de autorização termina.
  5. A aplicação solicita um determinado recurso ao resource server e apresenta o access token que obteve antes.
  6. Se o access token for válido, o resource server devolverá o recurso solicitado à aplicação.

Na realidade o fluxo real de autenticação depende do tipo de authorization grant que for utilizado, no entanto, este é fluxo conceptual normal do OAuth. Adiante discutem-se os vários authorization grants disponíveis.

Registo da aplicação

Antes de uma aplicação poder utilizador o protocolo, ela deve primeiro registar-se junto do serviço. Tipicamente esse registo é feito numa área para developers no Web site da API (como acontece para a Web API Jasmin).

O registo inclui as seguintes informações necessárias ao funcionamento do protocolo:

  • O nome da aplicação.
  • O Web site da aplicação.
  • O URL de redirect (ou callback).

O serviço reenviará o utilizador para este último URL depois de autorizar (ou negar) o acesso da aplicação. Portanto, esse URL deve responder pela parte da aplicação que trate dos códigos de autorização e dos access tokens.

Client ID e Client Secret

Depois de registada junto do serviço, a aplicação receberá deste as credenciais de cliente, compostas por um Client ID e um Client Secret.

Client ID é uma string visível publicamente que o serviço utilizará para identificar a aplicação. Esse ID será utilizado também nos URL de autorização apresentados ao utilizador.

Client Secret é utilizado pelo serviço para autenticar a identidade da aplicação sempre que esta solicitar acesso à conta do utilizador. Devem manter-se absolutamente privado entre a aplicação e o serviço.

Authorization grant

O tipo de grant utilizado depende do método de autorização que aplicação pretender utilizar e, claro, dos métodos que a Web API suportar. Existem 4 tipos diferentes definidos no protocolo, com utilidades diferentes:

  • Authorization code: usado em aplicações server-side.
  • Implicit: usado por aplicações Web e por aplicações mobile (as que correm no dispositivo do utilizador).
  • Resource owner password credentials: usado por trusted applications, tipicamente, as aplicações que são geridas pelo próprio serviço.
  • Client credentials: utilizado para acesso por parte de APIs de outras aplicações.

Authorization code grant

Este é o tipo mais comum porque está otimizado para aplicações server-side, onde o código fonte da aplicação não está exposto e é mais fácil manter a confidencialidade do client secret.

Trata-se de um fluxo baseado em redirects, o que significa que a aplicação deve ser capaz de interagir com o agente do utilizador (o browser por exemplo) e de receber os códigos de autorização reencaminhados através desse agente.

Passo 1 – Authorization code link

Em primeiro lugar o utilizador é um link semelhante ao seguinte:

https://myserver.com/v1/oauth/authorize?response_type=code&client_id={ClientId}&redirect_uri={CallbackUrl}&scope={Scope}

Os componentes deste link são os seguintes:

  • https://myserver.com/v1/oauth/authorize: é o endpoint de autorização da API.
  • {ClientId}: identifica a aplicação.
  • {CallbackUrl}: o URL para onde o serviço deve redirecionar o utilizador depois de atribuído um authorization grant.
  • response_type=code: indica que a aplicação está a solicitar um authorization code grant.
  • {Scope}: define o nível de acesso que a aplicação está a solicitar.

Passo 2 – Autorização por parte do utilizador

Quando o utilizador abre o link anterior deve, em primeiro lugar, autenticar-se junto do serviço. Em seguida ser-lhe-á solicitado que autorize (ou negue) a aplicação a aceder ao scope solicitado. Tipicamente este passo é realizado por um formulário muito simples que descreve o que a aplicação está a pedir e deixa o utilizador escolher entre aceitar ou rejeitar esse acesso.

Passo 3 – A aplicação recebe o authorization code

Depois da autorização do utilizador (passo anterior), o serviço redireciona o agente do utilizador (o browser) para o redirect URL especificado no registo da aplicação, enviando também um authorization code.

Normalmente, a forma do URL de redirect será semelhante à seguinte:

https://myapplication.com/callback?code={AuthorizationCode}

Passo 4 – A aplicação solicita um acess token

De seguida a aplicação solicita à API um access token, passando-lhe o authorization code anterior e detalhes de autenticação, incluindo o client secret.

O post será semelhante ao seguinte:

https://myserver.com/v1/oauth/token?client_id={ClientId}&client_secret={ClientSecret}&grant_type=authorization_code&code={AuthorizationCode}&redirect_uri={CallbackUrl}

Passo 5 – A aplicação recebe o acess token

Se a autorização for válida, a API responderá com uma mensagem que conterá o access token. A resposta pode ser semelhante à seguinte:

{
    "access_token":"{AccessToken}",
    "token_type":"bearer",
    "expires_in":2592000,
    "refresh_token":"{RefreshToken}",
    "scope":"{Scope}",
    "uid":100101,
    "info":{"name":"{UserName}","email":"{UserEmail}"}
}

Implicit grant

Este tipo de grant é usado tipicamente em aplicações mobile e em aplicações Web (as que correm no browser), sempre quando a confidencialidade do client secret não pode ser garantida.

Também é um fluxo baseado em redirects, ainda que o access token seja dado ao agente do utilizador para este o reenviar à aplicação, o que torna esse token mais vulnerável por poder estar exposto ao utilizador e/ou a outras aplicações do dispositivo do utilizador.

Além disso, a identidade da aplicação não é autenticada, confiando o serviço no URL de redirect especificado no momento do registo da aplicação.

O comportamento normal do fluxo é o seguinte: é solicitado ao utilizador que autorize a aplicação, depois o servidor de autenticação passa o access token ao browser do utilizador que depois o passa à aplicação.

Passo 1 – Link de autorização

Em primeiro lugar é apresentado ao utilizador um link para a autorização que solicita um token da API:

https://myserver.com/v1/oauth/authorize?response_type=token&client_id={ClientId}&redirect_uri={CallbackUrl}&scope={Scope}

Este link é essencialmente idêntica ao authorization code link (ver grant anterior), exceto pelo facto de que solicita um “token” em vez de um “code”.

Passo 2 – Autorização por parte do utilizador

Quando o utilizador abre o link anterior deve, em primeiro lugar, autenticar-se junto do serviço. Em seguida ser-lhe-á solicitado que autorize (ou negue) a aplicação a aceder ao scope solicitado. Tipicamente este passo é realizado por um formulário muito simples que descreve o que a aplicação está a pedir e deixa o utilizador escolher entre aceitar ou rejeitar esse acesso.

Passo 3 – O agente do utilizador recebe o access token com o URL de redirect

Depois da autorização do utilizador, o serviço redirecionará o browser para o URL de redirect da aplicação e incluirá no URL o access token atribuído:

https://myapplication.com/callback#token={AccessToken}

Passo 4 – O agente segue o URL de redirect

O browser seguirá esse URL, armazenando antes o access token.

Passo 5 – A aplicação envia o script para extrair o access token

A aplicação devolverá então no URL uma página Web que deve incluir uma script para extrair o access token do URL.

Passo 6 – O access token é passado à aplicação

Finalmente, o browser executará a script da página para extrair o access token e passá-lo então à aplicação.

Neste momento a aplicação estará autorizada.

Resource owner password credentials grant

Este tipo de grant requer que o utilizador disponibilize as suas credenciais de acesso ao serviço (username e password) diretamente à aplicação, que as utilizará para obter o access token.

Por motivos óbvios, trata-se de um tipo de grant que só deve ser disponibilizado pelo servidor de autorização se não for viável nenhum dos outros tipos.

O seu funcionamento é o seguinte.

Depois do utilizador fornecer as credenciais à aplicação, esta solicitará o access token ao servidor de autorização. O pedido (POST) terá uma forma semelhante à seguinte:

https://myserver.com/v1/oauth/token?grant_type=password&username={UserName}&password={Password}&client_id={ClientId}

Quando as credenciais estiverem corretas, o servidor retornará o access token à aplicação e esta estará autorizada.

Client credentials grant

Este tipo de grant fornece uma forma à aplicação de aceder à sua própria conta de serviço. O que será útil, por exemplo, quando a aplicação pretender atualizar o seu registo ou aceder aos dados da sua própria conta de serviço usando a API.

O fluxo é o seguinte.

A aplicação solicita um access token fornecendo as suas credenciais, o seu client id e o client secret ao servidor de autorização. O request poderá ter a seguinte forma:

https://myserver.com/v1/oauth/token?grant_type=client_credentials&client_id={ClientId}&client_secret={ClientSecret}

Se as credenciais estiverem corretas, o servidor retornará o access token e a aplicação estará então autorizada.

Refresh Token

Quando um access token expira, a sua utilização para fazer pedidos à API resultará num erro “Invalid Token Error”. Nesse momento, se um refresh token tiver sido incluído no momento em que o access token foi gerado, pode ser utilizado para fazer um novo token de acesso ao servidor.

Eis um exemplo de um pedido desse tipo:

https://myserver.com/v1/oauth/token?grant_type=refresh_token&client_id={ClientId}&client_secret={ClientSecret}&refresh_token={RefreshToken}

Mais informação

Guardar ou partilhar este artigo
Artigos Relacionados
Gestão das aplicações integradas Exemplos de Integrações Boas práticas de integração Como executar queries OData sobre os dados? Getting Started
Últimos Artigos Vistos