Ir para o conteúdo

Código de autorização

Realiza a solicitação de autorização ao titular do certficado, de acordo com a permissão de uso requisitada, assinatura digital ou autenticação. Após a autorização, será retornado o código de autorização à aplicação solicitante.


GET /authorize

Solicitação

O primeiro passo a ser realizado é criar uma solicitação de autorização contendo os parâmetros necessários para o PSC NeoID identificar a aplicação cliente e solicitar autorização ao usuário conforme a permissão de uso requisitada.

O usuário deve ser direcionado para o endpoint de autorização do PSC NeoID, https://psc-neoid.estaleiro.serpro.gov.br/psc/v0/oauth/authorize, concatenando via query param os parâmetros necessários.

Parâmetros

A tabela a seguir descreve os parâmetros suportados pelo endpoint de autorização do PSC NeoID.

Parâmetro Presença Descrição / Valor
response_type (Obrigatório) O valor deve ser "code"
client_id (Obrigatório) Deve conter a identificação da aplicação
code_challenge (Obrigatório) Valor utilizado para proteger a concessão do código de autorização, garantindo que quem iniciou a solicitação será quem irá realizar a troca do código de autorização pelo token de acesso.
Baseia-se na criação aleatória para cada solicitação de uma chave de prova (code_verifier), que é utilizada para derivar um desafio (code_challenge).
A chave deve ser armazenada pela aplicação e o desafio é informado na solicitação de autorização, posteriormente a chave é apresentada no momento da troca do código de autorização pelo token de acesso e é verificado se corresponde à chave que derivou o desafio apresentando anteriormente.
Para mais informações, consulte PKCE RFC.
Visualize aqui o código de exemplo
code_challenge_method (Obrigatório) Valor correspondente ao método utilizado na chave de prova (code_verifier) para derivar o desafio (code_challenge).
Deve ser informado o valor "S256", que corresponde ao método que deve ser utilizado para derivar o desafio.
Para mais informações, consulte PKCE RFC.
redirect_uri (Opcional) Deve ter a URI para redirecionar o usuário de volta para a aplicação de origem.
A URI deve estar na lista de URI's autorizadas para a aplicação.
Deve ser URL encoded.
Se não informado, será considerada a primeira URI cadastrada para a aplicação no serviço de cadastro
scope (Obrigatório) Os possíveis valores são:
  • single_signature

    Autoriza a aplicação a realizar a assinatura de apenas um conteúdo (hash), sendo invalidado após a sua utilização.

  • multi_signature

    Autoriza a aplicação a realizar a assinatura de múltiplos (hashes) em uma única requisição, sendo invalidado após a sua utilização.

  • signature_session

    Autoriza a aplicação a realizar várias assinaturas, única ou em lote, pelo período de tempo concedido pelo titular do certificado e enquanto a autorização não tiver sido revogada, pelo titular ou pela própria aplicação.

  • authentication_session

    Autoriza a aplicação a relizar a autenticação do titular, não permitindo a realização de assinaturas ou outras utilizações da chave privada.

state (Opcional)
Recomendado
Parâmetro que pode ser utilizado para "manter a sessão" do usuário na aplicação de origem, já que será retornado sem modificações na redirect_uri.
Recomenda-se seu uso também para prevenção de ataques CSRF
login_hint (Opcional) Valor de CPF ou CNPJ a ser informado como filtro para seleção do certificado a ser utilizado pelo usuário

Exemplo

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

Exemplo de URI de solicitação

https://psc-neoid.estaleiro.serpro.gov.br/psc/v0/oauth/authorize/?
response_type=code
&client_id=64e587fa-4f30-487d-96f0-44e6b14ff620
&code_challenge=aRU8irrNrwu8U8cH1nYTvdcFNujZo5_Gri5j02xmXUU
&code_challenge_method=S256
&redirect_uri=https%3A%2F%2Fneoid.estaleiro.serpro.gov.br%2Fbank%2F%23!%2Fcallback-neoid
&scope=single_signature
&state=aut
&login_hint=11111111111

Quando o usuário visitar a URL, o PSC NeoID irá apresentá-lo uma tela contendo a identificação da aplicação e a permissão de uso (scope) requisitada, solicitando a sua autorização.

Redirecionamento para aplicação cliente

Após a decisão do usuário, o PSC NeoID irá o redirecionar para a redirect_uri informada pela aplicação cliente.

Autorização concedida

No cenário de autorização por parte do usuário, será concatenado à redirect_uri, através de query param, o parâmetro code. Adicionalmente o parâmetro state será também concatenado caso tenha sido informado na solicitação de autorização.

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

Exemplo de redirecionamento após autorização

https://neoid.estaleiro.serpro.gov.br/bank#!callback-neoid
?code=07cceb34-2d04-401b-957d-715b3643240c
&state=aut

O valor do parâmetro state será o mesmo inicialmente informado pela aplicação na solicitação de autorização. É esperado que a aplicação cliente valide que o valor retornado seja idêntico ao valor setado originalmente, essa checagem serve como proteção a ataques do tipo CSRF e correlatos.

O valor do parâmetro code é o código de autorização gerado pelo PSC NeoID que representa a autorização do usuário. Este código estará válido por apenas 60 segundos, período no qual poderá ser utilizado para obtenção do token de acesso.

Autorização recusada

No cenário de recusa por parte do usuário, será concatenado à redirect_uri, através de query param, o parâmetro error. Adicionalmente o parâmetro state será também concatenado caso tenha sido informado na solicitação de autorização.

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

Exemplo de redirecionamento após recusa

https://neoid.estaleiro.serpro.gov.br/bank#!callback-neoid
?error=access_denied
&state=aut

O valor do parâmetro state será o mesmo inicialmente informado pela aplicação na solicitação de autorização. É esperado que a aplicação cliente cheque que o valor retornado seja idêntico ao valor setado originalmente, essa checagem serve como proteção a ataques do tipo CSRF e correlatos.

O valor do parâmetro error será o valor fixo access_denied, que representa a recusa por parte do usuário.

Permissões de uso (scope)

Cada valor possível do parâmetro scope corresponde a uma permissão específica requisitada ao titular do certificado. De tal forma, após concedida, a aplicação estará autorizada a realizar a chamada dos serviços disponíveis para cada uso.

Segue abaixo a lista do(s) serviço(s) autorizado(s) e a(s) restrição(ões) para cada scope:

Atenção

Os serviços listados abaixo são autorizados com a apresentação do token de acesso, obtido no serviço Token de Acesso através da apresentação do código de autorização retornado à aplicação após a autorização do titular do certificado.

single_signature

Serviço de assinatura digital, por uma única vez e de apenas um (1) resumo criptográfico (hash).
  • [Assinatura digital](../utilizacao-certificado/assinatura-digital.md)

Serviço de recuperação do certificado digital (X509).

  • [Recuperação de certificado](../utilizacao-certificado/recuperacao-certificado.md)

multi_signature

Serviço de assinatura digital, por uma única vez e de um(1) ou mais resumos criptográficos (hashes).
  • [Assinatura digital](../utilizacao-certificado/assinatura-digital.md)

Serviço de recuperação do certificado digital (X509).

  • [Recuperação de certificado](../utilizacao-certificado/recuperacao-certificado.md)

signature_session

Serviço de assinatura digital, de um(1) ou mais, por um número indeterminado de vezes, durante o período de tempo autorizado pelo titular do certificado e enquanto a autorização não estiver sido revogada.
  • [Assinatura digital](../utilizacao-certificado/assinatura-digital.md)

Serviço de recuperação do certificado digital (X509).

  • [Recuperação de certificado](../utilizacao-certificado/recuperacao-certificado.md)

Serviço de revogação da autorização de sessão de assinatura concedida pelo titular do certificado.

  • [Revogação de sessão de assinatura]

authentication_session

Serviço de recuperação do certificado digital (X509).
  • [Recuperação de certificado](../utilizacao-certificado/recuperacao-certificado.md)

Lista de erros

Erro na criação da solicitação

Caso a aplicação cliente direcione o usuário para uma uma solicitação inválida, devido por exemplo a um parâmetro obrigatório não informado, o PSC NeoID irá apresentar uma tela de erro ao usuário final, exibindo o motivo do erro.

Segue abaixo a lista das mensagens dos possíveis erros que podem ser exibidos:

  • "Parâmetro(s) requerido(s) não informado(s): <lista_nome_dos_parâmetros>"
  • "Parâmetro(s) duplicado(s) informado(s): <lista_nome_dos_parâmetros>"
  • "Parâmetro(s) com valor(es) inválido(s): <lista_nome_dos_parâmetros>"
  • "Não foi possível identificar a aplicação cliente"
  • "O parâmetro code_challenge deve ter no mínimo 43 caracteres"
  • "Redirect uri inválida para a aplicação"
  • "Erro interno no processamento da requisição"