Users, Groups, and Policies

Oracle Digital Assistant uses Oracle Cloud Infrastructure Identity and Access Management (IAM) as its base service for authentication and authorization.

IAM comes in two flavors:
  • IAM without Identity Domains. This flavor provides policy-based access. 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 instances that are provisioned without identity domains, 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.

  • IAM with Identity Domains. This flavor provides the possibility of role-based access in addition to policy-based access. To provide role-based access, the tenancy administrator for your organization needs to set up compartments, groups, and roles that control which users can access which resources and how. The process is similar to what is described in Setting Up Your Tenancy, except that you use pre-defined roles instead of writing policy statements.

    The identity domain feature enables you to manage access to Digital Assistant using the same concepts and techniques that you would use if Oracle Identity Cloud Service (IDCS) was your identity provider.

    Note

    It is possible that the Identity Domains feature is not yet available for your tenancy. To determine if your tenancy has been updated with this feature, log into your cloud account, open the console's navigation menu (Navigation menu icon), and select Identity & Security. If you see a Domains link in the Identity section of the page, identity domains are available in your tenancy.

Through IAM, you can also set up federation to other identity providers, such as Oracle Identity Cloud Service (IDCS).

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 Getting Started with Oracle Digital Assistant for Fusion Applications.

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, select Identity & Security, and then click Compartments.
  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. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity & Security, and then 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 & Security, and then click Groups.

    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. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity & Security, and then 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, select Identity & Security, and then click Federation.

  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. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity & Security, and then 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 Compartment drop-down 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, select Identity & Security, and then click Compartments.

  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 & Security, and then click Groups.

    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.
    • 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. From the Infrastructure Console's navigation menu, select Identity & Security, and then 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 & Security, and then click Groups.

    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.
    • 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. From the Infrastructure Console's navigation menu, select Identity & Security, and then 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, select Identity & Security, and then click Dynamic Groups.
  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. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Analytics & AI, and select Digital Assistant (which appears under the AI Services category on the page).
    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. From the Infrastructure Console's navigation menu, select Identity & Security, and then click Dynamic Groups.
  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. In the Infrastructure Console, click Navigation menu icon on the top left to open the navigation menu, select Identity & Security, and then 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 dynamic-group <name_of_your_dynamic_group> to use fn-invocation in compartment <name_of_your_Functions_compartment>

Role-Based Access and Identity Domains

If, when creating a Digital Assistant instance, you have enabled role-based access for that instance, you can assign roles to Oracle Cloud Infrastructure IAM groups and users within an identity domain.

The tenancy in which your Digital Assistant instance is provisioned contains a default identity domain in the root compartment. If the tenancy already existed before the Identity Domains feature was enabled, any users and groups that existed in the tenancy at the time that Identity Domains was enabled will be included in the default identity domain.

You can create additional identity domains for your tenant, either in the root compartment or in other compartments. For example, you might do something like the following:

  • In the root (default) compartment, create a default domain for administrators only.
  • In another compartment (for example, named Dev), create a domain for users and groups in a development environment
  • In another compartment (for example, named Prod), create a domain for users and groups in a production environment.

Create an Identity Domain

  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains .The Domains page is displayed.
  2. If not already selected, select the Compartment where you want to create the domain.
  3. Click Create domain.
  4. Enter required information in the Create domain page. See Creating Identity Domains in the Oracle Cloud Infrastructure documentation.

User Roles in IAM

If your instance of Digital Assistant is set up for role-based access, you give your team members access to the instance by assigning them one of the following roles:

  • ServiceBusinessUser. This role is designed for business users to analyze how the skills and digital assistants are being used. Users with this role can do the following:
    • View skills, digital assistants, and channels that have already been created.
    • Use Insights features for skills and digital assistants, including using the retrainer to add utterances to draft versions of skills.
  • ServiceDeveloper. This role is designed for developers who will be extending, updating, and/or developing skills and digital assistants. Users with this role can:
    • Develop, test, train, and deploy skills and digital assistants and create channels.
    • Use the Insights features for skills and digital assistants, including using the retrainer to add utterances to draft versions of skills.
  • ServiceAdministrator. This role is designed for administrators and gives them permissions to do things such as purge data and delete published skills. Users with this role can:
    • Access the OCI console for Oracle Digital Assistant instances.
    • Develop, test, train, and deploy skills and digital assistants and create channels.
    • Use the Insights features for skills and digital assistants, including using the retrainer to add utterances to draft versions of skills.

Create a User in an Identity Domain

  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. If not already selected, select the Compartment in which the domain that contains the group to which you want to add a new user resides.
  3. In the Name column, click the domain for the group in which you want to create the user.
  4. Click Users.
  5. Click Create user.
  6. In the Create user screen, enter the user's first and last name, and their username, then select the one or more groups to which the user should be assigned.
  7. Click Create.

    The new user is added to the selected group(s) and has permissions assigned to the group by its policy statement.

  8. On the user details page that is displayed, you can edit user information as needed, and reset the user's password.
  9. Provide new users with the credentials they need to sign in to their cloud account. Upon signing in, they will be prompted to enter a new password.

Create a Group in an Identity Domain

  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. If not already selected, select the Compartment in which the domain where you want to create the group resides.
  3. In the Name column, click the domain in which you want to create the group for creating and managing instances.The domain Overview page is displayed.
  4. Click Groups.The Groups page for the domain is displayed.
  5. Click Create group.
  6. In the Create group screen, assign a name to the group (for example, oci-integration-admins), and enter a description.
  7. Click Create.

Assign a Role in an Identity Domain

  1. Open the navigation menu and click Identity & Security. Under Identity, click Domains.
  2. If not already selected, select the Compartment in which the domain that contains the user or group to which you want to assign the Digital Assistant roles resides.
  3. In the Name column, click the domain for the user or group to which you want to assign roles.
  4. In the navigation pane, click Oracle Cloud Services.
  5. In the Name column, click the Digital Assistant instance for which you want to assign group roles.
  6. In the navigation pane, click Application roles.
  7. In the Application roles list, locate the role(s) you want to assign. At the far right, click the menu icon and select Assign groups or Assign users.
  8. Select the user or group to which to assign the service role, and click Assign.