Keycloak

Para utilizar ou Keycloak com o NetHSM, de forma a armazenar com segurança as chaves privadas no NetHSM e, ao mesmo tempo, permitir que o Keycloak assine tokens de acesso e descodifique JWE, é necessário instalar e configurar este fornecedor de chaves da seguinte forma:

Divulgação sobre IA

Este provedor foi desenvolvido e revisto com um apoio substancial da IA.

Prepare the NetHSM

Prepare o NetHSM da seguinte forma. Consulte a secção administration para obter instruções detalhadas.

  • Se o NetHSM utilizar um certificado autoassinado, registe a sua impressão digital:

    echo | openssl s_client -connect $NETHSM_HOST 2>/dev/null \
  | openssl x509 -fingerprint -sha256 -noout

  • Crie um utilizador com o papel de Operador dedicado ao Keycloak.

  • A extensão Keycloak deteta chaves, mas não as cria. Crie manualmente as chaves pretendidas:

    • O ID da chave deve começar com o prefixo que o reino irá reivindicar. Escolha um esquema de nomenclatura adequado, como kc-<realm>-<purpose>-<year> (por exemplo, kc-staff-sig-rs256-2026, kc-partners-sig-es256-2026, kc-customers-enc-oaep-2026). O ID passa a ser o kid que o Keycloak publica. A futura rotação de chaves é realizada através da adição de novos IDs, razão pela qual sugerimos utilizar o ano como parte do ID da chave.

    • Os mecanismos determinam quais os algoritmos JOSE que a chave pode suportar:

      NetHSM key type and mechanism

      JOSE algorithms served

      RSA + RSA_Signature_PKCS1

      RS256, RS384, RS512 — independente do algoritmo de hash, pelo que uma única chave abrange os três

      RSA + RSA_Signature_PSS_SHA256 / _SHA384 / _SHA512

      PS256 / PS384 / PS512 — apenas o algoritmo a que os nomes dos mecanismos se referem

      EC_P256 / EC_P384 / EC_P521 + ECDSA_Signature

      ES256 / ES384 / ES512 — a curva determina o algoritmo

      Curve25519 + EdDSA_Signature

      EdDSA

      RSA + RSA_Decryption_OAEP_SHA1 / _SHA256

      RSA-OAEP / RSA-OAEP-256, para descodificar JWE recebidos

Instalação

Descarregue o ficheiro JAR do provedor NetHSM do Keycloak ` <https://github.com/Nitrokey/nethsm-keycloak/releases>` __, guarde-o na pasta de provedores do Keycloak, por exemplo, /opt/keycloak/providers/

Recriar o registo de fornecedores: /opt/keycloak/bin/kc.sh build

Configuração

As configurações podem ser definidas no ficheiro ` `` conf/keycloak.conf` ou como variáveis de ambiente. Ambas as formas correspondem às mesmas configurações; as variáveis de ambiente têm prioridade, pelo que os valores não confidenciais podem constar no ficheiro, sendo apenas a frase-passe inserida em tempo de execução.

Utilizando conf/keycloak.conf

spi-keys--nethsm--url=https://nethsm.internal:8443/api/v1
spi-keys--nethsm--username=keycloak
spi-keys--nethsm--passphrase=<passphrase>
spi-keys--nethsm--tls-fingerprints=aabbcc...

Using environment variables

É a opção preferida em implementações em contentores, uma vez que a frase-passe pode ser fornecida a partir de um segredo do Docker ou do Kubernetes, em vez de ser gravada num ficheiro.

KC_SPI_KEYS__NETHSM__URL=https://nethsm.internal:8443/api/v1
KC_SPI_KEYS__NETHSM__USERNAME=keycloak
KC_SPI_KEYS__NETHSM__PASSPHRASE="<passphrase>"
KC_SPI_KEYS__NETHSM__TLS_FINGERPRINTS=aabbcc...

Nota

O nome da variável de ambiente é derivado automaticamente da chave de configuração: anteponha-lhe KC_, converta para maiúsculas e substitua cada - por _. Os sublinhados duplos decorrem da estrutura da chave, spi-<spi-name>--<provider-id>--<option>, que, para esta extensão, é SPI keys, provider nethsm e o nome da opção.

See also all available configuration options.

Restart Keycloak

O perfil de ligação só é lido quando a fábrica de fornecedores é inicializada. Reinicie o Keycloak.

Confirm the server configuration

Verifique o registo de arranque antes de configurar qualquer domínio. Isto permite distinguir um problema de ligação ou de credenciais de um problema de configuração do domínio.

Em caso de sucesso:

NetHSM key provider ready: 1 instance(s), user 'keycloak',
discovery cache PT5M, on-unavailable fail

Otherwise:

Log message

Cause

Não aparece nenhuma mensagem, ou aparece uma linha de depuração a indicar que o fornecedor está inativo

url is not set

NetHSM is not reachable or not Operational at startup

Endereço incorreto, bloqueado por uma firewall, incompatibilidade do PIN do certificado ou o NetHSM está bloqueado ou não foi configurado

NetHSM rejected the configured credential with HTTP 401

Wrong username or passphrase

Adicionar o fornecedor a um domínio

No console de administração, aceda a Definições do Realm → Chaves → Fornecedores, selecione Adicionar fornecedor e selecione nethsm.

Field

Significado

Key use

sig para assinar tokens, enc para descodificar JWEs recebidos

Key ID prefix

Todas as chaves NetHSM cujo ID comece por esta sequência de caracteres são publicadas por este domínio

Algorithm

O algoritmo ao abrigo do qual estas chaves são publicadas

Priority

Consulte Defina a prioridade para um valor superior a 100

Enabled / Active

Ambos têm de estar ativados para que uma chave possa assinar

Um componente publica um algoritmo, à semelhança dos fornecedores de chaves integrados no Keycloak. Um reino que necessite tanto de RS256 como de ES256 tem, portanto, dois componentes. As chaves com o prefixo que não suportem o algoritmo escolhido são ignoradas, pelo que um prefixo pode corresponder, com segurança, a um conjunto misto de chaves.

Cuidado

Não aponte dois componentes para a mesma chave com algoritmos diferentes. Ambos publicariam uma entrada JWKS sob o mesmo kid.

Defina a prioridade acima de 100

Importante

Um reino recém-criado contém quatro fornecedores de chaves gerados — rsa-generated, rsa-enc-generated, hmac-generated e aes-generated — todos com a prioridade 100. O componente NetHSM deve ter uma prioridade mais elevada; caso contrário, o Keycloak continua a assinar com uma chave de software gerada e a configuração parece funcionar.

Um valor de 200 para o NetHSM é um valor predefinido razoável.

Selecione o algoritmo para o reino

Defina Realm Settings → Tokens → Default Signature Algorithm para o algoritmo configurado no componente. Se o realm solicitar um algoritmo que o componente não publique, o Keycloak recorre a uma chave gerada sem reportar um erro.

Verificar

List the published keys:

curl -s https://<keycloak-host>/realms/<realm>/protocol/openid-connect/certs

Os valores « ` » kid` devem corresponder aos IDs das chaves NetHSM.

A verificação definitiva é um token emitido. Solicite um e descodifique o seu cabeçalho:

curl -s \
  -d "client_id=<client>" \
  -d "client_secret=<secret>" \
  -d "grant_type=client_credentials" \
  https://$NETHSM_HOST/realms/<realm>/protocol/openid-connect/token \
| python3 -c 'import sys, json, base64
header = json.load(sys.stdin)["access_token"].split(".")[0]
print(json.loads(base64.urlsafe_b64decode(header + "==")))'

Se kid for o ID da chave do NetHSM, a assinatura foi gerada no interior do HSM. Também pode consultar o registo do NetHSM em paralelo, que deverá apresentar uma chamada correspondente.

Plano para o caso de o NetHSM não estar disponível

Se não for possível estabelecer ligação com o NetHSM e não houver metadados de chaves armazenados em cache, o domínio não dispõe de chaves utilizáveis e a emissão de tokens falha, em vez de se recorrer a uma chave de software gerada.

Aviso

Se o algoritmo de assinatura predefinido de um domínio for gerido por chaves NetHSM e o NetHSM ficar inacessível, também não será possível emitir tokens administrativos para esse domínio. A API de administração fica, então, indisponível para resolver o problema.

A recuperação é efetuada através da configuração do servidor, em vez de através da consola de administração: defina spi-keys--nethsm--on-unavailable=degrade e reinicie, ou desative o componente.

Por este motivo, configure primeiro um domínio de teste e mantenha o domínio master com as chaves geradas pelo próprio Keycloak, para que a consola de administração continue acessível.

Further Details

You find further details here.