OAuth2

OAuth2 é um padrão de autenticação amplamente utilizado, que permite que sua aplicação não manipule diretamente nomes de usuários e senhas.

Empresas como Google, Facebook e Twitter já utilizam esse padrão para prover o acesso à seus recursos de forma segura à aplicações de terceiros.

No Marketplace, esse padrão foi implementado com a intenção de automatizar o processo de obtenção de tokens de acesso à API V2 de produção.

Se você está desenvolvendo uma integração de APIs que já passou pelo processo de homologação, então é hora de iniciar o processo de integração OAuth2. Abaixo você confere os passos necessários para conclusão do processo.

  • 1

    Cadastro da APP

    No cadastro da APP estão alguma informações essenciais para utilização do OAuth2.

    Logo no cadastro, será solicitado o preenchimento do campo Redirect URL. É por esse campo que o processo fará a a devolução do Grant Code, que falaremos no tópico seguinte.

    Se você ainda não sabe qual valor preencher para esse campo, pode deixá-lo vazio. Seu uso será melhor detalhado nos próximos passos.

     

    Agora que sua aplicação foi criada, repare que na lista de APPs existem duas colunas chamadas CLIENT ID e CLIENT SECRET. Essas informações serão utilizadas a seguir.


  • 2

    Solicitação do Grant Code

    Essa é a primeira interação que sua aplicação fará para obtenção do token de acesso.

    O Grant Code é um código intermediário emitido pelo Marketplace que garante que o usuário interessado na obtenção do Access Token passou pelo processo de autenticação com sucesso.

    Vamos começar fazendo a chamada para a URL abaixo.

     
    GET
    https://lojista.ehub.com.br/oauth-api/authorize?client_id=[Valor da coluna Client ID]&redirect_url=[URL para recebimento do Grant Code]
        

    Sobre os parâmetros esperados para essa requisição:

    client_id: Parâmetro obrigatório. Representa o valor gerado automaticamente e exibido na coluna Client ID, após o cadastro da APP

    redirect_url:Parâmetro opcional. Recebe a URL onde o grant code será disponibilizado. Você só precisa informar esse campo caso não tenha feito a configuração durante o cadastro da APP ou se desejar sobrescrever a configuração atual.

    O resultado deve ser uma tela de autenticação, disponibilizada pela Via Varejo, onde são esperadas as informações de usuário e senha já utilizadas no Admin do Lojista para gerenciamento de seus produtos e pedidos no Marketplace.

    Uma vez que a autenticação ocorra com sucesso, será enviada uma resposta para redirecionamento imediato à URL configurada na APP ou informada no campo redirect_url, como sujere o exemplo:

    http://urldeexemplo.com.br/callback?code=34k4a6h

    É muito importante destacar que essa informação será obtida no cabeçalho e, não no corpo da resposta.

    Observe o retorno do parâmetro code na URL retornada. Esse parâmetro corresponde ao Grant Code e, pode ser utilizado, finalmente, para obtenção do Access Token de produção.

  • 3

    Obtenção do Access Token

    Agora que você já o conseguiu obter o Grant Code, é hora de trocá-lo pelo Access Token, que permitirá o acesso às APIs de produção do Marketplace.

    Para isso, basta fazer o post das informações para a URL abaixo:

     
    POST
        https://api.cnova.com/oauth/access_token
    
    HEADER
        Content-Type: application/json
        Authorization: Basic base64(client_id:client_secret)
    
    REQUEST BODY
    {
        // Deve ser passado o mesmo grant_code que foi obtido
        "code": "34k4a6h",
        "grant_type": "authorization_code"
    }
    
    RESPONSE BODY
    {
        // O access_token gerado deve ser armazenado para ser utilizado nas chamadas à API
        "access_token": "222rkya88",
        "token_type": "access_token"
    }
                

    OBSERVAÇÃO IMPORTANTE:
    As informações passadas para o campo Authorization devem ser encodadas em Base 64. Assim, para gerar o header Authorization do par client_id: aC2yaac23 e client_secret: 1bhS45TT, deve ser gerado o base64 da string "aC2yaac23:1bhS45TT", que resultará na chave YUMyeWFhYzIzOjFiaFM0NVRU


  • 4

    Chamada à API

    Agora que o Access Token foi obtido, sua aplicação pode finalmente fazer o apontamento para o endpoint de produção e, substituir a chave que foi gerada automaticamente para Sandbox.

     



 

Referências de Implementação

Se você tem dúvidas de como implementar as iterações acima na linguagem de sua preferência, consulte algumas biblitecas recomendadas no site do OAuth2, na sessão "Client Libraries".

Se preferir, pode utilizar nosso script em Node.js, já configurado para os apontamentos listados acima.

Segurança na Troca de Informações

O tráfego de informações deve feito através de protocolo HTTPS, sendo que, para chamadas a recursos que não sejam feitas por intermédio deste protocolo, o conteúdo trafegado fica sob responsabilidade do desenvolvedor. Veja mais detalhes sobre a utilização desse protocolo.

Erros de Autenticação

Alguns erros serão tratados durante a autenticação dos Tokens. Abaixo a lista dos erros:

Ausência de um dos Tokens: Os dois Tokens (client_id e access_token) devem ser passados em todas as requisições. Caso um deles esteja ausente, será retornado o erro 401 Unauthorized.

Token inexistente/errado: Se qualquer um dos Tokens passados não existir ou estiver com algum erro (caso tenha sido alterado), será retornado o erro 401 Unauthorized.

Tokens revogados/inválidos: Se qualquer um dos Tokens tiver sido revogado ele será considerado inválido e será retornado o erro 403 Forbidden.

Para os erros Ausência de um dos Tokens e Token inexistente/errado medidas podem ser tomadas do lado do desenvolvedor para validar se as informações que estão sendo passadas estão válidas. Para o erro Tokens revogados (inválidos) a única ação será solicitar um novo Token.

Português, Brasil