Usar clientes OAuth personalizados com o IAP

Este documento descreve quando e como usar clientes OAuth personalizados para Identity-Aware Proxy (IAP).

Por padrão, o IAP usa clientes OAuth gerenciados pelo Google para autenticar usuários. Os clientes OAuth gerenciados pelo Google só podem ser usados para gerenciar o acesso de usuários internos que estão em uma organização.

É necessário usar uma configuração OAuth personalizada para fazer o seguinte:

• Gerenciar o acesso a aplicativos ativados pelo IAP para usuários externos que estão fora da sua organização.
• Gerenciar o acesso a aplicativos da Web que estão em projetos que não estão em uma Google Cloud organização.
• Mostrar informações de marca personalizadas nas telas de permissão durante a autenticação.

É possível configurar clientes OAuth personalizados no IAP ou diretamente na sua plataforma.

Ao usar clientes OAuth personalizados, é necessário configurar a tela de permissão OAuth. Para que a marca personalizada apareça na tela de permissão, envie seu aplicativo para verificação do Google. Para mais informações sobre o processo de verificação, consulte Como configurar a tela de permissão OAuth.

Ao configurar clientes OAuth personalizados, você é responsável por criar e gerenciar as credenciais, o que inclui armazenar a chave secreta do cliente com segurança e compartilhá-la com clientes autorizados quando necessário.

Comparar clientes OAuth gerenciados pelo Google e clientes OAuth personalizados

Os clientes OAuth gerenciados pelo Google não podem acessar aplicativos protegidos pelo IAP de maneira programática. No entanto, os aplicativos protegidos pelo IAP que usam o cliente OAuth gerenciado pelo Google ainda podem ser acessados de maneira programática usando um cliente OAuth separado configurado pela programmatic_clients definição ou um JWT da conta de serviço.

A tabela a seguir compara o cliente OAuth gerenciado pelo Google e um cliente OAuth personalizado.

	Cliente OAuth gerenciado pelo Google	Cliente OAuth personalizado
Usuários	Somente interno	Parceiros internos e externos
Marca	Google Cloud marca	Marca de propriedade do cliente
Configuração do OAuth	Configurado pelo Google	Configurado pelo cliente
Credenciais do OAuth	Gerenciada pelo Google	Gerenciada pelo cliente
Acesso ao aplicativo	Somente fluxo do navegador	Fluxo do navegador e acesso programático

Importante: o cliente OAuth gerenciado pelo Google não cria um novo cliente OAuth e chave secreta para cada aplicativo. Em vez disso, ele usa um cliente interno gerenciado pelo Google.

Configurar a página de marca

Para configurar a página de marca personalizada usando o Google Cloud console, faça o seguinte:

1. No Google Cloud console do, acesse a página Marca do OAuth:

   Acessar a página de marca

2. Clique em Primeiros passos.

3. Em Nome do app, insira o nome do aplicativo para a tela de permissão.

4. Em E-mail para suporte do usuário, insira o endereço de e-mail do administrador para suporte.

5. Em Público-alvo, selecione Interno para restringir o acesso a usuários da sua organização ou Externo para permitir o acesso a usuários de fora da sua organização.

6. Em Dados de contato, insira o e-mail do administrador para contato com os apps protegidos pelos clientes OAuth. Você configura os clientes OAuth em uma etapa posterior.

7. Para criar a configuração do OAuth, clique em Criar.

Configurar clientes OAuth personalizados no IAP

Esta seção descreve como configurar clientes OAuth personalizados no IAP.

Criar o cliente OAuth personalizado

Esta seção descreve como criar clientes OAuth personalizados usando o Google Cloud console. É possível configurar clientes OAuth personalizados do IAP em qualquer nível da hierarquia de recursos.

Para criar clientes OAuth personalizados para um recurso usando o Google Cloud console, faça o seguinte:

1. No Google Cloud console do, acesse a página IAP.

   Acessar o IAP

2. Na guia Aplicativos, na lista de recursos, encontre o recurso que você quer configurar.

   Para recursos para envolvidos no projeto, faça o seguinte:

   • Crie o cliente OAuth usando o Google Cloud console:

     1. Na coluna Ações, clique em Mais opções > Configurações.

     2. Na caixa de diálogo Configurações, selecione OAuth personalizado.

     3. Se você não tiver configurado uma tela de permissão, faça o seguinte:

        1. Clique em Configurar tela de permissão.

        2. Siga as instruções para configurar a página de marca fornecidas anteriormente neste documento.

     4. Na caixa de diálogo de configurações do IAP, clique em Gerar credenciais automaticamente. O IAP gera um novo cliente OAuth e uma chave secreta para uso com esse recurso. Na plataforma de autenticação do Google, o campo URIs de redirecionamento autorizados contém uma entrada no seguinte formato:

        https://iap.googleapis.com/v1/oauth/clientIds/CLIENT_ID:handleRedirect

     5. Para acessar o ID do cliente e a chave secreta, clique em Fazer o download das credenciais. As credenciais são salvas em um arquivo no formato JSON. Como o arquivo contém credenciais confidenciais para acessar recursos, verifique se ele está protegido ou excluído.

     6. Para salvar a configuração do OAuth do IAP e aplicar o cliente OAuth ao IAP, clique em Salvar.

Aplicar clientes OAuth personalizados ao IAP

Esta seção descreve como aplicar clientes OAuth ao IAP. É possível usar esse método em vez de aplicar os clientes diretamente na sua plataforma.

Importante: recomendamos que os usuários do App Engine e do serviço de back-end usem o método de configuração legada para clientes OAuth personalizados. Se você usar o método descrito nesta seção, seus serviços não vão aparecer na interface do IAP.

1. Para criar o cliente OAuth personalizado, siga as Google Cloud instruções do console fornecidas anteriormente neste documento.

2. Aplique o cliente OAuth personalizado.

   gcloud

   Para aplicar o cliente OAuth personalizado usando a CLI gcloud, faça o seguinte:

   1. Crie um arquivo YAML de configurações.

      cat << EOF > iap-oauth.yaml
      accessSettings:
      oauthSettings:
        clientId: CLIENT_ID
        clientSecret: CLIENT_SECRET
      EOF
      

      Substitua:

      • CLIENT_ID: o ID do cliente das credenciais do OAuth que você gerou anteriormente.
      • CLIENT_SECRET: a chave secreta do cliente das credenciais do OAuth que você gerou anteriormente.

   2. Para definir a configuração do OAuth, faça uma destas ações:

      • Para definir a configuração do OAuth no nível do projeto, execute o seguinte comando:

      gcloud iap settings set iap-oauth.yaml

      Para definir a configuração em outro nível da hierarquia de recursos, use uma das seguintes flags em vez da flag --project. A definição de clientes OAuth personalizados em um nível da hierarquia de recursos fornece a mesma marca personalizada para todos os serviços executados nesse nível.

      * <code>--folder=<var>FOLDER_ID</var></code>
      * <code>--organization=<var>ORGANIZATION_ID</var></code>
      

      • Para definir a configuração em um serviço específico, execute o seguinte comando:

      gcloud iap settings set iap-oauth.yaml \
          --project=PROJECT_ID \
          --resource-type= RESOURCE_TYPE \
          --region=REGION \
          --service=SERVICE_NAME

      Substitua:

      • PROJECT_ID: o ID do recurso do projeto. Para definir a configuração em outro nível, use uma das seguintes flags em vez da flag --project:

        • --folder=FOLDER_ID
        • --organization=ORGANIZATION_ID

      • RESOURCE_TYPE: substitua por um dos seguintes tipos de recursos, dependendo do recurso:

        • app-engine
        • backend-services
        • cloud-run
        • compute
        • folder
        • forwarding-rule
        • iap_web
        • organization

      • REGION: a região em que você executa o serviço do Cloud Run.

      • SERVICE_NAME: o nome do seu serviço.

   Terraform

   Para aplicar o cliente OAuth personalizado usando o Terraform, faça o seguinte:

   resource "google_iap_settings" "iap_settings" {
   name = IAP_RESOURCE_NAME
   access_settings {
     oauth_settings {
         oauth_client_id = CLIENT_ID
         oauth_client_secret = CLIENT_SECRET
     }
   }
   }
   

   Substitua:

   • IAP_RESOURCE_NAME: o nome do recurso iap_settings para o serviço, que tem o seguinte formato: projects/PROJECT_NUMBER/iap_web/REGION/services/SERVICE_NAME
   • CLIENT_ID: o ID do cliente das credenciais do OAuth que você gerou anteriormente
   • CLIENT_SECRET: a chave secreta do cliente das credenciais do OAuth que você gerou anteriormente

   API REST

   1. Crie um arquivo JSON de configurações.

      cat << EOF > iap-oauth.json
      {
      "accessSettings": {
        "oauthSettings": {
          "clientId": "CLIENT_ID",
          "clientSecret": "CLIENT_SECRET"
        }
      }
      }
      EOF

      Substitua:

      • CLIENT_ID: o ID do cliente das credenciais do OAuth que você gerou anteriormente.
      • CLIENT_SECRET: a chave secreta do cliente das credenciais do OAuth que você gerou anteriormente.

   2. Aplique o arquivo de configurações.

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"
      -H "Content-Type: application/yaml" \
      "https://iap.googleapis.com/v1/projects/cb-managed-ingress-demo/iap_web/forwarding_rule-us-central1/services/psc-fr:iapSettings?update_mask=iapSettings.accessSettings.oauthSettings.oauthClientId,iapSettings.accessSettings.oauthSettings.oauthClientSecret" \
      -d @iap-oauth.json
      

Para testar se os aplicativos da Web estão protegidos pelo IAP com os clientes OAuth, consulte Testar o acesso.

Configuração legada de clientes OAuth personalizados em um recurso

As seções a seguir descrevem métodos legados para configurar clientes OAuth personalizados no IAP para determinados tipos de recursos. Você pode pular esta seção se tiver usado o método descrito anteriormente neste documento.

App Engine

Esta seção descreve como ativar clientes OAuth personalizados no App Engine.

gcloud

Before you set up your project and IAP, you need an up-to-date version of gcloud CLI. For instructions on how to install the gcloud CLI, see Install the gcloud CLI.

1. To authenticate, use the Google Cloud CLI and run the following command.

   gcloud auth login

2. To sign in, follow the URL that appears.
3. After you sign in, copy the verification code that appears and paste it in the command line.
4. Run the following command to specify the project that contains the resource that you want to protect with IAP.

   gcloud config set project PROJECT_ID

5. Follow the instructions in Creating OAuth clients for IAP to configure the OAuth consent screen and create the OAuth client.
6. Save the OAuth client ID and secret.
7. To enable IAP, run the following command.

   gcloud iap web enable \
       --oauth2-client-id=CLIENT_ID \
       --oauth2-client-secret=CLIENT_SECRET \
       --resource-type=app-engine

After you enable IAP, you can use the gcloud CLI to modify the IAP access policy using the IAM role roles/iap.httpsResourceAccessor. Learn more about managing roles and permissions.

API

1. Siga as instruções em Como criar clientes OAuth para IAP para configurar a tela de permissão OAuth e criar o cliente OAuth.

2. Salve o ID e a chave secreta do cliente OAuth.

3. Execute o comando a seguir para preparar um arquivo settings.json.

   cat << EOF > settings.json
   {
   "iap":
     {
       "enabled": true,
       "oauth2ClientId": "CLIENT_ID",
       "oauth2ClientSecret":" CLIENT_SECRET"
     }
   }
   EOF
   

4. Execute o comando a seguir para ativar o IAP.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Accept: application/json" \
   -H "Content-Type: application/json" \
   -d @settings.json \
   "https://appengine.googleapis.com/v1/apps/PROJECT_ID?updateMask=iap"
   

Depois de ativar o IAP, use a Google Cloud CLI para modificar a política de acesso do IAP usando o papel do IAM roles/iap.httpsResourceAccessor. Saiba mais sobre como gerenciar papéis e permissões.

GKE

Esta seção descreve como ativar clientes OAuth personalizados no GKE.

Configurar o BackendConfig

Se você estiver executando clusters do GKE versão 1.24 ou mais recente, poderá configurar o IAP e o GKE usando a API Gateway do Kubernetes. Consulte Configurar o IAP para instruções.

1. Siga as instruções em Como criar clientes OAuth para IAP para configurar a tela de permissão OAuth e criar o cliente OAuth.

2. Crie um objeto Secret do Kubernetes para encapsular o cliente OAuth.

   kubectl create secret generic MY_SECRET --from-literal=client_id=CLIENT_ID \
     --from-literal=client_secret=CLIENT_SECRET
   

   Substitua:
   • MY_SECRET: o nome do secret a ser criado
   • CLIENT_ID: o ID do cliente OAuth
   • CLIENT_SECRET: a chave secreta do cliente OAuth

   Você vai receber uma confirmação, como a saída a seguir, de que o secret foi criado:

   secret "MY_SECRET" created
   

3. Adicione as credenciais do OAuth ao BackendConfig.

   apiVersion: cloud.google.com/v1
   kind: BackendConfig
   metadata:
     name: CONFIG_DEFAULT
     namespace: my-namespace
   spec:
   iap:
     enabled: true
     oauthclientCredentials:
       secretName: MY_SECRET
   

4. Ative o IAP associando portas de serviço ao BackendConfig. Consulte Como associar o BackendConfig ao Ingress. Uma forma de fazer essa associação é tornar todas as portas de serviço como padrão para seu BackendConfig. Para isso, inclua a anotação a seguir no recurso Service:

   metadata:
     annotations:
         beta.cloud.google.com/backend-config: '{"default": "CONFIG_DEFAULT"}}'
   

Depois de ativar o IAP, use a CLI gcloud para modificar a política de acesso do IAP usando o papel do IAM roles/iap.httpsResourceAccessor. Saiba mais sobre como gerenciar papéis e permissões.

Solução de problemas

Se o secretName referenciado não existir ou não estiver estruturado corretamente, uma das mensagens de erro a seguir será exibida:

• BackendConfig default/config-default is not valid: error retrieving secret "foo": secrets "foo" not found. Para resolver esse erro, verifique se você criou o objeto Secret do Kubernetes corretamente, conforme descrito na etapa 2.

• BackendConfig default/config-default is not valid: secret "foo" missing client_secret data. Para resolver esse erro, verifique se você criou as credenciais do OAuth corretamente. Além disso, verifique se você referenciou corretamente as chaves client_id e client_secret.

Serviço de back-end de balanceador de carga

Para usuários do Compute Engine e do Cloud Run, esta seção descreve como configurar clientes OAuth no IAP para o serviço de back-end do balanceador de carga.

gcloud

Before you set up your project and IAP, you need an up-to-date version of the gcloud CLI. For instructions on how to install the gcloud CLI, see Install the gcloud CLI.

1. To authenticate, use the Google Cloud CLI and run the following command.

   gcloud auth login

2. To sign in, follow the URL that appears.
3. After you sign in, copy the verification code that appears and paste it in the command line.
4. Run the following command to specify the project that contains the resource that you want to protect with IAP.

   gcloud config set project PROJECT_ID

5. Follow the instructions in Creating OAuth clients for IAP. to configure the OAuth consent screen and create the OAuth client.
6. Save the OAuth client ID and secret.
7. To enable IAP, run either the globally or regionally scoped command.
   
   Global scope

   gcloud compute backend-services update BACKEND_SERVICE_NAME \
       --global \
       --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET

   Regional scope

   gcloud compute backend-services update BACKEND_SERVICE_NAME \
       --region REGION_NAME \
       --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET
       

After you enable IAP, you can use the gcloud CLI to modify the IAP access policy using the IAM role roles/iap.httpsResourceAccessor. Learn more about managing roles and permissions.

API

1. Follow the instructions in Creating OAuth clients for IAP to configure the OAuth consent screen and create the OAuth client.

2. Save the OAuth client ID and secret.

3. Run the following command to prepare a settings.json file.

   cat << EOF > settings.json
   {
   "iap":
     {
       "enabled": true,
       "oauth2ClientId": "CLIENT_ID",
       "oauth2ClientSecret": "CLIENT_SECRET"
     }
   }
   EOF
   

4. Run the following command to enable IAP.

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "Accept: application/json" \
   -H "Content-Type: application/json" \
   -d @settings.json \
   "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/REGION/backendServices/BACKEND_SERVICE_NAME"
   

After you enable IAP, you can use the gcloud CLI to modify the IAP access policy using the IAM role roles/iap.httpsResourceAccessor. Learn more about managing roles and permissions.

Testar o acesso

Depois de configurar o cliente OAuth personalizado, você pode testar se o IAP está usando esse cliente para proteger seu serviço fazendo o seguinte:

1. Na página do IAP, na guia Aplicativos, confira os aplicativos gerenciados pelo IAP.

2. Acesse o URL de um dos aplicativos. Se você estiver acessando o aplicativo pela primeira vez desde que configurou a tela de permissão, ela vai aparecer.