FAM Onboarding Ops Guide

Create a New Application

• Create new OIDC clients for the new application in the terraform, depend on which environments they asked, create one for each environment, and config the following fields:

  • Supported identity provider
  • Login callback urls (normally we put debugger urls for dev and test, not prod)
  • Logout callback urls
  • Read attributes

• Add new application to the database

  • In the fam_application table, create a new application for each environment, follow the naming convention "ApplicationName_ENV" (like "FOM_DEV")
  • In the fam_application_client table, create a new application client for each environment
  • In the fam_role table, create a admin role for the new application for each enviornment in FAM, follow the naming convention "ApplicationName_ENV_ACCESS_ADMIN" (like "FOM_DEV_ACCESS_ADMIN")
  • If our user request some test roles, we could create the test roles for them in the fam_role table as well for all environmets

• Update the flyway infrastructure to pass new application client ids from Cognito

• Update the pipeline reusable_auth_function_ci.yml and the docker-compose file in the root directory to put flyway placeholder for the new application client ids, just random strings

• Update the test that gets all applications, update the assertion number when we add apps

• Could refer the pull request 487 when we onboard spar

Add New Application into Production

• Find the commit that we deployed to production last time, create a branch from that commit and switch to that branch. Note: the branch name can't be too long, and at most allow one "-" in the branch name

  // from main branch
  git checkout [commit_number_where_we_last_deploy_to_main]
  git branch hotfix/onboard-[new_application_name]
  git checkout hotfix/onboard-[new_application_name]
  

  

• Apply all the changes from the "Create a New Application" section. If want to apply a specific commit, could use git cherry-pick [commit_number], create a pull request and allow team members to review. Note: be careful to check to flyway script version order, make sure it's in sequence, and not having conflicts with other commits in main

• Make a test deployment from this hotfix branch, and verify if the new applications are setted up correctly (dev, test and prod client). Use the OIDC Debugger tool to check the flow of getting authentication token and access and id tokens

• Make a prod deploymetn from this hotfix branch, need to update the prod protection rule to allow deployment from the hotfix branch. Verify if the new applications are setted up correctly

  

• Merge the hotfix branch to main branch, if getting the conflict for the flyway script, apply the hotfix version first, and then the rest

Return the Configuration Parameters to Our Client

Return the following to our client for the dev and test environment in a json file, follow the naming convention "ApplicationName-ENV-config.json" (like SPAR-dev-config.json):

{
    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 the client id",
    aws_mandatory_sign_in: 'enable',
    oauth: {
        domain: "this is the cognito oauth domain",
        scope: ['openid'],
        redirectSignIn: "this is the login redirect url we get from our client", // note, they could give multiple redirect urls, we just list one or let them config by themselves
        redirectSignOut: "this is the logout chain url + the logout redirect url get from our client"
        responseType: 'code',
    },
    federationTarget: 'COGNITO_USER_POOLS',
};

Email template:

Please find the attachment for the configuration parameters for the dev and test environment to onboard with FAM. Feel free to check our onboarding guide at https://github.com/bcgov/nr-forests-access-management/wiki/FAM-Onboarding#start-using-your-client-configuration and let us know if you have any question.

Assign the PO and Tech Lead the admin access role to their application.

Ready for Production

When the new application is ready to move their application into production, we need to connect with IDIM team. An email should be sent to the IDIM team with the following within 60-90 days:

• Volume of users
• Product teams should complete OSD entries by sending an email: [email protected] or the security team & cc IDIM team with the following information:
  • Client Profile: Ministry Name
  • Online Service Name:
  • Acronym: max 6 Characters
  • Contact Name: ?
  • Online Service Home Page URL: ?
  • Short Description: ?
  • Long Description: ?
  • Help Desk Telephone: ?Help Desk Email: ?
  • Authentication Requirements: Business BCeID3.
• If any communication to external clients mention BCeID, the team need to contact BCeID for a review and signoff

And we will email the production config parameters to all the contact persons listed in the questionnaire