Pular para conteúdo

Auto-cadastro de aplicação com certificado SSL ICP-Brasil

Realiza o auto-cadastro de uma aplicação junto ao PSC SerproID, sendo que a aplicação utilizará um certificado SSL ICP-Brasil para assinar os dados enviados.


POST /application_cert

Solicitação

Para realizar o cadastro, a aplicação deverá enviar os seus dados assinados com seu certificado SSL ICP-Brasil ao endpoint de auto-cadastro de aplicação do PSC SerproID, https://serproid.serpro.gov.br/oauth/v0/oauth/application_cert, postando a assinatura dos dados via application/jwt.

A assinatura dos dados deve ser gerada no formato JWT with RSA Signature, conhecido como JWS (consulte RFC 7515), utilizando o algoritmo de hash SHA-256.

Parâmetros

O header do JWS deverá conter os seguintes parâmetros:

Nome Tipo Presença Descrição / Valor
alg (String) (Obrigatório) valor "RS256" representando assinatura RSA With SHA-256
x5c (Array de strings) (Obrigatório) valor multivalorado contendo o certificado SSL ICP-Brasil no formato PEM

O payload do JWS deverá conter os seguintes campos (conhecidos como claims):

Nome Tipo Presença Descrição / Valor
name (String) (Obrigatório) Nome da aplicação
comments (String) (Obrigatório) Descrição da aplicação
host (String) (Obrigatório) Host único da aplicação
redirect_uris (Array de strings) (Obrigatório) Lista de url's para redirecionamento. Devem ser oriundas do host do certificado de equipamento apresentado, sendo vedada a utilização de fragments
aud (String) (Obrigatório) Nome único do PSC ao qual se deseja cadastrar, valor fixo "serproid"
email (String) (Obrigatório) E-mail para suporte em caso de indisponibilidade, mudança de versão, etc

Exemplo do JWS codificado e decodificado:

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

eyJhbGciOiJSUzI1NiIsIng1YyI6WyItLS0tLUJFR0lOIENFUlRJRklDQVRFLS0tLS08cGVt
X2RvX2NlcnRpZmljYWRvPi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0iXX0.eyJuYW1lIjoi
Tm9tZSBkYSBBcGxpY2HDp8OjbyIsImNvbW1lbnRzIjoiRGVzY3Jpw6fDo28gZGEgQXBsaWNh
w6fDo28iLCJob3N0Ijoid3d3LmFwbGljYWNhby1leGVtcGxvLmNvbSIsInJlZGlyZWN0X3Vy
aXMiOlsiaHR0cHM6Ly93d3cuYXBsaWNhY2FvLWV4ZW1wbG8uY29tL2NhbGxiYWNrL2NlcnRp
ZmljYWRvX251dmVtIl0sImF1ZCI6Im5lb2lkIiwiZW1haWwiOiJzdXBvcnRlQGFwbGljYWNh
by1leGVtcGxvLmNvbSJ9.gBMWuEsrNLK-WybBLrxKYSc_JtL_fZAe5tgoZlmtK2FwEH-0x3T
y0UbyQiTFY4NEbYce8CvTPtZ4PfEEsJl2t9fgJBkdLt8pf_e-JliKGMEWB5_DRVHwGNoojq9
pYuGa2TLa4XocU93IU1yRdIqnAs3D4Su2acDgJA821voc0R3IXJ4tQeeBILVRF7mOTK8ksiQ
YsTtHust1DkXB8H0Zy0VWASSpT5f9YOY7sWAfW_MVHTBi13-lca0L93k5Iu9daemQOZjgTXs
0rBBQmeIs3VMhpaL_tKyxNvsx4jUYTzBSgj2yWzRaB7tZTIdO288y5_HeQ7XwL2RrI8SjFfk
EHA
/* Header do JWS */
{
    "alg": "RS256",
    "x5c": [
        "-----BEGIN CERTIFICATE-----<pem_do_certificado>-----END CERTIFICATE-----"
    ]
}
/* Payload do JWS */
{
    "name": "Nome da Aplicação",
    "comments": "Descrição da Aplicação",
    "host": "www.aplicacao-exemplo.com",
    "redirect_uris": ["https://www.aplicacao-exemplo.com/callback/certificado_nuvem"],
    "aud": "serproid",
    "email": "suporte@aplicacao-exemplo.com"
}

Dica

Em JWT.io é listado diversas bibliotecas open source existentes nas mais variadas linguagens de programação que implementam o JWS.

É possível também gerar e verificar o JWS na ferrramenta Debugger do JWT.io.

Exemplo

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

POST /oauth/v0/oauth/application_cert HTTP/1.1
Host: serproid.serpro.gov.br
Content-Type: application/jwt

eyJhbGciOiJSUzI1NiIsIng1YyI6WyItLS0tLUJFR0lOIENFUlRJRklDQVRFLS0tLS08cGVt
X2RvX2NlcnRpZmljYWRvPi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0iXX0.eyJuYW1lIjoi
Tm9tZSBkYSBBcGxpY2HDp8OjbyIsImNvbW1lbnRzIjoiRGVzY3Jpw6fDo28gZGEgQXBsaWNh
w6fDo28iLCJob3N0Ijoid3d3LmFwbGljYWNhby1leGVtcGxvLmNvbSIsInJlZGlyZWN0X3Vy
aXMiOlsiaHR0cHM6Ly93d3cuYXBsaWNhY2FvLWV4ZW1wbG8uY29tL2NhbGxiYWNrL2NlcnRp
ZmljYWRvX251dmVtIl0sImF1ZCI6Im5lb2lkIiwiZW1haWwiOiJzdXBvcnRlQGFwbGljYWNh
by1leGVtcGxvLmNvbSJ9.gBMWuEsrNLK-WybBLrxKYSc_JtL_fZAe5tgoZlmtK2FwEH-0x3T
y0UbyQiTFY4NEbYce8CvTPtZ4PfEEsJl2t9fgJBkdLt8pf_e-JliKGMEWB5_DRVHwGNoojq9
pYuGa2TLa4XocU93IU1yRdIqnAs3D4Su2acDgJA821voc0R3IXJ4tQeeBILVRF7mOTK8ksiQ
YsTtHust1DkXB8H0Zy0VWASSpT5f9YOY7sWAfW_MVHTBi13-lca0L93k5Iu9daemQOZjgTXs
0rBBQmeIs3VMhpaL_tKyxNvsx4jUYTzBSgj2yWzRaB7tZTIdO288y5_HeQ7XwL2RrI8SjFfk
EHA
curl -X POST \
https://serproid.serpro.gov.br/oauth/v0/oauth/application_cert \
-H 'Content-Type: application/jwt' \
-d eyJhbGciOiJSUzI1NiIsIng1YyI6WyItLS0tLUJFR0lOIENFUlRJRklDQVRFLS0tLS08cGVt
X2RvX2NlcnRpZmljYWRvPi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0iXX0.eyJuYW1lIjoi
Tm9tZSBkYSBBcGxpY2HDp8OjbyIsImNvbW1lbnRzIjoiRGVzY3Jpw6fDo28gZGEgQXBsaWNh
w6fDo28iLCJob3N0Ijoid3d3LmFwbGljYWNhby1leGVtcGxvLmNvbSIsInJlZGlyZWN0X3Vy
aXMiOlsiaHR0cHM6Ly93d3cuYXBsaWNhY2FvLWV4ZW1wbG8uY29tL2NhbGxiYWNrL2NlcnRp
ZmljYWRvX251dmVtIl0sImF1ZCI6Im5lb2lkIiwiZW1haWwiOiJzdXBvcnRlQGFwbGljYWNh
by1leGVtcGxvLmNvbSJ9.gBMWuEsrNLK-WybBLrxKYSc_JtL_fZAe5tgoZlmtK2FwEH-0x3T
y0UbyQiTFY4NEbYce8CvTPtZ4PfEEsJl2t9fgJBkdLt8pf_e-JliKGMEWB5_DRVHwGNoojq9
pYuGa2TLa4XocU93IU1yRdIqnAs3D4Su2acDgJA821voc0R3IXJ4tQeeBILVRF7mOTK8ksiQ
YsTtHust1DkXB8H0Zy0VWASSpT5f9YOY7sWAfW_MVHTBi13-lca0L93k5Iu9daemQOZjgTXs
0rBBQmeIs3VMhpaL_tKyxNvsx4jUYTzBSgj2yWzRaB7tZTIdO288y5_HeQ7XwL2RrI8SjFfk
EHA

Resposta da solicitação

De posse do JWS, o PSC SerproID irá extrair os dados da aplicação da assinatura para validar se todos os dados obrigatórios foram informados, se a chave privada utilizada para assinatura corresponde com a chave do certificado apresentado no campo x5c, asssim como se os valores de host e redirect_uri pertencem ao host em que o certificado SSL foi emitido.

Solicitação válida (Sucesso)

Se a solicitação estiver válida, o PSC SerproID irá cadastrar e gerar as credenciais da aplicação, client_id (identificar único) e client_secret (senha), retornando os dados com HTTP code 200 no formato application/json.

Parâmetros

JSON:

  • client_id - (string) - identificador único da aplicação gerado pelo PSC SerproID
  • client_secret - (string) - secret (senha) da aplicação gerada pelo PSC SerproID
Exemplo
HTTP/1.1 200 OK
Content-Type: application/json

{
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
}

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 SerproID retornará um erro no formato application/json com o HTTP code correspondente ao tipo do erro.

Parâmetros

JSON:

  • code - (string) - código do tipo do erro
  • msg- (string) - mensagem de erro
  • debug - (string) - informações adicionais sobre o erro
Exemplo
HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "code": "FALHA_CADASTRO_APLICACAO",
    "msg": "Erro interno no cadastro da aplicação",
    "debug": ""
}
Lista de erros
Tipo do erro HTTP Code Detalhes
CERTIFICADO_OBRIGATORIO 412 Claim (x5c) do header do JWS contendo o certificado é obrigatório
VALOR_INVALIDO_CLAIM_X5C 412 O valor esperado da claim (x5c) não foi encontrado
JWS_INVALIDO 412 Assinatura JWS inválida
CERTIFICADO_INVALIDO 412 Certificado inválido
CERTIFICADO_EQUIPAMENTO_INVALIDO 412 O certificado informado não é do tipo Equipamento SSL ICP-Brasil
CADEIA_DE_CERTIFICADOS_ICP_BRASIL_NAO_ENCONTRADA 412 Não foi possível encontrar uma cadeia de certificação ICP-Brasil para o certificado informado
CERTIFICADO_EXPIRADO_OU_INVALIDO 412 O certificado informado está expirado ou é inválido
CADASTRO_APLICACAO_CERTIFICADO_REVOGADO 412 O certificado informado se encontra revogado
CADASTRO_APLICACAO_CERTIFICADO_REVOGACAO_NAO_VERIFICADA 412 Não foi possível verificar revogação do certificado informado
CAMPO_OBRIGATORIO 412 Campo obrigatório não informado
PELO_MENOS_UMA_REDIRECT_URI 412 Deve ser informado ao menos 1(uma) URI para redirect
APLICACAO_OAUTH_NOME_JA_CADASTRADO 412 O Nome da aplicação informada já se encontra cadastrado
URI_INVALIDA 412 URI informada não é considerada válida
URI_HTTPS_OBRIGATORIO 412 Protocolo HTTPS obrigatório na URI
URI_NAO_CORRESPONDE_SUBJECT_ALT_NAME_CERTIFICADO 412 Redirect URI informada não se encontra na extensão Subject Alternative Names
APLICACAO_OAUTH_HOST_JA_CADASTRADO 412 Já existe uma aplicação cadastrada com host informado
FALHA_AO_LER_CERTIFICADO 412 Erro na leitura do certificado informado
FALHA_CADASTRO_APLICACAO 500 Algo inesperado aconteceu e não foi possível realizar o cadastro da aplicação