API Security

The FAM API is publicly accessible through an AWS API Gateway configuration. Security is controlled programmatically using JWT tokens provided by AWS Cognito.

For security pupose, we separate the apis used for managing application admins and managing regular users. The reason for this is to prevent a user with lower privileges hacking into the executable for a high-privilege API and getting more database access than necessary.

Admin Management Endpoints

Support users who use FAM to manage admin permissions for FAM applications, including application admin permissions and delegated admin permissions. Admin management endpoints require user that is logged-in has at least one FAM app admin role (must be admin of at least one FAM application).

FAM Application Admin

Only users with FAM admin role is able to manage application admins. The role "FAM_ADMIN" will be in the JWT attribute "cognito:groups" in the access token passed into the API as the bearer token. If there is no bearer token passed into the API, the user has not authenticated with Cognito. If there is no access token or the access token does not contain "FAM_ADMIN" role, the endpoints that manage application admin access return 403 (Forbidden).

• GET /application_admins
  • Get all the application admins
• POST /application_admins
  • Create an application admin
  • Cannot grant any application admin access for self
• DELETE /application_admins/{application_admin_id}
  • Delete an application admin
  • The URL parameter "application_admin_id" corresponds with a primary key of a record in the "fam_application_admin" table
  • Cannot delete any application admin access for self

FAM Access Control Privileges

Only users with application admin role is able to manage application delegated admins. The role "<APP_NAME>_ADMIN" (for example FOM_DEV_ADMIN, CLIENT_TEST_ADMIN, SILVA_PROD_ADMIN) will be in the JWT attribute "cognito:groups" in the access token passed into the API as the bearer token. If there is no bearer token passed into the API, the user has not authenticated with Cognito. If there is no access token or the access token does not contain application admin role, the endpoints that manage access control privileges return 403 (Forbidden).

• GET /access_control_privileges
  • Get all the delegated admins of the application specified by the "application_id" query parameter
  • The logged-in user must have the application admin role for the application specified by the "application_id" query parameter
• POST /access_control_privileges
  • Create an delegated admin with the privileges that he/she can manage
  • The logged-in user must have the application admin role for the application specified by the "role_id" query parameter (get application information by role_id)
  • Cannot grant any access control privilege for self
• DELETE /access_control_privileges/{access_control_privilege_id}
  • Delete an access control privilege
  • The URL parameter "access_control_privilege_id" corresponds with a primary key of a record in the "fam_access_control_privilege" table
  • The logged-in user must have the application admin role for the application specified by the "access_control_privilege_id" URL parameter (get application information by access_control_privilege_id)
  • Cannot delete any access control privilege for self

Admin User Accesses

Get the admin access of logged-in user for what applications/roles(scoped) the user can grant. This endpoint does not require user to have any role.

• GET /admin-user-accesses

Application Access Control Endpoints

Support users who use FAM to manage general users access for FAM applications. Application access control endpoints require user that is logged-in has at least one FAM app admin or delegated admin role (must be admin or delegated admin of at least one FAM application). The role "<APP_NAME>_ADMIN" (for example FOM_DEV_ADMIN, CLIENT_TEST_ADMIN, SILVA_PROD_ADMIN, FAM_ADMIN) will be in the JWT attribute "cognito:groups" in the access token passed into the API as the bearer token. If there is no bearer token passed into the API, the user has not authenticated with Cognito. Delegated admin access will be retrieved from the "fam_access_control_privilege" table. If there is no access token or the access token does not contain any admin role, and there is no delegated admin access can be found from the "fam_access_control_privilege" table, the endpoints that manage application access return 403 (Forbidden).

FAM Applications

User must have application admin role or have delegated admin access for the application specified by the "application_id" URL parameter in order to get users' access information to this application. Application admins are able to view all the users who have access to the specified application and their access to the application. Delegated admins are only able to view the users with the access that they have privilege to manage for. Business BCeID delegated admins are only allow to view the users from the same organization (cannot manage IDIR users' access). Business BCeID delegated admins must already accept the terms and conditions.

• GET /fam_applicaitons/{application_id}/user_role_assignment

FAM User Role Assignment

Only users with application admin role or have delegated admin access is able to manage users' access to the application. Application admins are able to manage all the users who have access to the specified application and their access to the application. Delegated admins are only able to manage the users with the access that they have privilege to manage for. Business BCeID delegated admins are only allow to manage the users from the same organization (cannot manage IDIR users' access). Business BCeID delegated admins must already accept the terms and conditions.

• POST /user_role_assignment
  • Grant a user access to the application with a role specificed by the "role_id" query parameter
  • The logged-in user must have the application admin role for the application, or have delegated admin privilege for the role specified by the "role_id" query parameter (get application and role information by role_id)
  • Cannot grant any access for self
• DELETE /user_role_assignment/{user_role_xref_id}
  • Remove an access of a user
  • The URL parameter "user_role_xref_id" corresponds with a primary key of a record in the "fam_user_role_xref" table
  • he logged-in user must have the application admin role for the application, or have delegated admin privilege for the role specified by the "user_role_xref_id" URL parameter (get application and role information by user_role_xref_id)
  • Cannot delete any access for self

FAM User Terms and Conditions

Business BCeID delegated admin must accept terms and conditions.

• POST /user_terms_conditions/user:validate
  • Check if user needs to accept terms and conditions
  • Only FAM application admin or delegated admin users can make this call (basic security check, user needs to be admin or delegated admin of at least one FAM application)
• POST /user_terms_conditions
  • Only business BCeID delegated admin is able to make this call, no need for other users

FAM Integration Endpoints

FAM integrates with external services such as Forest Client API and IDIM Web Services. FAM application admin or delegated admin users can make call to these endpoints (basic security check, user needs to be admin or delegated admin of at least one FAM application).

FAM Forest Clients

Integrated with Forest Client API to retrieve forest client number information. FAM-DEV and FAM-TEST are integrated with Forest Client API TEST environment. FAM-PROD is integrated with both Forest Client API TEST and PROD environment. In FAM-PROD environment, production applications use Forest Client API PROD; dev and test applications use Forest Client API TEST.

• GET /forest_clients/search
  • Get information of a forest client number

IDIR/BCeID Proxy

Integrated with IDIM Web Service to retreive user information. FAM-DEV and FAM-TEST are integrated with IDIM Web Service TEST enviornment. FAM-PROD is integrated with both IDIM Web Service TES and PROD environment. In FAM-PROD environment, production applications use IDIM Web Service PROD, dev and test applications use IDIM Web Service TEST.

• GET /identity_search/idir

  • Get information of a IDIR user
  • Only IDIR user can lookup for IDIR user

• GET /identity_search/bceid

  • Get information of a Business BCeID user
  • Business BCeID user cannot lookup for the user from the same organization

BCSC Proxy

Bc service card token and userinfo endpoints are used by AWS Cognito to decrypt the tokens. The /bcsc/jwks.json endpoint is used by the BC service card team previously for them to get the key to encrypt the token. But it's not in use anymore, the bc service card team hardcoded the key recently, so the encryption and decryption process can be fast enough to meet our Auth Lambda's response time limit.