Realms — create and manage users

Realms allow customers to create and manage users in flespi. Each user obtains a token configured according to the realm and user parameters.

• Essentials
• How realms work
• How to create a realm
• How to manage user access
• How to set up SSO authentication
• Realms API
• Troubleshooting

Essentials

Realms are designed to provide user-management functionality in flespi.

Realms support SSO via your identity providers, support custom login and password based authentication of users, can automate subaccounts creation and define various access levels for its users.

Realms are part of Platform API and with realm during user authentication it is possible to issue a token with master-level access to the current account. In order to access them via API or flespi.io panel you have to use master tokens.

How realms work

The main usage is the following: you create a realm and define some users in it. Then it is possible to obtain a flespi token using user credentials (username and password) or via OAuth. This is all done via public realms API. 

In order to use realms API, users should use the realm public ID. It is assigned to each realm automatically upon its creation and cannot be changed. Another way is to log in to the flespi panel using user credentials via https://flespi.io/#/realm/{REALM_PUBLIC_ID}.

Each realm has two main configuration options: token parameters and subaccount policy.

Token parameters define the default parameters: access (Standard, Master, ACL) and TTL of tokens of each user in the realm. 

• Default token parameters defined in the realm can be overridden on a per-user basis. Thus, if the user has its own token parameters, the user obtains a token with such parameters; otherwise the user gets a token with default token parameters defined in the realm. 
• Changing token parameters in the realm will update all the assigned tokens in this realm. While changing the token parameters per user will update the token for this user only.

Subaccount policy defines where each user's token should be created. This basically defines a user's subaccount because each user may create/modify or delete other flespi entities using the provided token if such token allows it to do. Subaccount policy can have the following values:

• Current — all the users' tokens are created in the same subaccount where realm is created

• Selected — all the users' tokens are created in the selected subaccount.

• Auto-created — each user obtains its own subaccount automatically created inside the chosen parent account.

Subaccount policy change is forbidden if the realm has at least one user.

How to create a realm

Open Realms in the Access Management submenu in the left-side menu. Click the “+” button to create a new realm. Specify its Name, provide optional Public information (name, description, and logo), select the Subaccount policy (User's home), and Access level. Click the 'Save + Open' button when you're done.

How to manage user access

To set up a new user account, go to 'Your realm' > Users tab and click the ‘+’ button to create a new one. In the pop-up window, you can specify a username along with a password, and if necessary, change the access level under ‘Token parameters’. Click ‘Save’.

Now you need to share the realm login link with a user. On the 'Your realm' pane, right-click the 'Login' icon in the top-right and select 'Copy link address', or you can use https://flespi.io/#/realm/{public_realm_id}. When the user follows the link, the realm authentication page will appear, asking for a username and password. After that, the user will be prompted to save the token for future use.

How to set up SSO authentication

You can allow users to authenticate with a custom Identity Provider, please refer to the following guides:

• How to set up SSO authentication with Google
• How to set up SSO authentication with GitLab

If you'd like your users to login only with a specific Identity Provider, though having two or more of them set up, you can select a direct link to share. Navigate to 'Your realm' > Users tab. Click on the blue ‘key’ icon for a specific user, and then choose the required Identity Provider from the list. 

When the user clicks on this link, he will be redirected to the Identity Provider authorization page requesting permission to access the account and if the user grants it, the account will be linked with the flespi user account for login. Now, the user can use the direct Realm link as we described above.

Realms API

To perform any operations with the realms, use the realms API. 

E.g., you can create a user using the following POST request.

curl -X POST  --header 'Authorization: FlespiToken XXXXXXXXX'  -d '[{"name":"","password":"","registration":"immediate"}]' 'https://flespi.io/platform/realms/{realm-selector}/users'

Troubleshooting

In case of any issue, please navigate to 'Your realm' > Logs tab, pick up an event and click it for details.

Here's the list of event codes explained to help you with further investigation.

If you accidentally deleted realm you may restore it from recycle bin within 30 days.