Realms

5 min read | Last updated :

Realms are logical partitioning of users and provides user isolation. Each realm has it’s own set of users and authentication providers.

Structure

The realm definition for your product can be viewed at iam/realms.yaml and has the below parameters.

Name	Description
name	name of the realm
default	set to true for default realm
active	true for active realms and set to false to inactivated a realm
providers	list of authentication providers to be enabled for the product

Types of Realms

All products have a default realm or create their own custom realm.

Default Realm

Every product has a default realm called users with users entity. Below are they key fields for users entity

Name	Description	Datatype	Validations	Attributes
id	autogenerated unique id	required , unique
email	user email	string	required, unique, length min 3 & max 255	Use for Identity and Authentication
mobile	user mobile	string	unique	Use for Authentication
firstname	First name of the user	string	length min 3 & max 255	required
middlename	Middle name of the user	string	length min 3 & max 255
lastname	Last name of the user	string	length min 3 & max 255	required
displayname	Display name for the user	string		computed : firstname + ” ” + middlename + ” ” + lastname
active	status of the user	boolean	required	defaultvalue : true
locked	status of the user account	boolean	required	defaultvalue : false
tags	labels that can be associated with the user	array(string)
password	user can create a string of characters that allows access	string
meta	miscellaneous fields	object
properties	user required properties	object

The required authentication providers can be defined under the users realm.

1
iam > realms.yaml
2

3
realms:
4
users:
5
default: true
6
active: true # optional, default is true
7
providers:
8
- password
9
- o365
10
- passwordotp
11
- magicnumbers01
12
...

Custom Realms

At times the fields defined in the default users realm are not sufficient and custom realms and entities need to be defined. Custom realms provides the option to define custom entities and tag them as default realms. Once a realm is defined, it auto applies to all tenants in that environment.

useforauth

Use for authentication will enable a field to be used at the time of login to the application like email, mobile. Any number of fields can be tagged as useforauth.

useforidentity

Identity ensures the user is tracked using this field while using the application. Only one field should be tagged as useforidentity.

NOTE

useforidentity is useful while enabling GDPR for your application where email can be used for authentication and id can be used for identity. When the user needs to be forgotten, only updating users entity is sufficient as the system records all other data with id.

Example - Create a custom realm

Let’s create a custom realm called customers and use id for identity and email,mobile for authentication.

customers.yaml

1
entities:
2
- name: customers
3
  fields:
4
  - name: id
5
    type: ulid
6
    ..
7
    attributes:
8
      useforidentity: true
9
  - name: email
10
    type: string
11
    ...
12
    attributes:
13
      useforauth: true
14
  - name: mobile
15
    type: string
16
    attributes:
17
      useforauth: true
18
  - name: password
19
    type: string
20
  - name: active
21
    type: boolean
22
    validations:
23
    - type: required
24
    defaultvalue: |
25
      true
26
  - name: locked
27
    type: boolean
28
    defaultvalue: |
29
      false

NOTE

Custom entity always extends the default users entity.

Example - Create a Custom Realm

Let’s create a custom entity called customers and create a customer realm for it.

customers.yaml

1
entities:
2
- name: customers
3
  fields:
4
  - name: id
5
    type: ulid
6
    defaultvalue: ulid()
7
  - name: name
8
    type: string
9
    validations:
10
    - type: required
11
    compliances:
12
    - type: nolog
13
  - name: username
14
    type: string
15
  - name: password
16
    type: string
17
    validations:
18
    - type: required
19
      message: Name is required
20
    compliances:
21
    - type: hash
22
      salt: S$gsd#%
23
  - name: email
24
    type: string

realms.yaml

1
realms:
2
  customers:
3
    entity: customers
4
    providers:
5
    - password
6
    - o365

Remote Realms

Remote realms are custom realms created from remote entities. The users created through the remote entity will always be stored in the remote entity itself.

Default Users entity

1
---
2
entities:
3
- name: users
4
  status: active
5
  default-order: id
6
  cdc: typeaudit
7
  inherits: kisai.common
8
  fields:
9
  - name: id
10
    type: ulid
11
    defaultvalue: ulid()
12
    validations:
13
    - type: required
14
    - type: unique
15
      message: id field needs to be unique
16
    - type: final
17
      message: id field cannot be updated
18
  - name: email
19
    type: string
20
    validations:
21
    - type: required
22
    - type: length
23
      min: 3
24
      max: 255
25
    - type: unique
26
    attributes:
27
      useforauth: true
28
      useforidentity: true
29
    compliances:
30
    - type: nolog
31
  - name: mobile
32
    type: string
33
    attributes:
34
      useforauth: true
35
    validations:
36
    - type: unique
37
    compliances:
38
    - type: nolog
39
  - name: meta
40
    type: object
41
    defaultvalue: |
42
      '{}'
43
  - name: properties
44
    type: object
45
    defaultvalue: |
46
      '{}'
47
  - name: firstname
48
    type: string
49
    validations:
50
    - type: required
51
    - type: length
52
      min: 3
53
      max: 255
54
    compliances:
55
    - type: nolog
56
  - name: lastname
57
    type: string
58
    validations:
59
    - type: required
60
    - type: length
61
      min: 3
62
      max: 255
63
    compliances:
64
    - type: nolog
65
  - name: middlename
66
    type: string
67
    validations:
68
    - type: length
69
      max: 255
70
    compliances:
71
    - type: nolog
72
  - name: displayname
73
    type: string
74
    computed: |
75
      firstname + "  " + middlename + " " + lastname
76
  - name: password
77
    type: string
78
    compliances:
79
    - type: hash
80
  - name: active
81
    type: boolean
82
    validations:
83
    - type: required
84
    defaultvalue: |
85
      true
86
  - name: locked
87
    type: boolean
88
    defaultvalue: |
89
      false
90
  - name: tags
91
    type: array(string)