Requisição HTTP
Cada recurso de um WebService pode exigir vários, alguns ou nenhum nível de autenticação.
O exemplo asseguir mostra uma requisição HTTP que submete um novo evento para uma API REST fictícia do Pandora. Nessa requisição podemos ver os três níveis de autenticação sendo informados no cabecalho da requisição:
POST http://api.pandora.cnpgc.embrapa.br/eventos HTTP/1.1 ... x-embrapa-auth-timestamp: 1393938240 # 15/04/2012 13:04:00 # Credenciais da aplicação x-embrapa-auth-application-id: pandora_mobile x-embrapa-auth-application-signature: GoFqh18rO5tUHCyZG2 # Credenciais do cliente x-embrapa-auth-client-id: 123 x-embrapa-auth-client-signature: 7XK9OT8ZW34IPRQA # Credenciais do usuário do sistema x-embrapa-auth-user-id: brunorighes x-embrapa-auth-user-signature: 96afea21475837aa03f5acb37677
Todos os cabecalhos do protocolo, tem o prefixo “x-embrapa-auth“.
Além do campo de timestamp, cada nível de autênticação possui dois campos: o identificador (id) e uma assinatura (signature).
O cabecalho “x-embrapa-auth-timestamp” é um UNIX timestamp em segundos, que deve informar o instante em que a requisição está sendo enviada. Com essa informação o servidor é capaz de verificar a idade na requisição e poderá retornar um erro se ela ultrapassar a idade máxima tolerada. O servidor DEVERÁ estipular um tempo de expiração de uma requisição. Recomenda-se definir esse valor entre 5 e 15 minutos, dependendo da velocidade esperada da conexão. A validação do timestamp protege o servidor contra replay attacks.
O identificador de cada nível de autenticação é definido pelos atributos ‘x-embrapa-auth-*-id‘. Ou seja, uma string com um identificador único para o cliente, o usuário e a aplicação. No caso de um usuário, o atributo ‘x-embrapa-auth-user-id‘ pode ser, por exemplo, o seu login no sistema, seu ID numérico ou seu e-mail.
O atributo de assinatura ‘x-embrapa-auth-*-signature‘, por sua vez, será o resultado de uma computação simples: o HMAC-SHA1 do timestamp concatenado com o identificador do usuário, cliente ou aplicação utilizando a senha, chave privada ou token, respectivamente, como secret key.
x-embrapa-auth-application-signature: hmac_sha1 (timestamp || application_id, token) x-embrapa-auth-client-signature: hmac_sha1 (timestamp || client_id, private_key) x-embrapa-auth-user-signature: hmac_sha1 (timestamp || user_id, password)
Com as informações públicas (timestamp e identificadores) o servidor é capaz de buscar em sua base de dados as chaves para reproduzir a computação HMAC-SHA1 e verificar a validade da assinatura.
