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

JWS codificadoJWS decodificado

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 ferramenta Debugger do JWT.io.

Exemplo

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

HTTPcURL

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 e 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