Skip to main content

IAM token

IAM token​

The IAM token is a central part in the system. The token is used by the Akkess system and any other service that is integrated. The IAM token can be represented as a signed JSON Web Token, keeping all needed information to know who is calling and what access does the caller have.

The validity of a jwt token can be verified by using the public JWK key that is referenced in the jwt itself.

Characteristics:

  • Issued using a IdP token
  • Used for identifying the calling part and its access rights
  • Place the caller within a tenant
  • Monitoring and auditing
  • Signed

Raw example:
A signed JWT consists of three parts separated by a dot:

  1. Header
  2. Content
  3. Signature
eyJraWQiOiI0NTA3MzkxMC1mNzIyLTQ0MzEtODkyNy0zNTNkNjc2ZDkzYWQiLCJjdHkiOiJ0MSIsImFsZyI6IlJTMjU2In0.eyJqdGkiOiIwY2E2NTdjYy1hYTMwLTRmMjQtYWNkOC02NWQ5YzA3NjMzNzMiLCJpc3MiOiJodHRwczovL2FwaS5ha2tlc3MuaW8vYXV0aG9yaXphdGlvbi92MSIsInN1YiI6IjY2NzNlNmE0NzZkYmUzMjc5Y2VhNzljNyIsImF1ZCI6IjIwMjQtMDYtMjAtZGVtby02NjczZTRiNjBkNWM4NzQxZjVlNTczYjAiLCJleHAiOjE3MjY3NTQ0NTMsImlhdCI6MTcyNjc1MDg1MywiYWNjIjoiNjY2YzA4NDJiYzEzNTY3OTczNzMxYWNmIiwiYXBwIjoiZGVtby02NjczZTNkNzBkNWM4NzQxZjVlNTczYTgiLCJ0aWQiOiIyMDI0LTA2LTIwLWRlbW8tNjY3M2U0YjYwZDVjODc0MWY1ZTU3M2IwIiwiYXJzIjpbeyJyIjpbInJlZ3VsYXItdXNlciJdLCJuIjpbIjY2NzNlNjUxNzZkYmUzMjc5Y2VhNzljMCJdfV19.4rxyDpAncLw8gDkaERO1xITClp6lgPfBHIFZvnA2qli1nC43MHFLna4EFjXNaH6ADiSWhsUR15SvBD-mmYIW44z_gNfKoJeT2ehieC7NmUjgbDdB9xHjVGCIfCwhNBBJIGxRDJB_-KEHNUmEnG0t0vmtlYfQ9lA9nnLjuQKfJ-5MJzYUmDec66k6JuoGg_yYwKyAGN5AHXKaRIzIcsoOexpQuGiUx6JUUIdxo5bg4ASKU_O5HQSgB0KD9nl49NnkT8o6U-6BHeT39zdTnTYDGGuJvng4L6MwUaxakbb31me6vJb7SX6I2CXxpwEfMaix838yDUhBvo60G3fMtYEX6g

Payload example:

{
  "jti": "0ca657cc-aa30-4f24-acd8-65d9c0763373",
  "iss": "https://api.akkess.io/authorization/v1",
  "sub": "6673e6a476dbe3279cea79c7",
  "aud": "2024-06-20-demo-6673e4b60d5c8741f5e573b0",
  "exp": 1726754453,
  "iat": 1726750853,
  "acc": "666c0842bc13567973731acf",
  "app": "demo-6673e3d70d5c8741f5e573a8",
  "tid": "2024-06-20-demo-6673e4b60d5c8741f5e573b0",
  "ars": [
    {
      "r": [
        "regular-user"
      ],
      "n": [
        "6673e65176dbe3279cea79c0"
      ]
    }
  ]
}

Examples of how to verify a JWT token:

The IAM token populates standard JWT attributes accordingly with some extra claims.

Audience​

The audience aud claim in the token holds the tenant identity of the tenant for which the caller have access to.
The tenant identity can be used in your own system to separate users and data in different tenants from each other.

"aud": "63c65dee83abd41be9f61108",

The IAM system is built from the start to support and enable multi-tenancy and relies on the aud claim to enforce tenant isolation.
The same approach can be used in your services to ensure that you don't mix data for different tenants.

Example:

You have a system that supports multi-tenancy. The system stores Foo-data into the database. To ensure that you don't mix data for different tenants you can pick the aud information from the token and store it onto your Foo-data. Like

type Foo = {
  bar: string;
  tenantId: string; // Picked from aud attribute in the token
}

Now you can always add the tenantId to database queries to ensure that tenant's data are isolated.
See our multi-tenancy section for additional information.

Subject​

The subject sub claim in the token is used to identify the originator of the issued token. In Akkess, this is represented by the actorId of an actor. This actorId does not contain any personal information about the caller which makes it easier to maintain privacy regulation.

"sub": "65f2bd99e410a04b36ef3685",

Example:

In your system you store Foo-data. The Foo-data belongs to a user, and you want to connect the data to the user and ensure that the user's identity is unique in the system. You also want to make it easy the keep up with GDPR regulations.

Using the sub attribute you get a system unique anonymized identity which you can add to your stored entity.

type Foo = {
  bar: string;
  userId: string; // Picked from sub attribute in token
}

Access reference sets​

The access reference sets ars claim is an Akkess specific attribute which contains access rights information that the subject (actor) is entitled to.

This information is used for evaluate the permissions that the called API will give to the caller and is picked from the actor accesses which is stored within the actor.

Attributes:

  • r - The calling actor's role
  • n - The nodes the actor has access to with given role. Represented by the node's Ids
  • a - The actors the actor has access to with given role. Represented by the actor's Ids
  • c - The custom resources the actor has access to with given role. Represented by the custom resource's type and value separated by an equal sign, like VIN=4Y1SL65848Z411439

Example:

const nodeAccess = [
  {
    r: ['STUDENT'],
    n: ['63d298bd78a47f40d600bd34']
  }
];

const tenantAccess = [
  {
    r: ['ADMIN']
  }
];

Account​

The account acc claim identifies the Akkess Account the token has been issued from. The account is the top entity in the Akkess system structure.

Example:

"acc": "63c65dee83abd41be9f61104",

Application​

The application app claim keeps the application identity. An account can have one or many application. The application is typically your system. You can for example have different application for different environments like dev, test, prod.

The app attribute could be used for feature toggling - if dev environment turn on the new cool feature. If not - go safe and disable it.

"app": "63c65dee83abd41be9f61106",

Tenant​

The tenant tid claim holds the tenant identity. The tenant is the entity that holds the users and data. You typically want to separate one tenants data from another tenants data and can use this attribute to do so.

"tid": "63c65dee83abd41be9f61108",

JWK​

A JSON web key (JWK) is defined by the JWK specification and is used for verify a JWT token's signature.

The system supports JWKs retrieval and Open Id connect discovery.

Attributes:

  • kid - Identifies the public part of the signing key. Used for validation of token's signature
  • cty - Tells version of content structure
  • alg - Algorithm used for signing the token

Example:

// Audit example
const header = {
  kid: '6e8743b7-5368-46b4-b585-90ac5f28b3b6',
  cty: 'v1',
  alg: 'RS256',
};

Tenant actor affiliation​

As a user you can have access to several Tenants within an Application. A tenant actor affiliations describes the access you have. You fetch the tenant affiliations using your IdP token and supplies the identifier to the Application you want to get information from.

Tenant actor affiliations are primary useful in a multi-tenancy system and could be used for creating a selection page to the user. Using this information the end user may select which tenant to use.

Characteristics:

  • Accessed using IdP token
  • Cross tenant request
  • Used before issuing an IAM token

Example:

// Tenant actor affiliation example
const tenantActorAffiliations = [
  {
    // Account information
    accountId: '63c65dee83abd41be9f61104',
    accountName: 'Connected locks inc account',

    // Application information
    applicationId: '63c65dee83abd41be9f61106',
    applicationName: 'Connected locks application',

    // Tenant information
    tenantId: '63c65dee83abd41be9f61108',
    tenantName: 'Connected locks - production environmet',

    // Actor information
    actorName: 'Jan Johnson',
    actorType: 'USER',
    actorAccesses: [
      {
        role: 'HOUSE_OWNER'
      },
      {
        role: 'HOUSE_ADMIN'
      }
    ]
  }
];
Copyright © 2019 Akkess