Skip to main content

Actor

There are two main entities in the system, actors and nodes.
The Actor represent some kind of end user in the system and can range from a real person to autonomous internet of things devices. There are several attributes for an actor that could keep information about the actor. For example, the actor's name, email, phone number, and more.

Actors have the ability to issue a token. This token allows the actor to perform various actions within the system. These actions can include creating, deleting, updating, and querying other actors or nodes. The specific actions an actor can perform are dependent on their access rights. Data that is produced and owned by the caller is typically connected to the actorId attribute.

An actor needs to enrolled into the system by someone else that have the right to add the actor and its privileges. When enrolling an actor, the callee can choose between associating the new actor with a specific identity or to create an invitation code that could be shared.

note

Akkess has no built-in support for automatic end user communication and identity provider registration. Akkess supports with all needed mechanisms to build such flows - but the actual flow needs to be implemented by your application.

The reasoning behind this is that the actual flow can be very different from application to application and your communication with your end users is a very important part of your application.

Characteristics:

  • Can authenticate and get an access token
  • Is an owner of data in the system
  • Is the author of changes in the system
  • Its access rights are managed by the system
  • Extendable with custom attributes

Examples of actors:

  • Human user
  • System administrator
  • IoT device
  • Vehicle
  • Machine to machine service account

Actor attributes​

Example:

const actor = {
  tenantId: '63c65dee83abd41be9f61108',
  actorId: '63d29842f0abf2120390cc58',
  createdAt: '2023-04-18T07:57:06.25Z',
  createdBy: '63c65dee83abd41be9f61103',
  lastModifiedAt: '2023-05-04T18:53:02.105Z',
  lastModifiedBy: '63c65dee83abd41be9f61103',
  changeId: '7229402262454403085',
  name: 'John Doe',
  description: 'Wanted $1000',
  type: 'USER',
  status: {
    value: 'VERIFIED',
    createdAt: '2023-04-18T07:57:16.554Z',
    createdBy: '63c65dee83abd41be9f61103',
    previousValues: [
      {
        value: 'REGISTERED',
        createdAt: '2023-04-18T07:57:06.25Z',
        createdBy: '63c65dee83abd41be9f61103',
        replacedAt: '2023-04-18T07:57:16.554Z',
        replacedBy: '63c65dee83abd41be9f61103'
      }
    ]
  },
  invites: [
    {
      inviteId: '63d29842f0abf2120390cc5a',
      expireAt: '2023-04-20T07:57:06.25Z',
      status: 'PENDING',
      statusChangedAt: '2023-04-18T07:57:06.25Z',
      statusChangedBy: '63c65dee83abd41be9f61103',
      createdAt: '2023-04-18T07:57:06.25Z',
      createdBy: '63c65dee83abd41be9f61103'
    }
  ],
  accesses: [
    {
      actorAccessId: '63d29842f0abf2120390cc5b',
      role: 'PRISONER',
      resourceType: 'NODE',
      createdAt: '2023-04-18T07:57:06.25Z',
      createdBy: '63c65dee83abd41be9f61103',
      lastModifiedAt: '2023-04-18T07:57:06.25Z',
      lastModifiedBy: '63c65dee83abd41be9f61103',
      accessFrom: '2023-04-18T07:57:06.25Z',
      accessTo: '2040-04-18T07:57:06.25Z',
      resourceNode: {
        nodeId: '63e13d14a235d55909a456e1',
        nodeType: 'PRISON',
        ancestorNodeIds: [
          '63d298bd78a47f40d600bd34'
        ]
      }
    }
  ],
  idpAffiliations: [
    {
      idpAffiliationId: '641319795e00a4761b8fcf9d',
      idpKey: 'idp.google',
      subject: '456179135785642558401',
      username: 'john@doe.com',
      verifiedAt: '2023-04-18T07:57:16.59Z',
      createdAt: '2023-04-18T07:57:06.25Z',
      createdBy: '63d29842f0abf2120390cc58',
      lastModifiedAt: '2023-04-18T07:57:16.653Z',
      lastModifiedBy: '63d29842f0abf2120390cc58'
    }
  ],
  customIds: [
    {
      type: 'SSN',
      value: '123-45-6789'
    }
  ],
  customStrings: [
    {
      type: 'SURNAME',
      value: 'Doe'
    }
  ],
  customStatuses: [
    {
      type: 'JAIL_STATUS',
      value: 'ON_THE_RUN',
      createdAt: '2023-05-04T18:49:57.039Z',
      createdBy: '65f2bd99e410a04b36ef3685',
      statusFrom: '2023-05-04T20:49:00+02:00',
      note: 'Escaped from prison',
      previousValues: [
        {
          value: 'LOCKED_UP',
          statusFrom: '2023-05-01T11:34:00+02:00',
          statusTo: '2023-05-04T20:49:00+02:00',
          createdAt: '2023-05-04T18:49:16.93Z',
          createdBy: '65f2bd99e410a04b36ef3685',
          replacedAt: '2023-05-04T18:49:57.039Z',
          replacedBy: '65f2bd99e410a04b36ef3685'
        }
      ]
    }
  ],
  customAttributes: [
    {
      type: 'METRICS',
      value: {
        height: 182,
        eyeColor: 'blue',
        gender: 'MALE',
        glasses: true
      }
    }
  ]
};

Actor status​

The actor has a life-cycle which can be used to manage and limit the actor's behaviour. The status is updated by the system when different business events occur.

For example, a non-active actor won't get the ars access token attribute populated when issuing a token. Another example could be that only actors that have accepted the privacy policy and terms of service should have the status `ACTIVE.

Characteristics:

  • Manage via business events and set by system
  • Can be queried
  • Supports history
  • Audit

Values:

ValueDescription
REGISTEREDInitial status when an actor is created
VERIFIEDActor becomes verified when the actor successfully manage to create a IAM token.
In verified status the IAM token is not populated with actor's access information.
In other words the token is not yet fully usable.
ACTIVEThe active status is set by client.
When the actor is active the actor is allowed to issue a fully populated IAM token with all available accesses.
The client activates the actor typically after that the actor has accepted needed consents, like privacy policy etc
INACTIVEThe client can de-activate an actor.
An de-activated actor has its all information intact and can be re-activated again.
An de-activated actor cannot issue a IAM token
WITHDRAWNA withdrawn actor is withdrawn from the system.
The only information left in the system is the information defined to be kept during the withdraw operation

Attributes:

  • value - the current status value. Set by a business event on the actor
  • createdAt- timestamp when actor got the status. Set by system
  • createdBy - the actor Id pointing to the actor initiated the business flow setting the status. Picked from IAM token
  • previousValues - an array with previous status values the actor has had. Managed by the system
  • value - the previous status value.
  • createdAt- timestamp when actor got the status at first. Set by system
  • createdBy - the actor Id pointing to the actor initiated the business flow setting the status.
  • replacedAt- timestamp when actor's status was changed and ended. Set by system
  • replacedBy - the actor Id pointing to the actor who ended the status

Example:

const status = {
  value: 'ACTIVE',
  startedAt: '2023-05-01T08:09:12.44Z',
  startedBy: '63d29842f0abf2120390cc58',
  previousValues: [
    {
      value: 'VERIFIED',
      createdAt: '2023-04-18T07:57:16.554Z',
      createdBy: '63d29842f0abf2120390cc58',
      replacedAt: '2023-05-01T08:09:12.44Z',
      replacedBy: '63d29842f0abf2120390cc58'
    },
    {
      value: 'REGISTERED',
      createdAt: '2023-04-18T06:57:06.25Z',
      createdBy: '63d29842f0abf2120390cc58',
      replacedAt: '2023-04-18T07:57:16.554Z',
      replacedBy: '63d29842f0abf2120390cc58'
    }
  ]
};

Actor accesses​

The actor accesses hold information about the actor's roles and relations in within the Tenant.
By evaluating the actor's roles you can know which privileges the actor has.

Characteristics:

  • CRUD operations
  • Can be queried
  • Audit

Attributes:

  • actorAccessId - an Id used for managing the access. Created by the system
  • audit - audit information telling who added / updated the access and when
  • accessFrom - a timestamp from when the access applies. If no accessFrom is set the access is valid from the creation time and accessFrom will have same value as createdAt
  • accessTo - a timestamp to when the access ends. Optional
  • role - The role that is given to the actor. The must be one of the configured roles that have been added to the Application see policies for more information.
  • resourceType - the actor is typically connected to a resource with given role. You are actor with role USER on a node representing the headquarters. Any of:
    • NONE- role is not bound to any specific resource. The actor has the role for whole Tenant
    • NODE - role is bound to a node
    • ACTOR - role is bound directly to another actor. Example user X is CARERfor user Y
    • CUSTOM - role is bound to a resource defined out-side of the system. Example user X is OWNER of vehicle with VIN 3B7HF13Z11M269883
  • resourceNode - information pointing out the node that the role is associated with. Only applicable for resource type NODE
    • nodeId - the associated node's Id
    • nodeType - the associated node's type
    • ancestorNodeIds - the node's ancestors Ids. Used to see nodes above in a hierarchy. The node ancestor hierarchy starting with the closet parent and ending with the most distant grandparent. Example ancestorNodeIds[0]- parent, ancestorNodeIds[1]- grandparent
  • resourceActor - information pointing out the actor that the role is associated with. Only applicable for resource type ACTOR
  • actorId - the associated actor's Id
  • actorType - the associated actor's type
  • resourceCustom - information pointing out the custom resource that the role is associated with. Only applicable for resource type CUSTOM
  • type - the associated resource's type
  • value - the value that identifies the associated resource

Example:

const accesses = [
  {
    actorAccessId: '63d29842f0abf2120390cc5b',
    role: 'OWNER',
    resourceType: 'NODE',
    createdAt: '2023-04-18T07:57:06.25Z',
    createdBy: '63d29842f0abf2120390cc58',
    lastModifiedAt: '2023-04-18T07:57:06.25Z',
    lastModifiedBy: '63d29842f0abf2120390cc58',
    resourceNode: {
      nodeId: '63d298bd78a47f40d600bd34',
      nodeType: 'HOUSE',
      ancestorNodeIds: [
        '63d298bd78a47f40d600bd33'
      ]
    }
  },
  {
    actorAccessId: '63d29842f0abf2120390cc5c',
    role: 'DRIVER',
    resourceType: 'CUSTOM',
    createdAt: '2023-04-18T07:57:06.25Z',
    createdBy: '63d29842f0abf2120390cc58',
    lastModifiedAt: '2023-04-18T07:57:06.25Z',
    lastModifiedBy: '63d29842f0abf2120390cc58',
    resourceCustom: {
      type: 'CAR',
      value: '3B7HF13Z11M269883',
    }
  }
];

Actor identity provider affiliations​

An actor needs to issue an IAM token to be able to perform any actions in the system. To be able to issue a token the actor needs to identify itself using a token from a reliable and trusted identity provider. More details about this concept is described in the identity abstraction feature.

The identity provider affiliation keeps the reference between the actor and its identity provider(s).

Characteristics:

  • CRUD operations
  • Can be queried
  • Used during authentication
  • IdP integration details

Attributes:

  • idpAffiliationId - an Id used for managing the affiliation. Created by the system
  • audit - audit information telling who added / updated the access and when
  • idpKey - an identifier that is configured on the Application and points out the IdP that the affiliation is associated with
  • subject - the IdP's identifier for the user. Typically called sub in an OIDC token. Either subject or username or both must be set.
  • username - the user's username within their IdP. Typically, an email address. Either subject or username or both must be set.
  • verifiedAt- a timestamp telling when the actor successfully identified itself for the first time using the IdP affiliation

Example:

const idpAffiliations = [
  {
    idpAffiliationId: '641319795e00a4761b8fcf9d',
    idpKey: 'idp.google',
    subject: '456179135785642558401',
    username: 'john@doe.com',
    verifiedAt: '2023-04-18T07:57:16.59Z',
    createdAt: '2023-04-18T07:57:06.25Z',
    createdBy: '63d29842f0abf2120390cc58',
    lastModifiedAt: '2023-04-18T07:57:16.653Z',
    lastModifiedBy: '63d29842f0abf2120390cc58'
  }
];

Actor invites​

An end user can be invited to your application. The invite itself is a one-time-password that enables the end user to claim the associated actor. In order to successfully claim the actor the caller also needs to authenticate itself using a trusted identity provider. If all steps are completed; then the invite is consumed and a corresponding identity provider affiliation is created for said actor and the authenticated subject.

Characteristics:

  • CRUD operations
  • Can be queried
  • Used during invite flow

Attributes:

  • inviteId - an Id used for managing the invite. Created by the system
  • expireAt - a timestamp for when the invite is no longer valid
  • status - the current status of the invite which can be either of PENDING, CLAIMED or WITHDRAWN
  • statusChangedAt - the timestamp when the current status was set
  • statusChangedBy- the actorId pointing to the actor who set the current status
  • audit - audit information telling who added / updated the access and when

Example:

const invites = [
  {
    inviteId: '641319795e00a4761b8fcf9d',
    expireAt: '2023-04-24T07:57:06.25Z',
    status: 'PENDING',
    statusChangedAt: '2023-04-18T07:57:06.25Z',
    statusChangedBy: '63d29842f0abf2120390cc58',
    createdAt: '2023-04-18T07:57:06.25Z',
    createdBy: '63d29842f0abf2120390cc58'
  }
];
Copyright © 2019 Akkess