SSO Access Control | FastComments Docs

What is Access Control?

With FastComments SSO Access Control, sometimes referred to as RBAC, users can be restricted to only access certain pages, or comment threads. Additionally, users can only @mention each other in the same group.

In Detail

We can place Users and optionally Pages into groups.

When Users are placed into groups, and Limit Comments by SSO User Groups is enabled in Widget Settings, then users will only see comments from users in their same groups and will only be able to @mention users in the same groups.

Additionally, Pages can be placed into groups, and then users can only access comments for pages they have access to.

We call this "User-Level" groups verses "Page-Level" groups.

So which one is right for you?

Use User-Level Groups if...

You want to use the same urlId value (page URL, or article ID), but restrict comments by group.
For example, you want to have "New User" and "Veteran User" groups, and they should never see each other's comments on the same pages.

Use Page-Level Groups if...

Your groups have specific pages.
For example, users in "Public Pages" group should never view articles on the "Top Secret" articles.

How it Works

FastComments Access Control works by assigning Pages and Users into the desired groups.

A group is simply a string identifier, like GREEN or abc-123.

Users and Pages are not just limited to one group. They are limited to 100 and 1000 groups, respectively.

Accessing Unauthorized Pages

If a user tries to access a page they don't have access to, they will see an error message, like below:

Authorization Failure Example

The message text can be customized.

The Spec

Defining how multiple users interact, and testing it, is complicated. Here is the following spec that we follow for access control, which you may use to test your implementation:

Page with null group ids, user with null group ids - should have access.
Page with null group ids, user with group ids - should have access.
Page with group ids, user with null group ids - should have access.
Page with group ids, user with empty list - should NOT have access.
Page with group ids, user with group ids - intersection exists - should have access.
Page with group ids, user with group ids - intersection does not exist - should NOT have access.
Page with empty list of group ids (nobody has access), user with null - should NOT have access.

SSO User A = No group ids defined (null = full access).
SSO User B = No group ids defined (null = full access).
A can @B.

SSO User A = No group ids defined (null = full access).
SSO User B = Group ids defined.
A can @B.

SSO User A = Group ids defined.
SSO User B = No group ids defined (null = full access).
A can @B.

SSO User A = Group ids = [a].
SSO User B = Group ids = [b].
A can NOT @B.

SSO User A = Group ids = [a].
SSO User B = Group ids = [a, b].
A can @B.

Implementation

Mentioning Users in Other Groups

If two users belong to two different sets of groups, and there is no intersection, they will not be able to @mention each other.

If a user manually types an @mention and submits their comment, it will remain as plain text. The other user will not be tagged.

Maintaining the Groups

Groups are defined using the Pages and SSOUsers API resources, respectively.

The Pages API can be invoked to define the set of groups allowed to access the page. By default, all groups, and users that do not belong to a group, have access.

Similarly, the SSOUsers API can be invoked to define the groups associated with each user.

For both resources, there are no limitations as to when the groups can be set or updated.

If it's only desired to limit users from @mention'ing each other, then Pages do not have to be taken into consideration.

Note!

Defining and updating the SSO user groups does not require using the API, and can instead be updated automatically by defining the group ids in the SSO payload passed to the comment widget. However, for large lists of groups, this is not recommended as the user would have to submit this payload for every page load.

Example API Calls

Here we'll walk through calling the FastComments API to setup access control.

Before we begin, note that we don't have to explicitly create a Group structure. Groups are simply identifiers added to Users and Pages. Adding a group to a user or page automatically "creates" the group.

First, let's create two users, User A and User B, we'll start them out in Group X:

Create User A cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "user-a",
    "username": "User A",
    "email": "usera@example.com",
    "groupIds": ["GROUP-X"]
}'

Create User B cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "user-b",
    "username": "User B",
    "email": "userb@example.com",
    "groupIds": ["GROUP-X"]
}'

Now let's create a Page. We'll call it our Confidential Page, and so far none of these users will have access to it as it will be in the group CONFIDENTIAL:

Page POST cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Confidential Page",
    "url": "https://mysite.com/confidential",
    "urlId": "https://mysite.com/confidential",
    "accessibleByGroupIds": ["CONFIDENTIAL"]
}'

Users A and B currently DO NOT have access to the new page. However, since they are in the same group, GROUP-X, they can @mention each other.

Let's update User B so they can now access the page:

Update User B cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "groupIds": ["GROUP-X", "CONFIDENTIAL"]
}'

User B now belongs to both groups. Our users can still @mention each other, but only User B can view our confidential page.

Let's make it so User B can only view the confidential page:

Update User B cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "groupIds": ["CONFIDENTIAL"]
}'

Now they can view the confidential page, but neither of our users can @mention each other, as they are in different groups.

However, any user that is not part of access control will be able to access our page. To prevent this, ensure no SSO Users have their groupIds set to null. For example, let's create User C, which has access to everything:

Create User C cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "user-c",
    "username": "User C",
    "email": "userc@example.com",
    "groupIds": null
}'

By setting groupIds to null, we say they are not limited by access control.

Now, let's create a page that everyone has access to:

Page POST cURL Example

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Public Page",
    "url": "https://mysite.com/public",
    "urlId": "https://mysite.com/public",
    "accessibleByGroupIds": null
}'

By setting accessibleByGroupIds to null, we say this Page is not controlled via access control, and both users can access it.

This completes our API walk-through for Access Control.

Background

Implementation

What is Access Control?

In Detail

Use User-Level Groups if...

Use Page-Level Groups if...

How it Works

Accessing Unauthorized Pages

The Spec

Implementation

Mentioning Users in Other Groups

Maintaining the Groups

Note!

Example API Calls