Ir para o conteúdo

Token de acesso

Realiza a troca do código de autorização pelo token de acesso que autoriza a realização das chamadas de serviço para utilização do certificado digital do usuário.


POST /token

Solicitação

A aplicação deve solicitar ao endpoint de token do PSC NeoID, https://psc-neoid.estaleiro.serpro.gov.br/psc/v0/oauth/token postando via application/x-www-form-urlencoded os parâmetros necessários.

Parâmetros

A tabela a seguir descreve os parâmetros suportados pelo endpoint de token do PSC NeoID.

Parâmetro Presença Descrição / Valor
grant_type (Obrigatório) O valor deve ser "authorization_code"
client_id (Obrigatório) Deve conter o client_id (identificador único) da aplicação
client_secret (Obrigatório) Deve conter a client_secret (senha) da aplicação, utilizado em conjunto com o client_id para a sua identificação
code (Obrigatório) Deve conter o código de autorização, code, retornado na redirect_uri no serviço código de autorização
code_verifier (Obrigatório) Deve ser informado a chave de prova aleatória (code_verifier) gerada para derivar o desafio (code_challenge) informado na solicitação de autorização.
Para mais informações, consulte PKCE RFC.
Visualize aqui o código de exemplo
redirect_uri (Opcional) Caso tenha sido informado na solicitação de autorização, o mesmo valor deve ser informado

Exemplo

O exemplo encontra-se com quebras de linha e espaços para melhor leitura

```http tab="HTTP" POST /psc/v0/oauth/token HTTP/1.1 Host: psc-neoid.estaleiro.serpro.gov.br Content-type: application/x-www-form-urlencoded

grant_type=authorization_code &client_id={client_id} &client_secret={client_secret} &code={código_de_autorização} &code_verifier={code_verifier} &redirect_uri={redirect_uri}

```shell tab="cURL"
curl -X POST \
 https://psc-neoid.estaleiro.serpro.gov.br/psc/v0/oauth/token \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -H 'cache-control: no-cache' \
 -d 'grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={código_de_autorização}&code_verifier={code_verifier}&redirect_uri={redirect_uri}'

Resposta da solicitação

O PSC NeoID irá verificar todos os parâmetros para validar a solicitação. As credenciais da aplicação, client_id e client_secret, serão checadas para realizar a sua autenticação, será verificado se o code informado não está expirado e se foi emitido para a aplicação identificada, será checado se o valor do code_verifier foi utilizado para derivar o code_challenge apresentado na solicitação de autorização, assim como, se informado, será verificado se a redirect_uri é idêntica à apresentada na solicitação de autorização.

Solicitação válida (Sucesso)

Se a solicitação estiver válida, o PSC NeoID irá gerar um token de acesso (access_token), que será retornado via HTTP code 200 na resposta da solicitação em conjunto com alguns parâmetros adicionais no formato application/json.

Atenção

O token retornado concede permissão à utilização dos serviços relacionados à utilização do certificado digital do usuário, como o uso da chave privada para a realização de assinatura digital, considerações de segurança devem ser garantidas pela aplicação para que o seu valor não seja exposto.

Parâmetros

JSON:

  • access_token - (string) - token de acesso gerado pelo PSC NeoID que permite a chamada aos serviços de utilização do certificado
  • token_type- (string) - tipo do token, valor fixo "Bearer"
  • expires_in - (inteiro) - validade do token em segundos
  • scope - (string) - escopo de autorização concedido conforme permissão de uso solicitada pela aplicação
  • authorized_identification_type - (string) - identifica se o certificado autorizado é do tipo Pessoa Física ou Pessoa Jurídica, "CPF" ou "CNPJ", respectivamente
  • authorized_identification - (string) - valor do "CPF" ou "CNPJ" do certificado autorizado, dependendo do valor informado no campo authorized_identification_type

A validade do token de acesso dependerá do tipo de permissão de uso solicitada através do parâmetro scope na solicitação de autorização. Para os valores single_signature, multi_signature e authentication_session, o token estará válido por 5 minutos. Para o valor signature_session, o token está válido pelo período de tempo autorizado pelo titular do certificado.

Saiba mais

Os períodos de tempo possíveis para autorização do titular do certificado, quando da solicitação de permissão de escopo de sessão de assinatura (valor signature_session informado no parâmetro scope) variam de acordo com o tipo de certificado.

Certificado de Pessoa Física: 15 Minutos, 1 hora, 4 horas, 8 horas, 1 dia, 3 dias, 7 dias

Certificado de Pessoa Juríddica: 1 hora, 8 horas, 1 dia, 3 dias, 7 dias, 15 dias, 30 dias

Exemplo
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: Cache-Control
Pragma: no-cache

{
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJuZW9pZCIsImF1ZCI6Im5lb2lkIiwic3ViIjoiNjRlNTg3ZmEtNGYzMC00ODdkLTk2ZjAtNDRlNmIxNGZmNjIwIiwiaWF0IjoxNTI4OTgyMDYyLCJqdGkiOiI4N2NhYTkzOS0wMjgxLTQ1YjktODA3Mi1lNjI1NDkzN2JlMzYiLCJoYXQiOiJNVEV6T1RJQUFBQUFBQUFBQUFBQUFPYXBWdEJnenp0b2JxZFY5Sk5CemRCVVVQcHlhdGtMWTJ2UjNDTFJmQy8wQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBRC8vLy8vLy8vLy93PT0ifQ.qsUtA4hBWGtM5HYuMcLMtWtDQtdgk95Rf_sJhMbAgvEqkq0xq6e4-1QXrLfodbbOES0Jnz4RpRpdmuXOVcLcduCmstgOfPIvjqi5Ewb93zTpuGavDGCmNiFpd33T8ytdl9KhIyCVisDg8LEWIdiPscBk421zTu2Dquj4rzQGVVM1EkrCqOazeU6zxnF3gSuIOgnvxeReu6k-runIPr5F1ZAsglPsQKp-WZqmqG9gmzoNOSXSFFD3g2S5nS4zdKuOL8NH1QfJytF72Ylvifhj4Fdlz9wWLDXZwMmvQjhHmJetNnN16D1CS3PUlQq1VdStMktgoOSqQOLzUMxPuLq-gw",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "single_signature",
    "authorized_identification_type": "CPF",
    "authorized_identification": "11111111111"
}

Solicitação inválida (Erro)

Se a solicitação for considerada inválida, seja devido a verificação dos parâmetros informados ou caso algum erro inesperado aconteça, o PSC NeoID retornará um erro no formato application/json com o HTTP code correspondente ao tipo do erro.

Parâmetros

JSON:

  • error - (string) - tipo do erro
  • error_description- (string) - descrição do erro
  • error_uri - (string) - URI da documentação que descreve o erro
Exemplo
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "error": "invalid_request",
    "error_description": "Parâmetro(s) requerido(s) não informado(s): code_verifier",
    "error_uri": "https://servicos.serpro.gov.br/neoid/docs/#lista-de-erros-possiveis"
}
Lista de erros
Tipo do erro HTTP Code Detalhes
invalid_request 400 A estrutura da solicitação encontra-se inválida.

Cenários possíveis:
  • Parâmetro requerido não informado
  • Parâmetro com mais de um valor informado
unsupported_grant_type 400 Valor do parâmetro grant_type inválido
invalid_client 401 Credenciais de autenticação inválidas.

Cenários possíveis:
  • Não foi possível identificar a aplicação pela client_id
  • client_secret informada inválida para a aplicação identificada
invalid_grant 400 O valor dos parâmetros code, code_verifier ou redirect_uri são inválidos.

Cenários possíveis:
  • Valor inválido do código de autorização (code)
  • Código de autorização (code) expirado
  • Valor do parâmetro redirect_uri com encode inválido
  • Valor do parâmetro redirect_uri não informado ou diferente do apresentado na solicitação de autorização
  • Valor do parâmetro code_verifier não condiz com o valor do code_challenge informado na solicitação de autorização
  • O token de acesso (access_token) referente ao código de autorização (code) informado já foi gerado e/ou utilizado
server_error 500 Algo inesperado aconteceu e não foi possível dar prosseguimento com a solicitação