FAM Onboarding

Purpose of FAM

FAM aims to be the central authentication/authorization hub for modernized Natural Resource Sector applications. It follows the OIDC (Open ID Connect) standard process and flow to secure the applications and will provide business clients manage their own staff access (roles) in highly secure and user friendly way. Please visit Wiki Home Page for more information.

Brief Technical Summary

FAM is built on AWS Cloud and the heart of FAM is built on highly secure and popular "Amazon Cognito" to support forestry applications access control needs. Cognito follows OIDC/OAuth2 standard protocols and supports rich integration. FAM currently is integrated with custom identity providers (IDIR and BCeID) and will soon integrate with BC Services Card and provide access management capabilities for those users. Please visit Architecture for more details.

Making a Request

Before making a request to onboard to FAM, please complete these steps:

• Review and provide application details using FAM Onboarding Questionniare.
• Provide administrative person information (probably product owner) for your application to grant access to users.
• Gather valid access roles your application needs (for later importing to FAM).
• Decide what user attributes your team wants. By default, we will return Name of SSO IDP (custom:idp_name), User GUID (custom:idp_user_id) and User ID (custom:idp_username). If you need more user information, please provide us a list. The full attribute list can be found here for IDIR user, and here for BCEID user, and here for BC service card user.
  Please note that your team's PIA should include information about how your team will use and maintain the user information you are pulling from FAM.
• Provide user/role records (or your team may need to contact and export from existing system) at later stage to migrate to FAM (preferable as CSV file).

Based on the information we get, we will create a new client in FAM for your project, and send the client details to your contact person for all environments that are requested. It includes the following configuration parameters:

{
    aws_cognito_region: "this is fam cognito region",
    aws_user_pools_id: "this is the fam user pool id",
    aws_user_pools_web_client_id: "this is your client id",
    aws_mandatory_sign_in: 'enable',
    oauth: {
        domain: "this is the cognito oauth domain",
        scope: ['openid'],
        redirectSignIn: "this is the login redirect url you give to us",
        redirectSignOut: "this is the logout chain url + the logout redirect url you give to us"
        responseType: 'code',
    },
    federationTarget: 'COGNITO_USER_POOLS',
};

Note:

• Your "redirectSignIn" and "redirectSignOut" are important based on your application and environment. They will be part of the verification check from Cognito. If it is not correct, authentication will fail.
• "aws_user_pools_web_client_id" value is environment specific for your application (e.g., DEV/TEST/PROD), so setup to your application appropriately.
• You can reference to Amplify for configuration.

Start Using your Client Configuration

Once you have your client details, you can configure your application to use the service for your application authentication and authorization. If your application is JavaScript or SPA (Single Page Application) We suggest to use the AWS Amplify library.

Note:

• Some AWS Authentication basic you may like to know.
• As FAM uses Cognito Hosted UI to provide choices of authentication through IDIR/BCeID (IDP providers), your application does not need to follow Amplify's way of building custom SignIn or SignUp page on your application.

An example:

• Install Amplify library for Nodejs project

  npm install aws-amplify
  

• Config the Amplify library where you want to use it, where the aws-exports is the file stores all the configuration parameters we send to you

  import { Amplify } from 'aws-amplify';
  import awsconfig from './aws-exports';
  
  Amplify.configure(awsconfig);
  

• Amplify methods, more methods please check its documnetation:

  • Login:

    import { Auth } from 'aws-amplify';
    
    Auth.federatedSignIn();
    

  • Logout:

    Auth.signOut();
    

  • Get current user:

    Auth.currentAuthenticatedUser();
    

  • Get tokens:

    Auth.currentSession();
    

• JWT Token and Authorization:

  • Once authentication is success and FAM Cognito sends back an encrypted token, it will contain these:

    • "id_token"
    • "access_token"
    • "refresh_token"

  • To get the access roles, you can obtain it from the decrypted "access_token" in "cognito:groups". Similar like below:

      {
        "sub": "e8c217e4-2c0e-45b6-9c5a-fff43c60c3ff",
        "cognito:groups": [
           "FAM_ACCESS_ADMIN",
           "FOM_DEV_ACCESS_ADMIN"
        ],
       "iss": "https://cognito-idp.ca-central-1.amazonaws.com/ca-central-1_yds9Vci8g",