Access control

It is common for multiple team members to collaborate on building an agent and for services to access the agent. Using roles , you can control access and permissions granted to principals .

You can configure access using the Conversational Agents console or by using the Google Cloud console ( visit documentation , open console ) with Identity and Access Management (IAM) . The Google Cloud console is used to grant IAM roles to principals, while the Conversational Agents console is used to grant Conversational Agents (Dialogflow CX) agent roles to principals. Conversational Agents (Dialogflow CX) agent roles are convenient predefined roles defined by Conversational Agents (Dialogflow CX) that restrict access to one agent or the child resources of a specific agent.

There are some situations in which you must use the Google Cloud console:

• IAM Project Owner role is by default granted to the user that created the project that owns the agent. This owner has full access to all agents in the project. If you want to change the project owner, you need to use the Google Cloud console.
• Only agent-level access can be configured through the Dialogflow CX console. If you want to configure project-level access, you need to use the Google Cloud console.
• A subset of IAM roles have corresponding Conversational Agents (Dialogflow CX) agent roles. If you want to grant a project-level or agent-level role that does not exist on the Dialogflow CX console, you need to use the Google Cloud console.
• If you are creating a data store agent with the Vertex AI Conversation user interface , you need to use the Google Cloud console.

If you are using the API, you may also have one or more applications that send requests to an agent. In this case, you can control access with service accounts .

Control access with the Conversational Agents console

The Conversational Agents console allows you to apply convenient agent roles configured for agent-level sharing. These roles correlate to IAM roles with IAM conditions that limit access to the specific agent or a subset of child resources of the agent.

To access agent roles configuration from the Conversational Agents console, you must be granted the Project IAM Admin role for the associated project. This role is granted from the Google Cloud console.

Sharing options are found in the agent's settings. To open the agent sharing settings:

1. Open the Dialogflow CX console .
2. Choose your Google Cloud project.
3. Select your agent.
4. Click Agent Settings.
5. Click the Sharetab.

Add a principal

1. Click Add.
2. Enter the email address for the user, group or service account.
3. Select User, Groupor Service Accountfor the email type.
4. The Dialogflow Readerrole is added by default, which is required for the users to access the Conversational Agents console.
5. Click Add roleunder Assign roles.
6. Select a role type under Type.
7. For the Flow Editorand Environment Editorroles, select specific flows or environments or keep the default Alloption.
8. Optionally, set the expiration date for the role.
9. Click Save.

Change principal roles

1. Click the principal in the list.
2. Update roles for this principal in the pop-up.
3. Click Save.

Remove a principal

1. Find the principal in the list.
2. Click the delete delete button for the principal.
3. Click Ok.

Control access with the Google Cloud console

You can control access with IAM settings. See the IAM quickstart for detailed instructions on adding, editing, and removing permissions.

To access the settings below, open the IAM page in the Google Cloud console.

Add a user or service account to the project

You can provide permissions to either users or service accounts by granting them roles on your Google Cloud project. Users are added by providing their email address. Service accounts are also added by providing their associated email address. You need to add service accounts when you want to use one service account for multiple projects. To find the email address associated with your service account, see the IAM Service Accounts page in the Google Cloud console.

To add a principal:

1. Click the add add button at the top of the page.
2. Enter the principal's email address.
3. Select a role.
4. Click Save.

Change permissions

1. Click the edit edit button for the principal.
2. Select a different role.
3. Click Save.

Remove a principal

1. Click the delete delete button for the principal.

Add a condition to restrict access to one agent

When adding or editing a principal, you can create an IAM condition that restricts access to one agent.

For example:

 {
    "expression": "resource.name.startsWith(\"projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID\")",
    "title": "For Conversational Agents (Dialogflow CX) Agent AGENT_ID"
} 

This condition gives you basic access to a specific agent. For example, a service account with this condition can only call the Conversational Agents (Dialogflow CX) API to access the agent specified in the condition for the project, but not other agents in the project.

To add this condition to a role granted to a principal:

1. Select a principal.
2. Click the edit edit button for the principal.
3. Click Add condition.
4. In the Titlefield, enter For Conversational Agents (Dialogflow CX) Agent AGENT_ID and replace AGENT_ID with your agent ID.
5. You may add any description.
6. Select the Condition editorto create your condition.
7. Add the expression resource.name.startsWith("projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID") , replacing AGENT_ID with your agent ID and PROJECT_ID with your project ID.
8. Click Save.

IAM roles

The following table lists common IAM roles relevant to Conversational Agents (Dialogflow CX). Permission summaries in the table use the following terms:

• Full access: Permission to modify access, create, delete, edit, and read any resource.
• Edit access: Permission to create, delete, edit, and read any resource.
• Session access: Permission to call methods for runtime-only resources during a conversation like detecting intent, updating context, updating session entities, or Agent Assist conversation interactions.
• Read access: Permission to read any resource.

OAuth

If you are using Google client libraries to access Conversational Agents (Dialogflow CX), you do not need to use OAuth directly, because these libraries handle the implementation for you. However, if you are implementing your own client, you may need to implement your own OAuth flow. Access to the Conversational Agents (Dialogflow CX) API requires one of the following OAuth scopes:

• https://www.googleapis.com/auth/cloud-platform (access to all project resources)
• https://www.googleapis.com/auth/dialogflow (access to Conversational Agents (Dialogflow CX) resources)

Requests that involve Cloud Storage access

Some Conversational Agents (Dialogflow CX) requests access objects in Cloud Storage for reading or writing data. When you call one of these requests, Conversational Agents (Dialogflow CX) accesses the Cloud Storage data on the caller's behalf. This means that your request authentication must have permissions to access Conversational Agents (Dialogflow CX) as well as the Cloud Storage objects.

When using a Google client library and IAM roles, see the Cloud Storage access control guide for information on Cloud Storage roles.

When implementing your own client and using OAuth , you must use the following OAuth scope:

• https://www.googleapis.com/auth/cloud-platform (access to all project resources)

Custom roles for playbook tool access

You can provide granular access control for playbook tools by using permissions and custom roles.

You can list the available permissions by visiting the permission search tool and searching for dialogflow.tools .

Using those permissions, you can create custom roles .