Authenticating with OAuth 2.0
A HP reconhece que a privacidade È um direito humano fundamental e a import‚ncia da privacidade, da seguranÁa e da proteÁ„o dos dados de nossos clientes e parceiros em todo o mundo. Seja vocÍ um cliente ou parceiro, saiba que pode contar com a HP para a proteÁ„o de seus dados em todas as nossas operaÁıes. Para que seus aplicativos acessem as APIs de Gest„o proativa, eles precisam estar autenticados. A Gest„o proativa utiliza o protocolo OAuth 2.0 , que È padr„o na ind˙stria, para concess„o de acesso, graÁas ‡ sua simplicidade e facilidade de implementaÁ„o.
Siga essas etapas para habilitar seu aplicativo para fazer chamadas de API autenticada usando o OAuth 2.0:
Etapa 1 ó Configurar o seu aplicativo
Para criar um aplicativo:
- Em um navegador de Internet, navegue atÈ o Portal de desenvolvedores da HP em https://developers.hp.com.
- Clique em Login para fazer login no Portal de desenvolvedores da HP usando seu nome de usu·rio/senha de Gest„o proativa. Se vocÍ ainda n„o tem uma conta no Portal de desenvolvedores da HP, clique no link Registrar para criar uma conta.
- Abra o menu suspenso sob seu endereÁo de e-mail e clique em Meus aplicativos.
- Clique em Adicionar um novo App.
- Na prÛxima p·gina, Selecione Nome de produto como HP TechPulse Analytics e preencha os campos abaixo para o novo aplicativo.
Campo
|
DescriÁ„o
|
ObrigatÛrio
|
---|---|---|
Escopo do aplicativo
|
Selecione Ler em escopo de produto
|
Sim
|
Nome do app
|
Nome do aplicativo de cliente
|
Sim
|
Nome ˙nico do aplicativo
|
Identificador ˙nico do aplicativo, gerado automaticamente
|
N„o
|
URI de redirecionamento
|
URI de redirecionamento apÛs autenticar o cliente
|
Sim
|
ObservaÁ„o: Para evitar transaÁıes fraudulentas durante o processo de autenticaÁ„o, as APIs de Gest„o proativa se comunicam com URLs de redirecionamento que foram identificados como endpoints confi·veis. Certifique-se de que o campo URLs de redirecionamento do seu aplicativo contenham um URL de chamada de retorno v·lido para o seu servidor que est· ouvindo para completar sua parte do fluxo de trabalho de autenticaÁ„o.
ObservaÁ„o: A HP recomenda usar HTTPS sempre que possÌvel e tambÈm usar URLs de redirecionamento (por exemplo, "https://example.com/auth/callback", and not "/auth/callback").
- Clique em Criar aplicativo. Isso cria um novo aplicativo e coloca a solicitaÁ„o de aplicativo no estado Pendente atÈ a HP aprovar a solicitaÁ„o do aplicativo. Clique em Meu aplicativo para conferir o status da nova solicitaÁ„o de aplicativo.
- Depois que a nova solicitaÁ„o de aplicativo for aprovada pela HP, um e-mail È enviado para o usu·rio da Gest„o proativa. Navegue atÈ Meu aplicativo e o novo aplicativo estar· no estado Aprovado.
- Clique no aplicativo aprovado para obter a chave de API (ID de cliente) e segredo de API (segredo de cliente) para esse novo aplicativo. .
ObservaÁ„o: A HP recomenda n„o compartilhar o valor de segredo de cliente com ninguÈm; inclusive n„o post·-lo em fÛruns de suporte para ajuda com o seu aplicativo.
⚠ Importante: O valor de segredo de cliente associado ao seu ID de cliente vai expirar automaticamente apÛs 365 dias. Registre as datas inicial e final para que vocÍ esteja ciente sobre a idade atual do valor de segredo de cliente. Se o valor de segredo de cliente for prÛximo a 365 dias de duraÁ„o, redefina-o e atualize o seu aplicativo. Para obter mais informaÁıes sobre a redefiniÁ„o do valor do segredo de cliente, consulte o Redefinir o segredo de cliente associado ao seu ID do cliente
.
Etapa 2 ó Solicite um cÛdigo de autorizaÁ„o
Depois de configurado o aplicativo, È hora de solicitar um cÛdigo de autorizaÁ„o. O cÛdigo de autorizaÁ„o n„o È o token final que vocÍ usa para fazer chamadas para a API Analytics. … usado na prÛxima etapa do fluxo OAuth 2.0 para trocar por um token de acesso real.
Redirecionar o usu·rio
Para solicitar um cÛdigo de autorizaÁ„o, vocÍ deve direcionar o navegador do usu·rio para o endpoint de autorizaÁ„o oAuth 2.0. Depois de feita a solicitaÁ„o, uma das duas situaÁıes seguintes ocorrer·:
- O navegador ser· redirecionado para a tela de autorizaÁ„o da HP DaaS. Quando o usu·rio concluir o processo de autorizaÁ„o, o usu·rio È redirecionado para o URI fornecido no par‚metro de consulta redirect_uri .
-
Se a sess„o j· existir, a tela de autorizaÁ„o È aprovada e o usu·rio È imediatamente redirecionado para o URI fornecido no par‚metro de consulta redirect_uri .
Para clientes dos EUA
GET | https://daas.api.hp.com/oauth/v1/authorize |
Para clientes da UE
GET | https://eu.daas.api.hp.com/oauth/v1/authorize |
Par‚metro
|
DescriÁ„o
|
ObrigatÛrio
|
---|---|---|
client_id
|
O valor "Chave de API" gerado quando vocÍ registrou seu aplicativo
|
Sim
|
redirect_uri
|
O URI para o seu usu·rio ser· redirecionado de volta apÛs a autorizaÁ„o.
Este valor deve corresponder a um dos URLs de redirecionamento do OAuth 2.0 definidos na configuraÁ„o do aplicativo. por exemplo, https://example.com/auth/callback |
Sim
|
response_type
|
O valor deste campo sempre deve ser: "code"
|
Sim
|
abrangÍncia
|
escopo como "Lido"
|
Sim
|
estado
|
Uma string usada para manter o estado entre a solicitaÁ„o e a resposta de redirecionamento. Isso È usado para evitar o CSRF.
por exemplo, state=DCEeFWf45A53sdfKef424 |
Sim
|
https://daas.api.hp.com/oauth/v1/authorize?client_id=VkGp3021j8m3l6vwz6AEr08lDxrAHdxi&redirect_uri=http://localhost&response_type=code&scope=Read&state=DCEeFWf45A53sdfKef424
A experiÍncia do usu·rio
Depois de redirecionado, o usu·rio ser· apresentado com uma p·gina de autenticaÁ„o HP DAAS .
ApÛs autenticaÁ„o, o HP DaaS redireciona o usu·rio para o local especificado no redirect_uri e retorna um cÛdigo de autorizaÁ„o e um estado.
-
code ó O cÛdigo de autorizaÁ„o OAuth 2.0.
-
state ó Um valor usado para testar possÌveis ataques CSRF .
O cÛdigo È um valor que vocÍ trocar· com o HP DaaS por um token de acesso OAuth 2.0 real na prÛxima etapa do processo de autenticaÁ„o. Por fins de seguranÁa, o cÛdigo de autorizaÁ„o tem uma vida ˙til muito curta e deve ser usado dentro de momentos apÛs recebÍ-lo: antes de expirar e vocÍ precisa repetir todas as etapas anteriores para solicitar outro.
Antes de aceitar o cÛdigo de autorizaÁ„o, seu aplicativo deve garantir que o valor devolvido no par‚metro estadual corresponda ao valor do estado a partir de sua solicitaÁ„o original do cÛdigo de autorizaÁ„o. Isso garante que vocÍ esteja tratando com o usu·rio original real e n„o um script malicioso que de alguma forma conseguiu entrar no seu fluxo de autenticaÁ„o. Se os valores do Estado n„o corresponderem, vocÍ provavelmente ser· vÌtima de um ataque CSRF e responder com um cÛdigo de erro HTTP 401.
Etapa 3 ó Trocar cÛdigo de autorizaÁ„o por um token de acesso
A etapa final para obter um token de acesso È que seu aplicativo solicite um usando o cÛdigo de autorizaÁ„o que acabou de obter. Isso È feito fazendo o seguinte "x-www-form-urlencoded" HTTP POST solicitaÁ„o:
Para clientes dos EUA
POST | https://daas.api.hp.com/oauth/v1/token |
Para clientes da UE
GET | https://daas.api.hp.com/oauth/v1/token |
Par‚metro
|
DescriÁ„o
|
ObrigatÛrio
|
---|---|---|
grant_type
|
O valor deste campo deve ser sempre: authorization_code
|
Sim
|
cÛdigo
|
O cÛdigo de autorizaÁ„o que vocÍ recebeu da Etapa 2.
|
Sim
|
redirect_uri
|
O mesmo valor "redirect_uri" que vocÍ passou na etapa anterior.
|
Sim
|
client_id
|
O valor "Chave de API" gerado na etapa 1.
|
Sim
|
client_secret
|
O valor "Chave de segredo" gerado na etapa 1.
|
Sim
|
POST: /oauth/v1/token HTTP/1.1
Host: https://daas.api.hp.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=cF5faYzL&redirect_uri=http://localhost&client_id=123456789&client_secret=shhdonottell
Resposta do token de acesso
Uma solicitaÁ„o bem-sucedida de token de acesso retornar· um objeto JSON contendo os seguintes campos:
- access_token ó O token de acesso para o usu·rio. Esse valor deve ser mantido seguro, de acordo com o seu acordo com os Termos de Uso da API.
- expires_in ó O n˙mero de segundos restantes, a partir do momento em que foi solicitado, antes do token expirar. Atualmente, todos os tokens de acesso s„o emitidos com uma vida ˙til de 30 minutos.
- refresh_token - Token de atualizaÁ„o para solicitar novo token de acesso;quando o token acesso expirou.
Vida ˙til dos tokens
Os tokens de acesso permanecem v·lidos atÈ que o n˙mero de segundos seja devolvido no campo expires_in na resposta da API. Um usu·rio pode passar pelo fluxo OAuth em v·rios clientes (navegadores ou dispositivos) e, simultaneamente, manter v·rios tokens de acesso v·lidos.
Etapa 4 ó Criar solicitaÁıes autorizadas
<
p>Depois de obter um token de acesso, vocÍ pode comeÁar a fazer solicitaÁıes autorizadas de API em nome do usu·rio. Isso È feito incluindo um cabeÁalho "Authorization" em sua chamada HTTP para a API HP TechPulse Analytics. Aqui est· uma solicitaÁ„o HTTP de amostra, incluindo o valor do cabeÁalho que inclui o token:
POST: /analytics/v1/reports/hwinv/deviceType/type/graph HTTP/1.1
Host: https://daas.api.hp.com
Conex„o: Keep-Alive
AutorizaÁ„o: Bearer 9vVLTv496kRmIAkfRwDvAUAr271T
Tokens inv·lidos
Se vocÍ fizer uma chamada de API usando um token inv·lido, receber· uma resposta "401 N„o Autorizado" do servidor. Um token pode ser inv·lido e precisar de regeneraÁ„o devido a:
- Ele ter expirado.
- Um fluxo OAuth2 subsequente que gerou um novo token de acesso. O token anterior ser· invalidado.
Uma vez que um prazo de validade previsÌvel n„o È o ˙nico fator contribuinte para a invalidaÁ„o do token, È muito importante que vocÍ cÛdigo seus aplicativos para lidar adequadamente com um encontro com um erro 401 redirecionando o usu·rio de volta para o inÌcio do fluxo de trabalho de autorizaÁ„o.
ObservaÁ„o: Em caso de falhas a jusante na verificaÁ„o do token de acesso, vocÍ receber· uma resposta de erro de 500 ou 503.
Etapa 5 ó Atualize seus tokens de acesso
Para proteger os dados do nosso membro, o HP DaaS n„o gera tokens de acesso excessivamente longos. VocÍ deve garantir que seu aplicativo seja projetado para processar a atualizaÁ„o de tokens de usu·rio antes de expirar, para evitar que os usu·rios tenham que passar desnecessariamente pelo processo de autorizaÁ„o para reobter acesso a um perfil DaaS .
Atualizar um token
Para atualizar um token de acesso,
- O token de atualizaÁ„o obtido a partir do fluxo do cÛdigo de autorizaÁ„o pode ser usado no fluxo de token de atualizaÁ„o para obter um novo token de acesso. O fluxo de token de atualizaÁ„o n„o envolve interaÁ„o final do usu·rio.
- Agora envie uma solicitaÁ„o POST para o endpoint /oauth/v1/token para trocar o token de atualizaÁ„o por um token de acesso.
- A autenticaÁ„o b·sica HTTP deve ser usada ao fazer essa solicitaÁ„o juntamente com o cabeÁalho da solicitaÁ„o e o corpo, conforme explicado abaixo.
Para clientes dos EUA
POST | https://daas.api.hp.com/oauth/v1/token |
Para clientes da UE
GET | https://daas.api.hp.com/oauth/v1/token |
Par‚metro
|
DescriÁ„o
|
ObrigatÛrio
|
---|---|---|
grant_type
|
Para atualizar o token este valor deve ser:
refresh_token |
Sim
|
refresh_token
|
O token de atualizaÁ„o retornado para vocÍ ao autenticar
|
Sim
|
AutenticaÁ„o com Auth b·sico
Para atualizar o token vocÍ deve usar a autenticaÁ„o b·sica HTTP, fornecer a chave de API e o segredo concatenados juntamente com um :
separando-os e codificar essa sequÍncia resultante no base64.
Exemplo de cabeÁalho Auth:
AutorizaÁ„o: Basic OTZDbml6gragegrmmWVHRnFHSjlRZ0FtQzRGRFE6TGdWTElrQXdCdG=
POST /oauth/v1/token HTTP/1.1
Accept: application/json
AutorizaÁ„o: Basic OTZDbml6ZUJoTXdQR1RXXXVHRnFFE6TGdWTElrQXdCdGFMenEzVFZqNkFkUUR0a0xWRXFNcnQ=
Content-Type: application/x-www-form-urlencoded
Host: daas.api.hp.com
grant_type=refresh_token&refresh_token=HZQlf0Bxc2gaergkQUYVjtoCaCwsTp
{
"access_token": "9vVLTv496kRmIAkfRwDvAUAr271T",
"scope": "Read",
"token_type": "Bearer",
"refresh_token": "D9HhoBelDMPizflefEMRNztIlrnEflUP",
"expires_in": 1799999
}
Etapa 6 - Entender as permissıes de aplicativo
Abaixo est„o as funÁıes que podem acessar as APIs de integraÁ„o de incidentes HP TechPulse e HP TechPulse Analytics.
- Cliente ñ Administrador de TI, administrador de relatÛrio
- MSP ñ Especialista em suporte, administrador de suporte
- Parceiro ñ Administrador parceiro