Roles and Access Control

This page describes how to define roles and assign permissions to those roles to control access to resources used by the Space Fleet solution. You define the roles and permissions with the Access Management configurations.

You can configure Access Management for controlling access to represent an API call or a knowledge type. This page will focus on the Space Fleet's configuration that controls access to a few REST APIs to get you started.

This page walks you through the following sections:

1. Dependencies
2. Permissions for the API
3. Resources and Actions for the API
4. Permissions in the Manifest
5. Custom Roles (Optional)
6. Mapping of Permissions to Roles
7. Mapping of Roles and Permission in the Manifest

When you're done, see Learn More About Access Management.

1. Dependencies

Access Management is accessed through the solution iam, so it's required.

The Space Fleet's manifest.json file specifies the iam dependency:

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

2. Permissions for the API

The Space Fleet solution groups the permission configurations in the directory <solutionRoot>/objects/iam. You can store your permission files in a directory or even place them in the root directory if you declare the file in manifest.json. Later, you will look at how the Space Fleet declares the permissions file in the manifest.

In the <solutionRoot>//objects/iam/ directory, the Space Fleet defines permissions for launching and relaunching torpedoes in the apis-permissions.json file. The permission's name is canLaunchAndReloadTorpedos.

[
  {
    "name": "canLaunchAndReloadTorpedos",
    "description": "Permissions for launching & reloading torpedoes",
    "displayName": "Launch Torpedos",
    "actionAndResources": [
      "..."
    ]
  }
]

Be sure to use a consistent naming scheme because the permission name and displayName are part of the request and responses of the Access Management APIs. Also, note that the value for displayName will be displayed in the UI.

3. Resources and Actions for the API

The permissions for our APIs are only useful if they are associated with actions (HTTP requests) and resources (URI endpoints). Creating permissions for the types and APIs not belonging to your solution is illegal. Thus, the configuration specifies a path to a relative path, not an absolute URL, with the HTTP/HTTPS protocol.

The Space Fleet solution defines two endpoints for launching and relaunching torpedos. You define resources with actions as objects in the actionAndResources array. Each object provides actions that specify the HTTP method (POST) and path pattern to the resource.

[
  {
    "name": "canLaunchAndReloadTorpedos",
    "description": "Permissions for launching & reloading torpedoes",
    "displayName": "Launch Torpedos",
    "actionAndResources": [
      {
        "action": {
          "type": "HttpAction",
          "classification": "UPDATE",
          "method": "POST",
          "pathPattern": "/spacefleet-rest-endpoints/torpedo/launch"
        }
      },
      {
        "action": {
          "type": "HttpAction",
          "classification": "UPDATE",
          "method": "POST",
          "pathPattern": "/spacefleet-rest-endpoints/torpedo/reload"
        }
      }
    ]
  }
]

4. Permissions in the Manifest

To use the permission, you have to declare the permissions file in the manifest.json file and specify the type as iam:Permission, as you can see in the following manifest.json file of the Space Fleet solution:

{
  "manifestVersion": "1.0.0",
  "name": "spacefleet",
  "solutionVersion": "<solution-version>",
  "dependencies": [
    "...",
    "iam"
  ],
  "description": "Space Fleet reference solution",
  "contact": "support@<your-doain>.com",
  "gitRepoUrl": "<your-git-repo>",
  "readme": "readme.md",
  "objects": [
    "...",
    {
      "type": "iam:Permission",
      "objectsFile": "objects/iam/apis-permissions.json"
    }
  ],
  "types": [
    "..."
  ]
}

5. Custom Roles (Optional)

You should only add custom roles if needed, as they add complexity. The Space Fleet solution uses a couple of simple custom roles that will help illustrate how to create your custom roles.

The Space Fleet solution has the two roles commandingOfficer and crewMember. Naturally, only one will have permission to launch and relaunch torpedoes, but we'll look at the permissions for these roles in the next step.

The Space Fleet solution declares the two roles with two objects in the file <solutionRoot>/objects/iam/roles.json:

[
  {
    "name": "commandingOfficer",
    "displayName": "Commanding Officer",
    "description": "Commanding Officer of the Space Fleet"
  },
  {
    "name": "crewMember",
    "displayName": "Crew Member",
    "description": "A member of the crew"
  }
]

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.

6. Mapping of Permissions to Roles

Because the Space Fleet solution defines resources for launching and relaunching torpedoes, it also defines the permissions for the only role allowed to launch and relaunch torpedos: commandOfficer.

The role-mapping file of the Space Fleet solution (<solutionRoot>/objects/iam/role-to-permission-mappings.json) adds an object defining the permission commandOfficerPermissions. The permission has an id that is assigned to the permission we looked at earlier with the following syntax: <solution_name>:<permission_name>

[
  {
    "name": "commandingOfficerPermissions",
    "roles": [
      "spacefleet:commandingOfficer"
    ],
    "permissions": [
      {
        "id": "spacefleet:canLaunchAndReloadTorpedos"
      }
    ]
  },
  "..."
]

The permission commandOfficerPermissions maps the role spacefleet:commandingOfficer that we just reviewed in the last step and the resource spacefleet:canLaunchAndReloadTorpedos that was defined in the name field of the following <solutionRoot>/objects/iam/apis-permissions.json:

[
  {
    "name": "canLaunchAndReloadTorpedos",
    "description": "Permissions for launching & reloading torpedoes",
    "displayName": "Launch Torpedos",
    "actionAndResources": [
      {
        "action": {
          "type": "HttpAction",
          "classification": "UPDATE",
          "method": "POST",
          "pathPattern": "/spacefleet-rest-endpoints/torpedo/launch"
        }
      },
      {
        "action": {
          "type": "HttpAction",
          "classification": "UPDATE",
          "method": "POST",
          "pathPattern": "/spacefleet-rest-endpoints/torpedo/reload"
        }
      }
    ]
  }
]

7. Mapping of Roles and Permission in the Manifest

As you saw with the API permissions file apis-permisions.json, the Space Fleet solution also declares the roles file <solutionRoot>/objects/iam/roles.json and the permission-mapping file <solutionRoot>/objects/iam/role-to-permission-mappings.json in manifest.json.

Notice that the objects/iam/roles.json is of type iam:Role, and objects/iam/role-to-permission-mappings.json is of type iam:RoleToPermissionMapping.

{
    "manifestVersion": "1.0.0",
    "name": "spacefleet",
    "solutionVersion": "<solution-version>",
    "dependencies": [
        "...",
        "iam"
    ],
    "description": "Space Fleet reference solution",
    "contact": "support@<your-doain>.com",
    "gitRepoUrl": "<your-git-repo>",
    "readme": "readme.md",
    "objects": [
        "...",
        {   
            "type": "iam:Role",
            "objectsFile": "objects/iam/roles.json"
        },   
        {
            "type": "iam:Permission",
            "objectsFile": "objects/iam/apis-permissions.json"
        },
        {
            "type": "iam:RoleToPermissionMapping",
            "objectsFile": "objects/iam/role-to-permission-mappings.json"
        }
    ],
    "types": [
        "..."
    ]
}

Learn More About Access Management

See Access Management for an introduction before viewing the following for more details:

• RBAC Modeling
• Access Management Default Roles