Case studies

Pluggoo

Pluggoo is an AI powered web application helping students to learn vocabularies in different languages.
It covers the main uses cases where:

1. Teachers create a homework with words the students should learn
2. The students can read their homeworks and practice on their words

Pluggoo can also be used for schools or privately where a parent or student would create their own Pluggoo community and manage the homeworks themselves.

Live demo

To view the Pluggoo application you can navigate to the Pluggoo application

Architecture

Pluggoo consists of the following parts:

• FE app - a front end application built in React. FE is responsible for user interaction.
• BE app - a back end application built in Node.js. BE is responsible for data validation, throttling, business logic etc. All sensitive traffic is proxied through BE before Akkess is called. BE also keeps secrets like API keys and is also responsible for integration with other systems.

Pluggoo uses Akkess to storing all of its application data. The data is stored as actors and nodes.
The actors are the users and nodes are used for to represent different entities.

Authentication

Many schools use Chromebooks and Google accounts. Initially Pluggoo will only support Google as IdP. This can easily be extended to support other IdPs in future if needed.

IdP configuration example

The IdP configuration is made via Akkess IAM Console or via Authentication API. The configuration includes the issuer and audience for the IdP. The configuration also includes the mapping of the user's attributes to Akkess actor.

The example below shows the configuration for Google sign-in that will map email in the token to the actor's username attribute and name to the actor's name attribute.

{
  "adapter": "OIDC",
  "name": "Google sign-in",
  "visibility": "PUBLIC",
  "description": "Used for sign-in with Google account",
  "adapterConfigOidc": {
    "issuer": "accounts.google.com",
    "audience": "*******************.apps.googleusercontent.com",
    "usernameMapping": {
      "attribute": "email"
    },
    "nameMapping": {
      "attribute": "name",
      "syncOption": "ALWAYS"
    }
  }
}

Permissions

Pluggoo has a set of custom permissions that are used to show / hide actions in the Pluggoo FE.

For example a GROUP_ADMIN is allowed to add users to a group meanwhile a STUDENT is not allowed to do that. Based on the signed-in user the Pluggoo FE will show / hide the actions.

Pluggoo permissions

• pgoo.community-admin.manage
• pgoo.community.manage
• pgoo.group-admin.manage
• pgoo.group.manage
• pgoo.student.manage
• pgoo.vocab.manage pgoo.vocab.practice

Permission configuration example

Permissions are configured in Akkess using the Akkess Account Console. The example below shows the configuration for the Pluggoo service.

// Endpoint
// policy/v1/applications/{applicationId}/service-definitions?returnUpdated=true

Partial payload

{
  "key": "pgoo",
  "name": "Pluggoo",
  "keyLevelSeparator": ".",
  "permissionDefinitions": [
    {
      "key": "pgoo.community-admin.manage",
      "name": "Community admin",
      "description": "Admin of a community. Is allowed to delete it.",
      "status": "GA"
    },
    {
      "key": "pgoo.community.manage",
      "name": "Manage community",
      "description": "Manage community name and participants",
      "status": "GA"
    },
    {
      "key": "pgoo.group-admin.manage",
      "name": "Manage group admin",
      "description": "Allowed to add and remove group admins",
      "status": "GA"
    },
    {
      "key": "pgoo.group.manage",
      "name": "Manage group",
      "description": "Manage group name and participants",
      "status": "GA"
    },
    {
      "key": "pgoo.student.manage",
      "name": "Manage students",
      "description": "Manage users with role STUDENT",
      "status": "GA"
    },
    {
      "key": "pgoo.vocab.manage",
      "name": "Manage vocabulary homework",
      "status": "GA"
    },
    {
      "key": "pgoo.vocab.practice",
      "name": "Practice vocabulary homework",
      "description": "Allowed read and practice vocabulary homeworks",
      "status": "GA"
    }
  ]
}

Roles

Pluggoo applies access control for the following roles:

• SYSTEM_ADMIN - can do anything and used for support and setting up the system
• COMMUNITY_ADMIN - can manage the community like adding groups, teachers and students and even delete the community
• GROUP_ADMIN - can manage the group like adding students and homeworks
• STUDENT - can read and practice on the homeworks
• BE_SERVICE - need a role used by the backend which is used when enrolling new communities to ensure that the limit of communities per person is not exceeded

STUDENT role configuration example

The STUDENT has a mix of Akkess permissions for managing its actor data - manage myself. The permissions will be evaluated by Akkess when a user tries to access the data.

STUDENT also has a Pluggoo specific permission pgoo.vocab.practice which allows the student to practice on the vocabularies. The permission will be evaluated by Pluggoo FE when a user tries to access the data and hide actions that are not allowed for a STUDENT user.

// Endpoint
policy/v1/applications/{applicationId}/role-definitions?returnUpdated=true

Partial payload

{
  "key": "STUDENT",
  "name": "Student",
  "servicePolicies": [
    {
      "serviceDefinitionSource": "CATALOG",
      "serviceDefinitionKey": "iam.actor",
      "permissions": [
        {
          "key": "permission.actor.myself.deactivate"
        },
        {
          "key": "permission.actor.myself.delete"
        },
        {
          "key": "permission.actor.myself.invite.delete"
        },
        {
          "key": "permission.actor.myself.name.manage"
        },
        {
          "key": "permission.actor.myself.read"
        },
        {
          "key": "permission.actor.myself.withdraw"
        }
      ]
    },
    {
      "serviceDefinitionSource": "CATALOG",
      "serviceDefinitionKey": "iam.node",
      "permissions": [
        {
          "key": "permission.node.read",
          "entities": [
            {
              "key": "entity.node",
              "filterCondition": {
                "fieldCondition": {
                  "field": "type",
                  "operator": "ANY_OF",
                  "values": [
                    "VOCABULARY",
                    "GROUP",
                    "COMMUNITY"
                  ]
                }
              }
            }
          ],
          "rules": [
            {
              "key": "rule.node.access-on-level",
              "operator": "ANY_OF",
              "values": [
                "NODE_DIRECT",
                "NODE_DESCENDANT"
              ]
            }
          ]
        }
      ]
    },
    {
      "serviceDefinitionSource": "APPLICATION",
      "serviceDefinitionKey": "pgoo",
      "permissions": [
        {
          "key": "pgoo.vocab.practice"
        }
      ]
    }
  ]
}

Node types

To store the Pluggoo data, the following Akkess nodes are used. The nodes are organized in a tree structure and the users are added to the nodes to give them access.

• COMMUNITY - represents typically a school or family
• GROUP - represents typically a school class
• VOCABULARY - represents a homework for training words

Lokk

Lokk is a show-case application emulating a wireless lock product where end users may interact with the lock to lock and unlock it. An owner of a lock may associate it with a building and also to grant access to technicians. Additionally, the systems support factories that manufacture the locks and make them available pairing.

Live demo

To view the lokk application you can navigate to the lokk demo portal.

Scenario

In this pre-cooked scenario, we have an user that has a single building and a lock associated with it. You sign in as the user to interact with your lock and see its status. In the second section you are signed in as the lock itself to see the last received signals and update the lock status.

This scenario show case the typical interactions and also how the fine-grained access control is applied to give different roles access to different parts of the system. See the lokk role configuration section below for full details of the roles and their access rights. Please view your network tab in the browser to see the interactions made with the Lokk & Akkess services.

Authentication of the owner and the lock is made using the basic identity provider service and its credentials are exposed in the application itself. These credentials are only used for this demonstration and they have limited access to the system.

Key usages of the Akkess toolbox

• Fine-grained access control is applied to give different roles access to different parts of the system
  • Owners can only access their own locks and buildings
  • Technicians can only access locks in buildings they are assigned to and with limited access to the lock data
• Relies entirely on Akkess for data storage using actor and node services
• Lokk backend for frontend service is used to proxy all calls to Akkess services
  • Ensures that business logic is enforced and that only expected interactions are made
  • The application firewall ensures that no malicious interactions are made on the actor and node services

Components

The lokk application is composed by a portal and a backend service using typescript and react. These are containerized and deployed as separate components using node and nginx. These in turn interact with Akkess IAM services. The image below demonstrates these components and also the roles in the system.

Interactions

The tabs below illustrate some of the typical use cases and interactions in the lokk application.

Login

List

Send

Report

End-to-end

Actor and node configuration

Actor types

• LOCK
• USER
• FACTORY
• SERVICE_ACCOUNT

Node types

• ROOT
• FACTORY
• OWNER_ROOT
• HOUSE
• TECHNICIAN_ROOT

Role configuration

The following roles are used in the lokk application:

• LOCK
• OWNER
• USER
• TECHNICIAN
• SERVICE_FACTORY
• SERVICE_ACCOUNT

Most of them have their data access limited to their respective associated nodes, while the SERVICE_ACCOUNT role have privileged access to enable claiming of locks on behalf of an owner.

Full example of lokk role configuration can be found here: Lokk role configuration

Identity provider configuration

The lokk application relies on the basic identity provider to authenticate end users. This is a simple identity provider that only supports username and password authentication and is only used for testing and demonstration purposes.

Firewall configuration

In the lokk application; none of the calls are made directly to the actor or node service. Instead, all needed interactions are proxied via the lokk backend service which will append a valid firewall authorization key. This ensures that only expected interactions are made on the respective actor and node endpoints and that their respective lokk application data is not manipulated in an unexpected way.

This firewall authorization key is only known to the administrator of the lokk application and is injected into the lokk backend service during deployment.

Tenant setup

A single tenant is used for the lokk application. Different end users / owners are separated by their respective association their respective owner node. Locks are registered in the system by the factory and can be claimed by any owner as long as they know the lock serial number.