Users, Groups, and Policies

Oracle Digital Assistant uses Oracle Cloud Infrastructure Identity and Access Management (IAM) as its base service for authentication and authorization. (Through IAM, you can also set up federation to other identity providers, such as Oracle Identity Cloud Service (IDCS).)

IAM is a policy-based identity service. The tenancy administrator for your organization needs to set up compartments, groups, and policies that control which users can access which resources and how. For an overview of this process, see Setting Up Your Tenancy.

In Digital Assistant, policies control who can develop skills and digital assistants, access Insights data, and call the service's APIs. For details on how policies work, see Getting Started with Policies. For specific details about writing policies, see Policy Reference.

Note

If your Digital Assistant instance is paired with a subscription to a Fusion-based Oracle Cloud Applications service, such as HCM Cloud or Sales Cloud, you do not use IAM to set up permissions for users. Instead, you use Oracle Identity Cloud Service (IDCS). See Assign Users the ServiceDeveloper Role.

Similarly, if you have an instance that was initially provisioned on the Gen 1 cloud infrastructure (in 2019 or before) and then migrated to the Gen 2 infrastructure, you also use IDCS instead of IAM. See Manage User Access in a Migrated Instance.

Digital Assistant Policies

Before you start organizing your users into groups, you should learn the basics on how policies work and decide on what policies you want to apply to which groups of users.

Policies are created with statements that specify resource-types, verbs (which describe the level of access to those resource types), and locations (typically the names of compartments).

For example, you could create a policy statement that enables a group named ServiceDevelopers to be able to use the resource type oda-design in a compartment named MyDigitalAssistantTest.

Resource-Types

This table shows the resource types that are available for Oracle Digital Assistant.

Resource-type Description
oda-instance-resource Enables use of Oracle Digital Assistant APIs. There are three permissions levels (verbs) that you can apply. For details on which endpoints are covered in each permission level (inspect, read, and use), see REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure and click Permissions in the left navigation of the page.
oda-design Enables access to the user interface for skills, digital assistants, and channels. At the read permission level, users can see the artifacts that have been created. At the use level, users can actively develop, test, and deploy these artifacts.
oda-insights Enables access to the user interface for skill and digital assistant Insights.
oda-instances Enables access to the console for Oracle Digital Assistant instances. At the manage permission level, you can create and delete instances.
oda-family This resource type is a superset of the Oracle Digital Assistant resource types. For each verb (inspect, read, use, and manage) that you use with this resource-type in a policy definition, all operations covered by that verb are included. For example, if you have a policy using this resource type and the manage verb, the user(s) that are covered by this policy will have all possible Oracle Digital Assistant permissions.

Verbs

You use verbs in policy definitions to set the permission levels that given user groups have for given resource-types. For example, you would use the read verb to allow read-only access.

Here are the verbs have been defined for the set of Oracle Digital Assistant resource-types.

Verb Description
inspect Generally covers operations that list contents of a resource. This is the verb that provides the most limited access.
read In user interface terms, this generally means read-only access. In API terms, it generally applies to GET operations.
use When applied to resources in the service's user interface, this generally allows developing, testing, and deploying of these resources. At the API level, it generally allows GET, PUT, POST, PATCH, and DELETE operations, with the exception of more high-impact operations (such as creating instances and purging data).
manage Generally allows the user to perform the whole set of a resource type's operations, including high-impact operations such as creating instances and purging data.

Example Set of Policies

The following table illustrates the patterns for IAM policies and provides typical examples for Oracle Digital Assistant.

IAM Policy Pattern for Policy Statement
Policy for Service Administrators
  • Allow group <name_of_your_Service_Administrators_Group> to manage oda-family in compartment <your_digital_assistant_compartment>
Policy for Service Developers
  • Allow group <name_of_your_Service_Developers_Group> to use oda-design in compartment <your_digital_assistant_compartment>
  • Allow group <name_of_your_Service_Developers_Group> to use oda-insights in compartment <your_digital_assistant_compartment>
Policy for Service Business Users
  • Allow group <name_of_your_Service_Business_Users_Group> to read oda-design in compartment <your_digital_assistant_compartment>
  • Allow group <name_of_your_Service_Business_Users_Group> to use oda-insights in compartment <your_digital_assistant_compartment>
Policy for Digital Assistant API Users
  • Allow group <name_of_your_Digital_Assistant_API_Users_Group> to use oda-instance-resource in compartment <your_digital_assistant_compartment>
Note

This statement provides access to all of the Oracle Digital Assistant endpoints. You can also create policies using the inspect and read verbs for more limited access. To see which endpoints are covered by which verbs, see REST API for Oracle Digital Assistant on Oracle Cloud Infrastructure.

Create a Compartment

Compartments enable you to partition resources in Oracle Cloud so that you can better control access to those resources. When you write policies to give users access to a Digital Assistant instance, the compartment name is one of the parts of the policy statement.

Note

You can also write policies that give users access to the resources in the entire tenant, but that is best for very simple setups (such as if you never intend to have more than one Digital Assistant instance.

To create a compartment:

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Compartments.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. Click Create Compartment.
  3. Fill in the required values and click Create Compartment.

Create New IAM Users

If any of your users don't have user accounts yet, create them in IAM.

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Users.

  2. Click Create User.

  3. In the Create User dialog, fill in the necessary details, with special attention to the following:

    • The Name value can be an email address or a unique name. This will be the name that the user uses to log in to the instance.
    • The Email value, which is used for password recovery.
  4. Click Create.

  5. Once the user is created, select the user and click Create/Reset Password.

  6. Click Copy.

  7. Paste the password in a secure place, and then provide it to the user.

    The user will need to log in with that password and then immediately change it.

Create Groups

Groups are collections of users that can be referenced in policies. You create groups to help manage which users get access to what.

Here is an example set of user groups that you could set up.

User Group Description and Purpose
Service Administrators Has complete unfettered access to manage, administer, and develop with the Oracle Digital Assistant service instance.
Service Developer Has privileges to develop and train digital assistants. However, can't delete published digital assistants or skills nor purge data. These privileges are a subset of service administrator privileges.
Service Business Users Mostly read-only access. Can use the skill and digital assistant tester, view Insights reports, and also enhance the training corpus by adding sample utterances (retraining). These privileges are a subset of service developer privileges. Intended for line-of-business users and analysts.
External Service Users Has permissions to call Oracle Digital Assistant REST APIs. There are three different permission levels (the inspect, read, and use verbs) for Oracle Digital Assistant APIs. As such, you may want to create a separate group for two or three of those permission levels.

To create a group:

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity, and then select Groups.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

    A list of the groups in your tenancy is displayed.

  2. Click Create Group.

  3. Enter the following:

    • Name: A unique name for the group. The name must be unique across all groups in your tenancy. You cannot change this later.
    • Description: A friendly description. You can change this later if you want to.
    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  4. Click Create Group.

Add IAM Users to a Group

You'll need to add each user to a group in order to give them access to the service.

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Groups.

    A list of the groups in your tenancy is displayed.

  2. Locate the group in the list.

  3. Click the group.

  4. Click Add User to Group.

  5. Select the user from the drop-down list, and then click Add User.

Map IDCS Users to an IAM Group

If the user accounts for the team members that need to access Digital Assistant have been set up in Oracle Identity Cloud Service (IDCS), you can map those users to an IAM group.

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Federation.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. Click the OracleIdentityCloudService link.

  3. In the left navigation, click Group Mappings.

  4. Click Edit Mapping.

  5. Click Add Mapping.

  6. In the Identity Provider Group field, select the IDCS group for the users that you want to give access to Digital Assistant.

  7. In the OCI Group field, select the IAM group that corresponds with the access that you want to provide for those users.

  8. Click Submit.

Create Policies

You define IAM policies to apply to your user groups.

To create a policy:

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Policies.

    A list of the policies in the compartment you're viewing is displayed.

  2. If you want to attach the policy to a compartment other than the one you're viewing, select the desired compartment from the list on the left. Where the policy is attached controls who can later modify or delete it (see Policy Attachment).

  3. Click Create Policy.

  4. Enter the following:

    • Name: A unique name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later.
    • Description: A friendly description. You can change this later if you want to.
    • Policy Versioning: Select Keep Policy Current if you'd like the policy to stay current with any future changes to the service's definitions of verbs and resources. Or if you'd prefer to limit access according to the definitions that were current on a specific date, select Use Version Date and enter that date in format YYYY-MM-DD format. For more information, see Policy Language Version.
    • Statement: A policy statement. For the correct format to use, see Policy Basics and also Policy Syntax. If you want to add more than one statement, click +.
    • Tags: Optionally, you can apply tags. If you have permissions to create a resource, you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, skip this option (you can apply tags later) or ask your administrator.
  5. Click Create.

The new policy will go into effect typically within 10 seconds.

For an example of how you might define your Oracle Digital Assistant policies, see Example Set of Policies.

For more background on IAM policies, see How Policies Work.

Setup and Policies for Oracle Functions

If you decide to use Oracle Functions to host code custom component code for any of your skills, you need to configure your tenancy for function development. This includes setting up permissions for the developers and giving your Digital Assistant instance permissions to call the functions that contain that code.

Here are the general steps:

  1. Set up compartments for Functions and a virtual cloud network (VCN).
  2. Set up the VCN.
  3. Set up permissions for network access.
  4. Set up permissions for Functions developers.
  5. Set up a dynamic group for your Digital Assistant instance (or instances).
  6. Define a policy to give the dynamic group access to the functions.

The following topics will give you a quick walkthrough of those steps. If you need more background information, see Configuring Your Tenancy for Function Development.

Create Compartment for Functions and Network Resources

In your tenancy, you'll want to have separate compartments for your functions and network resources. This enables you to write specific policies for each.

To create the compartments:

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Compartments.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. Click Create Compartment.
  3. Fill in the required values for the compartment dedicated to Functions and click Create Compartment.
  4. Click Create Compartment again and fill in the values for the compartment that you are dedicating to network resources.

Set Up a Virtual Cloud Network (VCN)

Before your team can create and deploy functions, you need a virtual cloud network (VCN) containing the subnets for your functions.

The easiest way to create the VCN is to use the VCN with Internet Connectivity wizard, which creates the necessary artifacts for you. See Create the VCN and Subnets to Use with Oracle Functions in Oracle Cloud Infrastructure Documentation.

Note

You need to create the VCN in the region where you plan to deploy your functions.

Set Up Network Access Permissions

To set up permissions for users who will manage network resources:

  1. If you haven't already done so, create a group for those users.

    1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity, and then select Groups.

      You might need to use the scroll bar on the left to scroll down to see the menu option.

    2. Click Create Group.

    3. Complete the wizard, making sure that the name for the group is unique across all groups in the tenancy. You can't change this later.

    4. Click Create Group.

  2. Add the appropriate users to the group.
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Groups.

    2. Locate your group for managing network resources and select it.

    3. For each user, click Add User to Group, select the user from the drop-down list, and then click Add User.

  3. Create the required policy for the group:
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Policies.

    2. Click Create Policy.

    3. Complete the wizard, paying particular attention to the following fields:

      • Name: Enter a unique name for the policy. The name must be unique across all policies in your tenancy. You can't change this later.
      • Statement: Add the following policy statement, where you replace <group-name> and <network-resources-compartment-name> with the names of the appropriate user group and compartment, respectively:
        Allow group <group-name> to manage virtual-network-family in compartment <network-resources-compartment-name>
        For further elaboration on the policy format, see Policy Basics and Policy Syntax.

Set Up Permissions for Functions Developers

To set up permissions for the function developers:

  1. If you haven't already done so, create a group for those users.

    1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity, and then select Groups.

      You might need to use the scroll bar on the left to scroll down to see the menu option.

    2. Click Create Group.

    3. Complete the wizard, making sure that the name for the group is unique across all groups in the tenancy. You can't change this later.

    4. Click Create Group.

  2. Add the appropriate users to the group.
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Groups.

    2. Locate the group you just created and select it.

    3. For each user, click Add User to Group, select the user from the drop-down list, and then click Add User.

  3. Create the required policies for the group:
    1. Open the navigation menu. Under Governance and Administration, go to Identity and click Policies.

    2. Click Create Policy.

    3. Complete the wizard, paying particular attention to the following fields:

      • Name: Enter a unique name for the policy. The name must be unique across all policies in your tenancy. You can't change this later.
      • Statement: Add the following policy statements (clicking + for each statement after the first), where you replace <group-name>, <network-resources-compartment-name>, and <functions-compartment-name> with the names of the appropriate user group and compartment:
        Allow group <group-name> to use virtual-network-family in compartment <network-resources-compartment-name>
        Allow group <group-name> to manage functions-family in compartment <functions-compartment-name>
        Allow group <group-name> to read metrics in compartment <functions-compartment-name>
        Allow group <group-name> to manage logging-family in compartment <functions-compartment-name>
        Allow group <group-name> to manage repos in tenancy
        Allow group <group-name> to read objectstorage-namespaces in tenancy
      Note

      The first statement applies to a different compartment than the next three statements. Make sure that the first of these policy statements specifies the compartment that you set up for network resources and the next three statements specify the compartment that you set up for functions development.

Create a Dynamic Group

For functions written in Oracle Functions to work in Digital Assistant, you need to give permissions to the Digital Assistant service instance itself (as opposed to users of the instance). To do so, you first need to create a dynamic group that contains a rule that matches that instance. You can then apply a policy to the dynamic group to give it the desired permissions.

Here are the steps for creating a dynamic group for Digital Assistant instances.

  1. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Dynamic Groups.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  2. Click Create Dynamic Group to open the Create Dynamic Group dialog.
  3. Fill in values for Name and Description.

    The name must be unique across all groups in your tenancy (dynamic groups and user groups). You can't change this later.

  4. In the Matching Rules section, add one or more rules to match the instance or instances that you want to have access to the component.

    You can add rules for instances or for compartments that contain the instances.

    Tip:

    Click the Rule Builder link to get assistance with the rule syntax.

    Here are rules that you could use for Digital Assistant instances in a specific compartment.

    
      resource.type = odainstance,
      resource.compartment.id = <ocid-of-compartment-containing-DigitalAssistant-instance>
    
  5. Click Create.
Example: Dynamic Group for a Single Instance

Here are the steps that you would follow to create a dynamic group for a single Digital Assistant instance.

  1. Get the OCID of your instance. You can do this by following these steps:
    1. From the Infrastructure Console, click the navigation menu Navigation menu icon in the top left corner, scroll down to and expand Data and AI, and select Digital Assistant.
    2. From the Compartments panel, select a compartment.
    3. Select the instance.
    4. In the Instance Information section of the page, click the Copy link for the instance's OCID.
  2. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, click Identity, then click Dynamic Groups.

    You might need to use the scroll bar on the left to scroll down to see the menu option.

  3. Click Create Dynamic Group to open the Create Dynamic Group dialog.
  4. Fill in values for Name and Description.
  5. Click the Rule Builder link.
  6. In the Create Matching Rule dialog, in the Match Instances With field, select Instance OCID.
  7. In the Value field, paste the OCID that you just copied.
  8. Click Add Rule.
  9. Click Create.

Create a Policy to Access Oracle Functions

Once you have a dynamic group for the instance or instances that you want to be able to invoke functions in Oracle Functions, you create a policy for that dynamic group to access the functions:

  1. Open the navigation menu. Under Governance and Administration, go to Identity and click Policies.

    A list of the policies in the compartment you're viewing is displayed.

  2. From the list of compartments, select the compartment to which you want to attach the policy. This controls who can later modify or delete the policy (see Policy Attachment).

  3. Click Create Policy.

  4. Complete the wizard, paying particular attention to the following fields:

    • Name: Enter a unique name for the policy. The name must be unique across all policies in your tenancy. You cannot change this later.
    • Statement: Enter a policy statement with the following format:
      Allow group <name_of_your_dynamic_group> to use fn-invocation in compartment <name_of_your_Functions_compartment>