Welcome to BriteAccess’s documentation!

A Primer on BriteAccess

BriteAccess is BriteCore’s access control solution, making sure that actions in the system can only be taken by authorized personnel. This means things like ensuring Agents cannot see each other’s data or that agencies can only write business for the states they are allowed to. It does that by intercepting all API calls into products and inspecting them first before there’s any chance it’ll perform an action in the system.

Resources and actions: nouns and verbs

BriteAccess represents all possible points of control as pairs of resource and action identifiers. Take the following table as an example:

Human-readable description of an action	HTTP Endpoint	Resource	Action
Bind a quote	`POST /quote/{quote_number}/bind`	`bc.britequote.quote`	`Bind`
Create a user	`POST /user-management/users`	`bc.briteauth.user`	`Create`
Listing all users in the system	`GET /user-management/users`	`bc.briteauth.user`	`RetrieveList`
Get details about a particular user	`GET /user-management/users/{username}`	`bc.briteauth.user`	`RetrieveRecord`
Create a claim	`POST /claims/`	`bc.briteclaims.claim`	`Create`
See the BriteRules module in the sidebar	N/A	`bc.briterules.britecoreui`	`ViewModule`
See the Underwriter Queue page	N/A	`bc.britequote.underwriter-queue`	`ViewPage`

This way, BriteAccess’s configuration layer is not limited (or dependent on) the underlying technology that it is protecting — as long as it can be translated into a resource and action pair, it can be configured into BriteAccess. There’s no inherent meaning to these two other than the following convention:

Resources automatically get prefixed by bc.{module} within BriteAccess
Actions that are just performing the standard CRUD should be named Create, RetrieveRecord, RetrieveList, Update and Delete.

Other than these conventions, every product is free to define their own resource and action pair themselves.

Statements

Actions and resources can be organized together into statements, which tell BriteAccess what to enforce and how to enforce it. Here’s an example:

{
    "effect": "allow",
    "resource": "bc.briteauth.user",
    "actions": ["Create", "RetrieveRecord", "RetrieveList"]
}

This simple statement tells BriteAccess that whoever is bound to it should be granted the permission to perform the Create, RetrieveRecord and RetrieveList actions on the bc.briteauth.user resource. Now compare that to this other example:

{
    "effect": "deny",
    "resource": "bc.briteauth.*",
    "actions": ["*"]
}

This statement is denying the permission for an action to whomever it’s bound to. In this case, it’s denying the permission to perform ANY (*) action on ANY (*) resource in the bc.briteauth domain. In BriteAccess, deny always overrides allow statements, so if this statement was present in a user’s profile, no matter what other permissions they had, they would not be able to perform any actions on the BriteAuth module.

Wildcards can be used anywhere in the statement definition’s actions and resource sections. This is an example off of an actual permission in BriteAccess:

{
    "effect": "allow",
    "resource": "*.*.*",
    "actions": ["*"]
}

This statement grants whomever it is attached to the permission to perform ANY action on ANY resource in the system. This is the equivalent of having full power over BriteCore and is very powerful. BriteAccess has no concept of a built-in “superuser” flag, but this can configure an equivalent situation. Statements can also involve conditions and more advanced options.

ACPs: The building blocks

Access Control Permissions, or ACPs, are the next building blocks in access configuration. They group multiple statements into a logical block that can be reused as part of larger definitions. Take this example:

{
  "name": "UserManagementWriteOnly",
  "description": "Allows write-only access to the user management system",
  "statements": [
    {
      "sid": 1,
      "effect": "allow",
      "resource": "bc.briteauth.user",
      "actions": ["Create", "Update", "ResetPassword", "Delete", "ChangeGroupMembership"]
    },
    {
        "sid": 2,
        "effect": "allow",
        "resource": "bc.briteauth.group",
        "actions": ["Create", "Delete"]
    },
    {
        "sid": 3,
        "effect": "deny",
        "resource": "bc.briteauth.user",
        "actions": ["Delete"]
    }
  ]
}

Statement #1 is granting the permission to perform a number of actions on users in the system, #2 is granting the permission to do the same to groups. Statement #3 is denying a permission that was previously granted to delete users.

As written above, deny always overrides allow statements anywhere in BriteAccess, so effectively the third statement is removing a permission previously established in statement #1.

Other than the list of statements (note the sid properties denoting ordering of statements), an ACP also has a name (that is unique in the system) and a description. This means that this ACP can be reused multiple times on various different objects. If the ACP itself changes, the change will propagate to all objects it is attached to automatically.

Moreover, ACPs should effectively convey a logical grouping of related actions into a user-visible “flow”. It would make a lot of sense to have, for example, an ACP that allowed whoever it was attached to the permission to Quote. That could involve multiple resources and actions, even across different modules. Having that in one single ACP that’s reusable facilitates configuration and maintenance of the system.

Roles

A role in BriteAccess is effectively just a group of different ACPs under a single name. You could have, for example, the following role:

{
    "name": "Agent",
    "gen2_role": "Agent",
    "permissions": [
        "AllowQuoting",
        "AllowListingOwnPolicies",
        "AllowEditingOwnPolicies"
    ]
}

Would define an Agent role with the AllowQuoting, AllowListingOwnPolicies and AllowEditingOwnPolicies ACPs bound to it. Put simply, whenever a user with this role tries to perform an action, BriteAccess will compare it with all ACPs bound to that user’s current role and decide whether the user has access based on these rules, in order:

If there’s any statement matching the user’s action with the deny effect, the action is denied.
If there’s any statement matching the user’s action with the allow effect, the action is allowed.
Finally, if no statements match the user’s action in their current role, the action is denied.

Roles can be assigned either to users or to groups of users. Assigning a role to a group of users is effective immediately: if a user gets added to the group, they will have access to that role whenever they log in.

User sessions can only have one role active at a time. If a user has more than one role upon logging in, they will be asked to choose an effective role during the log in process. They can also switch roles during their session, but BriteAccess will always consider only the currently effective role of a user for access control purposes.

Conclusion

Tying it all up together, this schematic denotes the relationships between the multiple objects exposed above:

Object diagram

For more advanced topics, follow other links on this page.

Concepts

Access Control Permissions