Especificação do nível de acesso personalizado

Nesta página, detalhamos os objetos e atributos usados para criar expressões Common Expression Language (CEL) para níveis de acesso personalizados. Exemplos estão incluídos.

Para saber mais sobre o CEL, consulte a definição de linguagem do CEL.

Objetos

O Access Context Manager fornece quatro objetos que contêm atributos de nível de acesso.

Objetos
origin Contém atributos que identificam a origem da solicitação.
request.auth Contém atributos que identificam aspectos de autenticação e autorização da solicitação.
levels Contém atributos para definir dependência em outros níveis de acesso.
device Contém atributos que descrevem o dispositivo de origem da solicitação.

Atributos do origin

Esta seção lista os atributos compatíveis com o objeto origin.

Atributos
ip
Tipo string
Descrição

O endereço IP de origem da solicitação. Se o endereço IP não pode ser determinado, origin.ip avalia a um erro. Recomendamos o uso de inIpRange para verificar se o endereço IP de origem está em um intervalo de endereços IP específico em vez de fazer uma comparação de string.

Exemplo:

inIpRange(origin.ip, ["203.0.113.24"])

region_code
Tipo string
Descrição

O código ISO 3166-1 Alfa-2 para o país ou região de origem da solicitação. Se o código da região não puder ser determinado, origin.region_code vai gerar um erro.

Exemplo:

origin.region_code == "GB"
origin.region_code in ["US", "FR", "JP"]

Atributos do request.auth

Esta seção lista os atributos compatíveis com o objeto request.auth.

Atributos
principal
Tipo string, list(string)
Descrição

O ID exclusivo do usuário que emitiu a solicitação.

O valor de request.auth.principal precisa ser um ou mais IDs de usuário exclusivos. Para conseguir os UUIDs, use a API Admin SDK Directory.

O valor precisa estar no seguinte formato: https://accounts.google.com/UUID

Em que UUID é o UUID de um usuário.

Exemplo:

request.auth.principal == "https://accounts.google.com/1134924314572461055"
request.auth.principal in ["https://accounts.google.com/1134924314572461055", "https://accounts.google.com/3134824314572461115"]

claims.crd_str.pwd
Tipo boolean
Descrição

Usuário autenticado com uma senha.

Exemplo:

request.auth.claims.crd_str.pwd == true

claims.crd_str.push
Tipo boolean
Descrição

Usuário autenticado com uma notificação push para o dispositivo móvel.

Exemplo:

request.auth.claims.crd_str.push == true

claims.crd_str.sms
Tipo boolean
Descrição

Usuário autenticado usando um código enviado para SMS ou por chamada telefônica.

Exemplo:

request.auth.claims.crd_str.sms == true

claims.crd_str.swk
Tipo boolean
Descrição

A verificação em duas etapas usou uma chave de software, como um smartphone, como uma chave de segurança.

Exemplo:

request.auth.claims.crd_str.swk == true

claims.crd_str.hwk
Tipo boolean
Descrição

A verificação em duas etapas usou uma chave de hardware, como a chave Titan do Google.

Exemplo:

request.auth.claims.crd_str.hwk == true

claims.crd_str.otp
Tipo boolean
Descrição

Usuário autenticado com métodos de senha única (Google Authenticator e códigos alternativos).

Exemplo:

request.auth.claims.crd_str.otp == true

claims.crd_str.mfa
Tipo boolean
Descrição

Usuário autenticado com qualquer um dos métodos desta tabela, exceto pwd.

Exemplo:

request.auth.claims.crd_str.mfa == true

Para mais informações sobre a política de força de credenciais, consulte Como configurar uma política de força de credenciais.

Atributo levels

Esta seção lista os atributos compatíveis com o objeto levels.

Atributos
level name
Tipo boolean
Descrição

level name corresponde ao nome de um nível de acesso existente.

Quando usadas, as condições do nível de acesso especificado também precisam ser atendidas além dos outros requisitos do seu nível de acesso personalizado.

Exemplo:

levels.allow_corp_ips

Em que allow_corp_ips é o nome de um nível de acesso.

Atributo device

Esta seção lista os atributos compatíveis com o objeto device. Se não houver dispositivo associados aos identificadores na solicitação, todos os itens a seguir atributos serão avaliados como um erro.

Atributos
encryption_status
Tipo enum
Descrição

Descreve o status de criptografia do dispositivo.

Valores de enumeração:

enum DeviceEncryptionStatus {
  // The encryption status of the device is not specified or not known.
  ENCRYPTION_UNSPECIFIED == 0;
  // The device does not support encryption.
  ENCRYPTION_UNSUPPORTED == 1;
  // The device supports encryption, but is currently unencrypted.
  UNENCRYPTED == 2;
  // The device is encrypted.
  ENCRYPTED == 3;
}

Exemplo:

device.encryption_status == DeviceEncryptionStatus.ENCRYPTED

is_admin_approved_device
Tipo boolean
Descrição

Se o dispositivo foi aprovado pelo administrador do domínio.

Exemplo:

device.is_admin_approved_device == true

is_corp_owned_device
Tipo boolean
Descrição

Se o dispositivo é de propriedade da organização.

Exemplo:

device.is_corp_owned_device == true

is_secured_with_screenlock
Tipo boolean
Descrição

Se o dispositivo está com a função de bloqueio de tela ativada.

Exemplo:

device.is_secured_with_screenlock == true

os_type
Tipo enum
Descrição

Identifica qual sistema operacional o dispositivo está usando.

Valores de enumeração:

enum OsType {
  // The operating system of the device is not specified or not known.
  OS_UNSPECIFIED == 0;
  // A desktop Mac operating system.
  DESKTOP_MAC == 1;
  // A desktop Windows operating system.
  DESKTOP_WINDOWS == 2;
  // A desktop Linux operating system.
  DESKTOP_LINUX == 3;
  // An Android operating system.
  ANDROID == 4;
  // An iOS operating system.
  IOS == 5;
  // A desktop ChromeOS operating system.
  DESKTOP_CHROME_OS == 6;
}

Exemplo:

device.os_type == OsType.DESKTOP_MAC
device.os_type != OsType.OS_UNSPECIFIED

vendors
Tipo map<string, Vendor> vendors;
Descrição

O objeto vendors é usado para acessar dados fornecidos por fornecedores de segurança e gerenciamento de endpoints de terceiros. Cada fornecedor pode preencher três atributos de nível superior compartilhados: is_compliant_device, is_managed_device e device_health_score.

Além disso, os fornecedores podem fornecer as próprias chaves e valores referenciados usando o atributo data. As chaves disponíveis para o atributo data variam de acordo com o fornecedor. Verifique se você está consistente ao comparar o valor da chave na expressão da política. Por exemplo, se você espera que o valor-chave seja uma string ou um booleano, compare-o a uma string ou um booleano na expressão de política correspondente. Quando o valor for um número inteiro, compare-o com um número duplo na expressão de política.

Valores de enumeração:

// Health score of the device as provided by the vendor (possibly third party).
enum DeviceHealthScore {
  // The health score for the device is not specified or unknown.
  DEVICE_HEALTH_SCORE_UNSPECIFIED = 0;
  // The health of the device is very poor.
  VERY_POOR = 1;
  // The health of the device is poor.
  POOR = 2;
  // The health of the device is ok.
  NEUTRAL = 3;
  // The health of the device is good.
  GOOD = 4;
  // The health of the device is very good.
  VERY_GOOD = 5;
}

Exemplos:

device.vendors["some_vendor"].is_compliant_device == true

device.vendors["some_vendor"].is_managed_device == true

device.vendors["some_vendor"].device_health_score == DeviceHealthScore.VERY_GOOD

device.vendors["some_vendor"].data["is_device_compromised"] == true

device.vendors["some_vendor"].data["some_num"] == 1.0

android_device_security.verified_boot
Tipo boolean
Descrição

Indica se o status de inicialização verificada do Android é green.

Exemplo:

device.android_device_security.verified_boot == true

android_device_security.cts_profile_match
Tipo boolean
Descrição

Se o dispositivo passa pela conformidade do perfil do CTS.

Exemplo:

device.android_device_security.cts_profile_match == true

android_device_security.verify_apps_enabled
Tipo boolean
Descrição

Se o dispositivo tem a opção Verificar apps do Google Play Protect ativada.

Exemplo:

device.android_device_security.verify_apps_enabled == true

android_device_security.has_potentially_harmful_apps
Tipo boolean
Descrição

Se apps potencialmente nocivos foram encontrados no dispositivo.

Exemplo:

device.android_device_security.has_potentially_harmful_apps == true
ios_device_security.is_device_jailbroken
Tipo boolean
Descrição

Se o dispositivo iOS foi encontrado com jailbreak.

Exemplo:

device.ios_device_security.is_device_jailbroken == true

verified_chrome_os
Tipo boolean
Descrição

Indica se a solicitação vem de um dispositivo com um Chrome OS verificado.

Exemplo:

device.verified_chrome_os == true

chrome.management_state
Tipo string
Descrição

Se o navegador é gerenciado no nível do navegador ou do perfil e pela empresa no domínio correto.

Um navegador é considerado gerenciado se as políticas são gerenciadas centralmente e enviadas e o domínio do navegador ou perfil gerenciado corresponde ao domínio esperado no servidor.

Confira a seguir os estados de gerenciamento do Chrome disponíveis:

Estado
MANAGED O navegador ou perfil é gerenciado pelo cliente.
UNMANAGED O navegador ou perfil não é gerenciado por nenhum cliente.
MANAGED_BY_OTHER_DOMAIN O navegador ou perfil é gerenciado por outro cliente.
PROFILE_MANAGED O perfil é gerenciado pelo cliente.
BROWSER_MANAGED O navegador é gerenciado pelo cliente.

Exemplo:

device.chrome.management_state in
    [
        ChromeManagementState.CHROME_MANAGEMENT_STATE_BROWSER_MANAGED,
        ChromeManagementState.CHROME_MANAGEMENT_STATE_PROFILE_MANAGED,
    ]

chrome.versionAtLeast
Tipo string
Descrição

O navegador está acima de uma determinada versão mínima.

Exemplo:

device.chrome.versionAtLeast("88.0.4321.44")

chrome.is_realtime_url_check_enabled
Tipo boolean
Descrição

O conector de verificação de URL em tempo real está ativado?

Exemplo:

device.chrome.is_realtime_url_check_enabled == true | false

chrome.is_file_upload_analysis_enabled
Tipo boolean
Descrição

O conector de análise de upload de arquivos está ativado?

Exemplo:

device.chrome.is_file_upload_analysis_enabled == true | false

chrome.is_file_download_analysis_enabled
Tipo boolean
Descrição

O conector de análise de download de arquivos está ativado?

Exemplo:

device.chrome.is_file_download_analysis_enabled == true | false

chrome.is_bulk_data_entry_analysis_enabled
Tipo boolean
Descrição

O conector de análise de texto em massa (colar) está ativado?

Exemplo:

device.chrome.is_bulk_data_entry_analysis_enabled == true | false

chrome.is_security_event_analysis_enabled
Tipo boolean
Descrição

O conector de relatórios de ocorrências de segurança está ativado.

Exemplo:

device.chrome.is_security_event_analysis_enabled == true | false

Funções

O Access Context Manager fornece as seguintes funções para uso nas expressões CEL para níveis de acesso personalizados.

Funções
inIpRange(address, [subnets])
Tipo (string, list(string)) -< boolean
Descrição

Verifica se um endereço IP pertence a uma das sub-redes especificadas.

Exemplo:

inIpRange(origin.ip, ["192.0.2.0/24", "198.51.100.0/24", "203.0.113.0/24"])

device.versionAtLeast(minVersion)
Tipo DeviceType.(string) -> boolean
Descrição

Verifica se o sistema operacional do dispositivo é pelo menos uma determinada versão. Recomendamos que você use essa função com o atributo device.os_type.

Exemplo:

device.versionAtLeast("10.0") == true

certificateBindingState(origin, device)
Tipo (Peer, DeviceType) -> integer
Descrição

Verifica se o certificado do cliente associado à origem corresponde ao dispositivo e informa o estado.

O estado retornado pela função pode ser um dos seguintes:

  • CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE
  • CertificateBindingState.CERT_NOT_MATCHING_EXISTING_DEVICE
  • CertificateBindingState.CERT_STATE_UNKNOWN

Exemplo:

certificateBindingState(origin, device) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE

startsWith()
Tipo string.(string) -&gt; booleano
Descrição

Testa se o operando da string começa com o argumento prefix.

Exemplo:

"Sample string".startsWith("Sample")

endsWith()
Tipo string.(string) -&gt; booleano
Descrição

Testa se o operando de string termina com o argumento de sufixo.

Exemplo:

"Sample string".endsWith("string")

origin.clientCertFingerprint()
Tipo Origin.() -> corda
Descrição

Retorna a impressão digital do certificado associado à origem. Use isso em macros para testar certificados do dispositivo.

Exemplo:

// Checks if the enterprise certificate associated with the origin matches the device.
device.certificates.exists(cert, cert.is_valid && cert.cert_fingerprint == origin.clientCertFingerprint())

Macros para expressões CEL

É possível usar as seguintes macros nas expressões de CEL para níveis de acesso personalizados:

Macro Descrição
has(e.f) Testa se um campo está disponível. Consulte Seleção de campo para mais detalhes. Exemplo:

has({"key": "value"}.key) has(device.vendors.some_vendor)

e.all(x, p) Testa se um predicado contém para todos os elementos de uma lista e ou chaves de um mapa e. Aqui, x é um identificador a ser usado em p, que se vincula ao elemento ou chave. A macro all() combina resultados de predicado por elemento com o operador and (&&). Portanto, se algum predicado for avaliado como falso, a macro será avaliada como falsa, ignorando todos os erros de outros predicados. Exemplo:

Isso retorna "false" porque nem todos os elementos são maiores que 1:
[1,2,3].all(x, x > 1)

e.exists(x, p) É semelhante à macro all(), mas combina os resultados do predicado com o operador or (||). Exemplo:

Isso retorna "true" porque há pelo menos um elemento na lista maior que 1:
[1,2,3].exists(x, x > 1)

Verifica se o certificado empresarial associado ao dispositivo corresponde ao emissor:
device.certificates.exists(cert, cert.is_valid && cert.issuer == "EMAILADDRESS=test_inter1@beyondcorp.in, CN=inter_1, OU=BCEDemo_1, O=BCEDemo, L=NCR, ST=UP, C=IN")

e.exists_one(x, p) É semelhante à macro exists(), mas só avalia como verdadeiro se o predicado de exatamente um elemento ou chave for verdadeiro e o restante for falso. Qualquer outra combinação de resultados booleanos é avaliada como falsa, e qualquer erro de predicado faz com que a macro gere um erro. Exemplo:

Isso retorna "false" porque mais de um elemento é maior que 1:
[1,2,3].exists_one(x, x > 1)

Exemplo de expressões CEL

Esta seção inclui exemplos de expressões CEL usadas para criar níveis de acesso personalizados.

Exemplo 1

device.encryption_status == DeviceEncryptionStatus.ENCRYPTED && (origin.region_code in ["US"] || device.is_admin_approved_device)

Este exemplo representa um nível de acesso que exige que as seguintes condições sejam atendidas para permitir uma solicitação:

  • O dispositivo de origem da solicitação é criptografado.

  • Um ou mais dos itens a seguir são verdadeiros:

    • A solicitação foi originada nos Estados Unidos.

    • O dispositivo de origem da solicitação foi aprovado pelo administrador do domínio.

Exemplo 2

(device.os_type == OsType.DESKTOP_WINDOWS && device.is_corp_owned_device) || (device.os_type == OsType.DESKTOP_MAC && device.is_admin_approved_device && device.versionAtLeast("10.11.0"))

Este exemplo representa um nível de acesso que exige que as seguintes condições sejam atendidas para permitir uma solicitação:

  • Um dos seguintes itens é verdadeiro:

    • O dispositivo de origem da solicitação usa um sistema operacional Windows para computador e pertence à sua organização.

    • O dispositivo de origem da solicitação usa um sistema operacional Mac para computadores, é aprovado pelo administrador do domínio e está usando pelo menos o MacOS 10.11.

Exemplo 3

(certificateBindingState(origin, device) == CertificateBindingState.CERT_MATCHES_EXISTING_DEVICE)

Este exemplo representa um nível de acesso que exige que a condição a seguir seja atendida para permitir uma solicitação:

  • A função de extensão certificateBindingState determina que o certificado apresentado no momento da solicitação corresponde a um dos certificados de dispositivo que foram registrados quando o dispositivo foi inscrito na verificação de endpoints.