Código de autorização¶
Realiza a solicitação de autorização ao titular do certificado, 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 SerproID 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 SerproID, https://serproid.serpro.gov.br/oauth/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 SerproID.
| 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:
|
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://serproid.serpro.gov.br/oauth/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%2Fserproid.serpro.gov.br%2Fbank%2F%23!%2Fcallback-serproid
&scope=single_signature
&state=aut
&login_hint=11111111111
Quando o usuário visitar a URL, o PSC SerproID 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 SerproID 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://serproid.serpro.gov.br/bank#!callback-serproid
?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 SerproID 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://serproid.serpro.gov.br/bank#!callback-serproid
?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).
-
Serviço de recuperação do certificado digital (
X509).
multi_signature¶
- Serviço de assinatura digital, por uma única vez e de um(1) ou mais resumos criptográficos (hashes).
-
Serviço de recuperação do certificado digital (
X509).
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.
-
Serviço de recuperação do certificado digital (
X509). -
Serviço de revogação da autorização de sessão de assinatura concedida pelo titular do certificado.
authentication_session¶
- Serviço de recuperação do certificado digital (
X509).
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 SerproID 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_challengedeve ter no mínimo 43 caracteres" - "Redirect uri inválida para a aplicação"
- "Erro interno no processamento da requisição"