Documentação do Oracle Cloud Infrastructure

Criar e Gerenciar Segredos para uma Instância Digital Twin

Se você receber dados de um dispositivo, deverá usar a autenticação com sua instância de gêmeo digital. Este cenário explica como usar um segredo para autenticar uma instância de gêmeo digital para um dispositivo.

O segredo é a senha do dispositivo. O uso de um segredo não é recomendado para produção; use apenas segredos do vault para testar a configuração. Para produção, use um certificado mTLS para autenticação de instância de gêmeo digital.

Tarefas

  1. Criar um segredo
  2. Criar ou atualizar um ID de autenticação de instância gêmea digital
  3. Enviar dados
  4. Atualizar e Gerenciar Segredos
  5. Diagnóstico e Solução de Problemas
Antes de Começar
  • Certifique-se de ter as permissões necessárias. Um administrador concede acesso criando as políticas necessárias. Para obter mais informações, consulte Pré-requisitos para obter as políticas necessárias para segredos e Detalhes da Política da Plataforma Internet of Things (IoT) para obter as políticas necessárias para recursos do IoT.
  • Adicione essas políticas ao compartimento para permitir o acesso.
    IoT Política de Segredo do Vault de Domínio

    Ao criar uma instância de gêmeo digital se você usar um segredo para autenticação, precisará da política a seguir para que um domínio IoT possa ler o segredo em um vault específico.

    Permitir que qualquer usuário do IoT leia segredos em um compartimento e vault específicos para um domínio do IoT:

    Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
Para criar um segredo, você precisa de um vault e uma chave:
  • Confirme se você tem um vault, consulte Listando Vaults ou crie um vault. Para obter mais informações, consulte Gerenciando Vaults.
    Política do Vault

    Para criar um vault, seu usuário deve adicionar políticas ao compartimento no qual deseja criar um vault e uma chave.

    Vamos a um grupo de usuários gerenciar vaults para um compartimento específico.

    Allow group <group-name> to manage vaults in compartment <compartment-name>
  • Depois de criar um vault, você deverá ter uma chave de criptografia HSM (hardware-protected, symmetric) existente no OCI (Oracle Cloud Infrastructure). Para verificar se você tem uma Chave de criptografia principal, consulte Listando Chaves. Ou para criar uma nova chave, que use o modo de proteção HSM, consulte Criando uma Chave de Criptografia Principal.

    Para obter mais informações, consulte Visão Geral de Vaults e Gerenciamento de Chaves e Rotacionando uma Chave.

    Política de Chave

    Vamos a um grupo de usuários gerenciar chaves para um compartimento específico.

    Allow group <group-name> to manage keys in compartment <compartment-name>

Etapa 1: Criar um Segredo

O segredo de texto sem formatação é a senha do dispositivo. O uso de um segredo não é recomendado para produção; use apenas segredos do vault para testar a configuração.

Quando você se conectar ao dispositivo, use o texto sem formatação conteúdo secreto. Para obter mais informações, consulte Gerenciando Segredos.

  1. Na página da lista Segredos, selecione Criar Segredo. Se precisar de ajuda para localizar a página da lista, consulte Listando Segredos.
  2. Selecione o Compartimento no qual você deseja criar o segredo. A melhor prática é usar o compartimento com os recursos relacionados do IoT.
  3. Informe um Nome para identificar o segredo. de Evite digitar informações confidenciais.
  4. Opcionalmente, você pode informar uma Descrição para ajudar a identificar o segredo.
  5. Selecione o Vault que armazena a chave de criptografia. Se o vault estiver em outro compartimento, use o seletor Compartimento do Vault para especificar o compartimento do vault.
  6. Selecione a Chave de Criptografia mestre que você deseja usar para criptografar o conteúdo do segredo enquanto ele for importado para o vault. Se a chave estiver em outro compartimento, use o seletor Compartimento da Chave de Criptografia para especificar o compartimento da chave de criptografia.
    • A chave deve estar no mesmo vault do segredo.
    • Você deve selecionar uma chave simétrica para criar o segredo. Chaves assimétricas não são suportadas para criação de segredo.
  7. Selecione Geração manual de segredo para fornecer manualmente o conteúdo do segredo. Forneça as seguintes informações:
    • No Modelo de Tipo de Segredo, especifique o formato do conteúdo do segredo que você está fornecendo selecionando um modelo. Você pode fornecer o conteúdo do segredo em texto simples quando usar a Console para criar um segredo do vault ou a versão do segredo do vault, mas é necessário codificar o conteúdo do segredo em base64 para que ele seja enviado ao serviço. A Console codifica automaticamente conteúdos de segredo de texto não criptografado para você.
    • Em Conteúdo do Segredo, informe o conteúdo do segredo. O tamanho máximo permitido para um bundle de segredos é de 25 KB. Posteriormente, quando você enviar dados de e para um dispositivo, use esse segredo de texto sem formatação como a senha do dispositivo.
  8. Na seção Rotação de segredo, forneça os seguintes detalhes:
    • Tipo de sistema de destino: Selecione o tipo de sistema de Destino como Autonomous AI Database ou Function e forneça o id do sistema de Destino correspondente.
    • Id do sistema de destino: O id do sistema é preenchido automaticamente para o tipo de sistema de Destino selecionado.
    • Ativar rotação automática: Marque a caixa de seleção para ativar a rotação automática.
    • Intervalo de rotação: Opcionalmente, selecione o intervalo de Rotação para atualizar o segredo periodicamente.
    Observação

    Se você não especificar o tipo e o id do sistema de destino, a caixa de seleção não será ativada para rotação automática.
  9. Para aplicar uma regra a fim de gerenciar como os segredos do vault são usados, na seção Regras, selecione Outra Regra. Você pode criar uma regra referente à reutilização de conteúdo de segredo nas versões de um segredo ou criar uma regra especificando quando o conteúdo do segredo expirará. Para obter mais informações sobre regras, consulte Regras de Segredo.
    Observação

    A atualização frequente de um segredo com o novo conteúdo do segredo ajuda a manter as credenciais mais seguras dos usuários com intenção maliciosa. Ou, pelo menos, reduz o período durante o qual as credenciais comprometidas podem ser usadas ou reveladas inadvertidamente.
  10. Opcionalmente, para aplicar tags ao segredo, selecione Adicionar tag. Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deverá ter permissões para usar o namespace de tag. Para obter mais informações sobre tags, consulte Tags de Recurso. Se não tiver certeza de que deseja aplicar tags, ignore esta opção (você poderá aplicar tags posteriormente) ou pergunte ao administrador.
  11. Selecione Criar Segredo.

    Para obter uma lista completa de definições, consulte Criar um segredo e, para obter as melhores práticas, consulte Gerenciando Segredos.

Etapa 2: Criar uma Instância Digital Twin com um ID de Autenticação Secreta

Para autenticar um dispositivo para enviar dados, crie uma instância de gêmeo digital usando o parâmetro --auth-id com o <secret-OCID> criado na etapa anterior. Use esse comando e parâmetros para criar uma instância de gêmeo digital que use um segredo para autenticação.

  • Para o valor do parâmetro --external-key, substitua o <device-username-or-generated> pelo nome de usuário do dispositivo ou, se você não incluir a chave externa, ela será gerada e aparecerá na resposta.
  • Substitua o <secret-OCID> pelo OCID do segredo que você deseja usar. 
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <secret-OCID> --external-key <device-username-or-generated>

Para obter uma lista completa de parâmetros da CLI, consulte oci iot digital-twin-instance create e Criando uma Instância Gêmea Digital para obter mais informações.

Como alternativa, você pode atualizar o parâmetro --auth-id de uma instância de gêmeo digital existente com o OCID de um segredo.

Etapa 3: Enviar Dados

Envie dados para testar sua configuração.

O uso de um segredo de vault como senha de dispositivo só é recomendado para teste, não para produção. Para produção, a instância de gêmeo digital deve usar um certificado mTLS para autenticação.

  • Usando o Curl

    Shells de estilo POSIX: Use este comando curl ao usar bash, zsh, Terminal macOS, Linux ou Git Bash no Windows.

    curl 
  -u '<digital-twin-instance-external-key>:<device-password>' \
  -H 'Content-Type: text/plain' \
  -d 'sample data 1' \
  'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'

    Windows PowerShell: Use este comando curl.exe para enviar uma solicitação POST com um corpo de solicitação usando -d.

    curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"

    Ao concluir a Etapa 4: Criar uma Instância Gêmea Digital, se você tiver definido o valor do parâmetro de chave externa com aspas, deverá incluir as aspas ao enviar os dados: "external-key". Para obter informações sobre melhores práticas, consulte Diagnosticando e Solucionando Problemas.

  • Use qualquer cliente MQTT, este exemplo usa MQTTX com as seguintes configurações.

    1. Faça download e configure o MQTTX, siga estas instruções. Consulte Conceitos Básicos do MQTTX. Abra o MQTTX.
    2. Selecione Mais de Nova Conexão para criar uma nova conexão.
    3. Informe o valor <unique-id> da chave externa como o Nome do Usuário. Você pode encontrar a chave externa na resposta oci iot digital-twin-instance create, na Etapa 4: Criar uma Instância Digital Twin anterior:
      "external-key": "<unique-id>"
    4. Insira a senha do dispositivo. Se você estiver testando com um segredo do vault, use o conteúdo do segredo de texto sem formatação. Para um ambiente de produção seguro, use um certificado mTLS.
    5. Informe o Host. Selecione o protocolo mqtts:// na lista drop-down host e informe o host do dispositivo: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com no domínio IoT.
    6. Informe a porta. Por exemplo: 8883
      Observação

      Atualmente, o MQTT Secure (MQTTS) só é suportado usando a porta 8883.
    7. Ative a opção SSL/TLS.
    8. Ative a opção SSL Secure.
    9. Para o Certificado, selecione a opção Certificado do servidor assinado pela CA.
    10. Quando você configurar a conexão MQTTX, escolha o comportamento da sessão intencionalmente. Use clean session para uma reconexão sem monitoramento de estado ou desative a sessão limpa com um ID de cliente estável para uma sessão persistente que retoma as assinaturas existentes. A definição Last-Will-Retain controla apenas se a mensagem Última Vontade é retida e não controla a persistência de assinatura.
    11. Defina o Último QoS como 1.
    12. Selecione Conexão.

    Depois de concluir essas etapas, você terá uma instância de gêmeo digital na plataforma IoT que poderá receber dados de um dispositivo.

Atualizar um Segredo ou Criar um Novo Segredo

Melhores Práticas de Rotação de Segredos

Usar um ciclo de vida definido para rotacionar credenciais do dispositivo armazenadas nos segredos do OCI Vault. Gire o conteúdo do segredo regularmente para reduzir a exposição de credenciais e dar suporte aos requisitos de auditoria/conformidade.

Política de linha de base recomendada: gire o conteúdo do segredo a cada 90 a 180 dias, revise a cadência de rotação anualmente e gire imediatamente quando ocorrer um evento de segurança.

Gire o conteúdo do segredo imediatamente quando o risco mudar, como:

  • Comprometimento de segredo suspeito ou acesso não autorizado.
  • Um incidente de segurança de dispositivo ou integração.
  • Alterações de política ou conformidade que exigem uma vida útil de credencial mais curta.

Quando possível, use a automação para janelas de rotação previsíveis e rotação manual para eventos de emergência.

Atualizar um Segredo Existente (Mesmo OCID do Segredo)

Use a atualização de um segredo existente para rotação. Esta opção mantém o mesmo OCID de segredo e mantém o ciclo de vida:

  • Usando a Console: Crie uma nova versão do segredo e edite as propriedades do segredo, se necessário.
  • Usando a CLI ou a API: Atualize o conteúdo do segredo; o OCI cria automaticamente uma nova versão de segredo.
  • Comportamento de tempo de inatividade zero: O OCID do segredo permanece o mesmo, para que a instância de gêmeo digital possa continuar usando o --auth-id existente.
  • Preparação para rollback: As versões anteriores permanecem disponíveis (a menos que sejam excluídas) para um rollback, se necessário.

Criar um Novo Segredo (Novo OCID do Segredo)

Use um novo segredo quando precisar de um novo OCID de segredo com um ciclo de vida independente. Os casos de uso típicos incluem:

  • Credenciais exclusivas: Um segredo por dispositivo ou por instância de gêmeo digital.
  • Separação de ambientes: Diferentes políticas, compartimentos, vaults ou limites de governança.
  • Novos requisitos de propriedade ou nomenclatura: Limpe a separação para operações e auditoria.

Depois de criar um novo segredo, atualize a instância de gêmeo digital com a nova --auth-id.

Lista de Verificação de Validação Após Rotação do Segredo

  1. Confirme se a nova versão do segredo está ativa e recuperável.
  2. Verifique se a instância do gêmeo digital ainda resolve o --auth-id configurado.
  3. Valide a autenticação do dispositivo e o fluxo de dados por HTTPS ou MQTTS.
  4. Registre a data de rotação, a versão do segredo e os resultados do teste para obter evidências de auditoria.

Para obter controles de ciclo de vida adicionais, consulte Atualizando Regras de um Segredo, Regras de Segredo e Perguntas Frequentes de Segredo.

Diagnosticando e Solucionando Problemas de Erros de Autorização

Erro 404 - Erro de serviço: NotAuthorizedOrNotFound

Se você receber uma mensagem de erro do serviço IoT relacionada à autorização, ela poderá estar relacionada a um segredo ou ao parâmetro --auth-id do ID de autenticação na instância do gêmeo digital. Confirme se os valores estão corretos:

Se você criar uma instância de gêmeo digital com esta resposta 404: 

...ServiceError:
{
    "client_version": "Oracle-PythonSDK/2.161.0, Oracle-PythonCLI/3.68.0",
    "code": "NotAuthorizedOrNotFound",
    "logging_tips": "Please run the OCI CLI command using --debug flag to find more debug information.",
    "message": "Resource Auth id with OCID [ocid1.vaultsecret.oc1.iad.unique-id] not found",
    "opc-request-id": "unique-id",
    "operation_name": "create_digital_twin_instance",
    "request_endpoint": "POST https://iot.region.oci.oraclecloud.com/20250531/digitalTwinInstances",
    "status": 404...

Normalmente é por um destes motivos:

  • O recurso não existe. Para confirmar os segredos aos quais você tem acesso, use o comando oci secrets secret-bundle get, consulte o recurso abaixo.
Use este comando para confirmar os segredos aos quais você tem acesso. Para acessar seus segredos na Console ou na API, consulte Listar os segredos. 
oci secrets secret-bundle get --secret-id ocid1.vaultsecret.oc1.iad.unique-id
  • Você não tem a política correta para o domínio IoT para ler a credencial de segredo do vault. Adicione essa política ao compartimento do vault para que o domínio IoT possa ler segredos em um vault específico. 
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}
  • O segredo pode não estar ativo.