Get Started with Access Management

Access Management blends the familiar roles-based access control (RBAC) with an overlay of attribute-based access control (ABAC), which has yet to be implemented. Most common authorization use cases, however, can be addressed with RBAC modeling.

In the following sections, we'll use an example solution to guide you through the process. We've organized the steps into three sections that focus on one aspect of access control.

Protecting Your APIs and Resources

1. Add the iam dependency.
2. Map permissions to actions (APIs) and resources (knowledge types).
3. Create roles.
4. Assign permissions to existing roles.

Accessing APIs and Resources of the Platform and Other Solutions

5. Declare permissions to access resources from the platform or other solutions.

Testing APIs

6. Test your APIs and knowledge types.

1. Add the iam Solution as a Dependency

Access Management provides authorization through the solution iam.

Add the iam dependency to your solution's <solutionRoot>/manifest.json file:

Copy{
    "manifestVersion": "1.0.0",
    "name": "dashboard",
    "solutionVersion": "<solution-version>",
    "dependencies": [
        "iam",
        "..."
    ],
    "..."
}

2. Map Your Solution to Access Management Permissions

A permission can either represent an API call or a knowledge type. API calls or knowledge types that don't have permissions cannot be accessed externally. The default permission for Access Management is no-access.

1. Give your permission a descriptive name and use camel case in the <solutionRoot>/objects/permissions.json file, such as readDashboard in this example:

   json

   Copy[
       {
           "name": "readDashboard",
           "..."
        }
    ]
   

2. Choose a consistent naming scheme because the permission name and displayName are part of the request and responses of the Access Management APIs. The value for displayName will be displayed in the UI. We recommend creating displayName by prefixing the solution name (dashboard in this example) and colon to the permission name, as shown here.

   json

   Copy [
        {
            "name": "readDashboard",
            "displayName": "dashboard:readDashboard",
            "description": "Read Dashboard",
            "..."
         }
     ]
   

   Note: The permission ID is made by prefixing the permission name with the solution name and a colon character. So, for a permission with the name readDashboard from a solution called dashboard, the ID will be dashboard:readDashboard. The IDs are used in RoleToPermissionMapping.

3. You can use one permission to represent multiple APIs. The following example uses the permission readDashboard for two API calls: GET /dashboards and GET /dashboard/{id}:

   json

   Copy[
       {
           "name": "readDashboard",
           "displayName": "dashboard:readDashboard",
           "description": "Read Dashboard",
           "actionAndResources": [
               {
                   "action": {
                       "method": "GET",
                       "pathPattern": "/v1/testing/dashboards",
                       "classification": "READ",
                       "type": "HttpAction"
                   }
               },
               {
                   "action": {
                       "method": "GET",
                       "pathPattern": "/v1/testing/dashboards/{id}",
                       "classification": "READ",
                       "type": "HttpAction"
                   }
               }
           ]
       }
   ]
   

   Note: It is illegal to create permissions for the types and APIs not belonging to your solution. While this is not enforced today, we suggest not doing so, as this may break your solution in the future.

4. Create the file <solutionRoot>/objects/permissions.json, and add all the permission objects. The following permission objects create, update, and delete dashboards with the HTTP methods POST, PUT, and DELETE:

   json

   Copy[
       {
           "..."
       },
       {
           "name": "createDashboard",
           "displayName": "dashboard:createDashboard",
           "actionAndResources": [
               {
                   "action": {
                       "method": "POST",
                       "pathPattern": "/v1/testing/dashboards",
                       "classification": "CREATE",
                       "type": "HttpAction"
                   }
               }
           ],
           "description": "dashboard:createDashboard"
       },
       {
           "name": "updateDashboard",
           "displayName": "dashboard:updateDashboard",
           "actionAndResources": [
               {
                   "action": {
                       "method": "PUT",
                       "pathPattern": "/v1/testing/dashboards/{id}",
                       "classification": "UPDATE",
                       "type": "HttpAction"
                   }
               }
           ],
           "description": "dashboard:updateDashboard"
       },
       {
           "name": "deleteDashboard",
           "displayName": "dashboard:deleteDashboard",
           "actionAndResources": [
               {
                   "action": {
                       "method": "DELETE",
                       "pathPattern": "/v1/testing/dashboards/{id}",
                       "classification": "DELETE",
                       "type": "HttpAction"
                   }
               }
           ],
           "description": "dashboard:deleteDashboard"
       }
   ]
   

   Expand to see full code example

   json

   Copy [{
       "name": "readDashboard",
       "displayName": "dashboard:readDashboard",
       "description": "Read Dashboard"
       "actionAndResources": [{
           "action": {
               "method": "GET",
               "pathPattern": "/v1/testing/dashboards",
               "classification": "READ",
               "type": "HttpAction"
           }
       }, {
           "action": {
               "method": "GET",
               "pathPattern": "/v1/testing/dashboards/{id}",
               "classification": "READ",
               "type": "HttpAction"
           }
       }, {
           "action": {
               "classification": "READ"
           },
           # An example of a permission on a KnowledgeStore type called dashboard
           "resource": {
               "type": "dashboard"
           }
       }]
   }, {
       "name": "createDashboard",
       "displayName": "dashboard:createDashboard",
       "actionAndResources": [{
           "action": {
               "method": "POST",
               "pathPattern": "/v1/testing/dashboards",
               "classification": "CREATE",
               "type": "HttpAction"
           }
       }],
       "description": "dashboard:createDashboard"
   }, {
       "name": "updateDashboard",
       "displayName": "dashboard:updateDashboard",
       "actionAndResources": [{
           "action": {
               "method": "PUT",
               "pathPattern": "/v1/testing/dashboards/{id}",
               "classification": "UPDATE",
               "type": "HttpAction"
           }
       }],
       "description": "dashboard:updateDashboard"
   }, {
       "name": "deleteDashboard",
       "displayName": "dashboard:deleteDashboard",
       "actionAndResources": [{
           "action": {
               "method": "DELETE",
               "pathPattern": "/v1/testing/dashboards/{id}",
               "classification": "DELETE",
               "type": "HttpAction"
           }
       }],
       "description": "dashboard:deleteDashboard"
   }]
   
   </details>
   

5. Once you have finished adding permissions to <solutionRoot>/objects/permissions.json, add the path to permissions.json with its type iam:permission to an object in the objects array of your manifest.json:

   json

   Copy{
       "manifestVersion": "1.0.0",
       "name": "dashboard",
       "solutionVersion": "<solution-version>",
       "dependencies": [
           "iam"
       ],
       "objects": [
           {
               "type": "iam:Permission",
               "objectsFile": "objects/permissions.json"
           }
       ]
   }
   

3. Create Roles

Create roles only when necessary. Each new role is a cognitive burden on a customer.

The properties roleName and displayName may appear in APIs or the UI, so choosing a meaningful value for these is better. Also, these follow the same naming conventions and ID generation mechanism as permissions.

1. Create the file <solutionRoot>/objects/roles.json>.

2. Add an object with the name of the role, the displayName of the role, a description, and an array to hold permissions:

   json

   Copy{
       "name": "dashboardAdmin",
       "displayName": "dashboard:dashboardAdmin",
       "description": "Administer your dashboards",
       "permissions": [
       ]
   }
   

3. In the permissions array, enter one object for each permission ID that you defined with the displayName property in <solutionRoot>/objects/permissions.json:

   json

   Copy{
       "name": "dashboardAdmin",
       "displayName": "dashboard:dashboardAdmin",
       "description": "Administer your dashboards",
       "permissions": [
           {
               "id": "dashboard:readDashboard"
           },
           {
               "id": "dashboard:createDashboard"
           },
           {
               "id": "dashboard:updateDashboard"
           },
           {
               "id": "dashboard:deleteDashboard"
           }
       ]
   }
   

   Note: Roles cannot refer to permissions defined in the other solutions.

4. Add objects/roles.json with its type iam:Role to an object in the objects array of the manifest.json file:

   json

   Copy{
       "manifestVersion": "1.0.0",
       "name": "<solution-name>",
       "solutionVersion": "<solution-version>",
       "dependencies": [
           "iam"
       ],
       "objects": [
           {
               "type": "iam:Permission",
               "objectsFile": "objects/permissions.json"
           },
           {
               "type": "iam:Role",
               "objectsFile": "objects/roles.json"
           }
       ]
   }
   

4. Assign Permissions to Existing Roles

You can add permissions to existing roles, allowing solutions to reuse pre-existing roles from other solutions. See the list of available roles.

Note: The role iam:tenantAdmin can access any API or type if a permission has been defined. Thus, you do not need to map the permissions to this role. The role iam:agent, however, does not acquire any permissions; therefore, the role alone cannot provide access to APIs. To make an API or Knowledge Store type available to an agent, you must map the permission to iam:agent role.

If you map permissions to the iam:troubleshooter role, you should map permissions to iam:configmanager , so that this role will get the permissions of the iam:troubleshooter role.

Suppose you map permissions to the iam:observer role. In that case, you should map permissions to iam:configmanager and iam:troubleshooter, so that these roles will get the permissions of the iam:observer role.

Thus, in the following example file of objects/roles.json, the three roles iam:configManager, iam:configManager, and iam:observer are all included in the roles array:

File: objects/roles.json

Copy{
    "name": "mapApisToTroubleshooterAndConfigManager",
    "roles": [
        "iam:configManager",
        "iam:troubleshooter",
        "iam:observer"
    ],
    "permissions": [
        {
            "id": "dashboard:readDashboard"
        },
        {
            "id": "dashboard:createDashboard"
        },
        {
            "id": "dashboard:updateDashboard"
        },
        {
            "id": "dashboard:deleteDashboard"
        }
    ]
}

5. Declare Permissions to Access Resources from the Platform or Other Solutions

You are required to declare a permission for each resource from the platform or other solution that your solution needs to access.

NOTE: This requirement is not currently enforced, but you are recommended to declare the permissions so your solution will be compliant in the future.

For example, if your solution was using the Cisco Observability Platform Health Rules API, you would create a file declaring the required permissions to access the API's resources.

In the example file <solutionRoot>/objects/solution-permissions.json below, the permissions healthruleapiservice:getHealthRule and healthruleapiservice:getHealthRulesV2 are declared to access the the first and second versions of the getHealthRule URI of the Health Rules API.

The property can_access_in_background determines if the request requires user consent or can be made in the background without the user's consent.

File: <solutionRoot>/objects/solution-permissions.json

Copy{
  "permissions": [
    {
      "id": "healthruleapiservice:getHealthRules",
      "can_access_in_background": true
    },
    {
      "id": "healthruleapiservice:getHealthRulesV2",
      "can_access_in_background": false
    }
  ],
  "name": "default"
}

As with the other object files, you will need to add <solutionRoot>/objects/solution-permissions.json to manifest.json:

Copy{
    "manifestVersion": "1.0.0",
    "name": "<solution-name>",
    "solutionVersion": "<solution-version>",
    "dependencies": [
        "iam"
    ],
    "objects": [
        "...",
        {
             "type": "iam:SolutionPermissions",
             "objectsFile": "objects/solution-permissions.json"
        }
    ]
}

6. Test your APIs and Knowledge Store Types

1. Upload your solution to your Tenant.
2. Test both internal and external calls. If you need help, reach out to Customer Support.
3. Notify Customer Support before you promote your solution to production.