Concepts #

Account #

We have two types of accounts:

• User account: Account that is created by a human. Each user account contains: FirstName and LastName Phone number Attributes (to use in policies)

• Service account: Services use this type of accounts to send requests to the authorization server or for service-to-service calls. When the admin created a service account, they can get a PAT using that service account and use it in their services.

Service #

Service is a real service in your platform(e.g., marketing service), you can use them to isolate policies, resources, and roles in the authorization service. When you want to add a new service to the platform (e.g., analytics service), the admin needs to create a new service, so the new service can assign roles and permissions to users. Each service owner can create new roles and use them in policies.

Role #

Create roles and assign them to users. We can assign one or more resources (resources) to roles. It means if a user has the role, they have access to the role's resources.
To assign a resource to a role, we need to create a policy.

Resource And Scope #

A resource is an entity that you want to specify whether a user has permission to it. Resources can have scopes, scope is the operation that the user wants to do on the resource. For example, if you have some projects in your service and want to grant “edit” permission to John, your resource is “project” and your scope is “edit”. Each service has its own resources and scopes. Services can not share resources and scopes. You can set attributes per each resource and use them in your policies. By default, you don’t need to define resources when you are using them in policies, but if you want to set attributes (e.g., is_active: false|true) on resources, you can define resources by API before using them in policies(more on this later).

Each resource contains:

• Unique id (per type per service)
• Type
• Scopes
• Attributes (to use in policies)

Policy #

We use policies to define resource permissions. Policies are per service, so when a service defines a policy, that policy applies just in that service permission checks, not other services.

Policies can be defined in many ways, for example, we can define a policy:

• To grant permission to a resource type (e.g., all projects)
• To grant permission to a specific resource (e.g., a project with id: 4)
• To grant permission to a specific user or any user with a specific role
• ...

Some examples of policies could be like these:

• Grant “view project” permission to any user with a “manager” role.
• Grant “view project” permission to any user in Fars state just for projects in Fars state.
• Grant “view project” on the project with id 3 to the user with the name “Ali”.

Each policy contains:

• User ID (optional): If we set a user on a policy, so that policy is just for that user.
• tree(optional): If we set a tree on the policy, that policy applies to the resource just when tree values match with values provided in the request context.
• res_type(required): If we set res_type but do not set res id and scope, that policy applies to all resources of that type.
• res_id(optional): If we set res_id, the policy applies to that resource. When we set scope, it applies on specified scopes, otherwise on all scopes of that policy.
• res_scopes (optional): if we set res_scopes, the policy applies to specified scopes of the resource.
• role_code: If we set the role, so we grant access to every user with the specified role.
• condition(optional): Condition is an optional field to check if some attributes match before we apply the policy, for example, if you want to apply a policy just when the project(as our resource) is active, we can define it in our policy using condition.