Usar clientes OAuth personalizados com o IAP

Neste documento, descrevemos quando e como usar clientes OAuth personalizados para o 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.

É preciso usar uma configuração OAuth personalizada para:

• Gerencie o acesso a aplicativos com o IAP ativado 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 organização doGoogle Cloud .

• Mostrar informações personalizadas da marca nas telas de permissão durante a autenticação.

É possível configurar clientes OAuth personalizados no IAP ou diretamente na 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 com segurança a chave secreta do cliente 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 de forma programática aplicativos protegidos pelo IAP. 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 configuração programmatic_clients ou um JWT de 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 do cliente
Configuração do OAuth	Configurado pelo Google	Cliente configurado
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 uma chave secreta para cada aplicativo. Em vez disso, ele usa um cliente interno gerenciado pelo Google.

Configurar a página de branding

Para configurar a página de branding personalizado usando o console do Google Cloud , faça o seguinte:

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

   Acessar Branding

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 Informações de contato, insira o e-mail do administrador para entrar em contato com os apps protegidos pelos clientes OAuth. Você vai configurar os clientes OAuth em uma etapa posterior.

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

Configurar clientes OAuth personalizados no IAP

Nesta seção, descrevemos como configurar clientes OAuth personalizados no IAP.

É possível criar um cliente OAuth personalizado para o IAP usando o console doGoogle Cloud das seguintes maneiras:

• Criar um cliente OAuth manualmente: é necessário adicionar o URI de redirecionamento antes de configurar o IAP.

• Criar um cliente OAuth automaticamente usando as credenciais geradas automaticamente do IAP: o IAP cria e configura o cliente OAuth para você e adiciona automaticamente o URI de redirecionamento necessário.

Independentemente do método usado, configure a página de branding antes de criar o cliente OAuth. O formato de URI de redirecionamento obrigatório é mostrado nos dois métodos.

Criar o cliente OAuth personalizado

Nesta seção, descrevemos como criar clientes OAuth personalizados usando o console doGoogle Cloud . É 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 console do Google Cloud , use um dos seguintes métodos:

Método 1: criar um cliente OAuth usando o console do Google Cloud

Use esse método quando quiser criar o cliente OAuth separadamente, talvez antes de configurar o IAP para seus recursos. Para isso, é preciso adicionar manualmente o URI de redirecionamento do IAP.

1. No console do Google Cloud , acesse APIs e serviços > Credenciais.

2. Clique em Criar credenciais e selecione ID do cliente OAuth.

3. Em Tipo de aplicativo, selecione Aplicativo da Web.

4. No campo Nome, insira um nome descritivo para o cliente OAuth.

5. Clique em Criar. Anote o ID do cliente gerado.

6. Depois que o cliente OAuth for criado, acesse a seção URIs de redirecionamento autorizados na página de detalhes do cliente OAuth recém-criado.

7. Clique em Adicionar URI e insira o seguinte URI de redirecionamento autorizado específico do IAP:

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

   Substitua YOUR_CLIENT_ID pelo ID do cliente que você recebeu na etapa anterior.

8. Clique em Salvar.

Método 2: criar um cliente OAuth usando as credenciais geradas automaticamente do IAP

Use esse método para que o IAP crie e configure o cliente OAuth para você e adicione automaticamente o URI de redirecionamento necessário.

1. No console do Google Cloud , 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 console do Google Cloud :

     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 consentimento.

        2. Siga as instruções para configurar a página de branding 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 usar com esse recurso. Na Google Auth Platform, 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 formatado em 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

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

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

1. Para criar o cliente OAuth personalizado, siga as instruções do console doGoogle Cloud 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, siga um destes procedimentos:

      • 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 de --project. Definir clientes OAuth personalizados em um nível da hierarquia de recursos oferece a mesma marca personalizada para todos os serviços executados nesse nível.

      • --folder=FOLDER_ID

      • --organization=ORGANIZATION_ID

      • 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 de --project:

        • --folder=FOLDER_ID

        • --organization=ORGANIZATION_ID

      • RESOURCE_TYPE: substitua por um dos seguintes tipos de recurso, 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 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 do 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 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. Pule esta seção se você usou o método descrito anteriormente neste documento.

App Engine

Nesta seção, descrevemos 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. 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://appengine.googleapis.com/v1/apps/PROJECT_ID?updateMask=iap"
   

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

GKE

Nesta seção, descrevemos como ativar clientes OAuth personalizados no GKE.

Configure the BackendConfig

If you are running GKE clusters version 1.24 or later, you can configure IAP and GKE by using the Kubernetes Gateway API. See Configure IAP for instructions.

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

2. Create a Kubernetes Secret to wrap the OAuth client.

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

   Replace the following:

   • MY_SECRET: The name of the secret to create

   • CLIENT_ID: The OAuth client ID

   • CLIENT_SECRET: The OAuth client secret

   You should receive confirmation, like the following output, that the Secret was successfully created:

   secret "MY_SECRET" created
   

3. Add the OAuth credentials to the BackendConfig.

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

4. Enable IAP by associating Service ports with your BackendConfig. See Associating BackendConfig with your Ingress. One way to make this association is to make all ports for the service default to your BackendConfig, which you can do by adding the following annotation to your Service resource:

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

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.

Troubleshooting

If the secretName you referenced doesn't exist or isn't structured properly, one of the following error messages will display:

• BackendConfig default/config-default is not valid: error retrieving secret "foo": secrets "foo" not found. To resolve this error, make sure that you've created the Kubernetes Secret correctly as described in step 2.

• BackendConfig default/config-default is not valid: secret "foo" missing client_secret data. To resolve this error, make sure that you've created the OAuth credentials correctly. Also, make sure that you referenced the correct client_id and client_secret keys.

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, teste se o IAP o está usando 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 será exibida.