FAM Onboarding Ops Guide

Create the New Application in FAM

• 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

• Could refer the pull request 487 when we onboard spar

Deploy New Application into FAM Production by Hotfix Release

Note: It's ideal if we can do this in a regular release, but in the case we're not ready for a regular release, we can also do a hotfix release

• Find the latest release tag that we deployed to production last time, create a branch called "hotfix" from that release commit

• Find the latest release tag that we deployed to production last time, create another branch from that release 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_for_the_latest_release_we_deploy_to_prod]
  git branch hotfix/onboard-[new_application_name]
  git checkout hotfix/onboard-[new_application_name]
  

  

• Apply all the changes from the "Create the New Application in FAM" section. If want to apply a specific commit, could use git cherry-pick [commit_number]. Create a pull request to merge the "hotfix/onboard-[new_application_name]" branch to the "hotfix" branch, 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

• Merge the "hotfix/onboard-[new_application_name]" branch to the "hotfix" branch, the hotfix release management will be triggered and a hotfix release pull request will be created automatically

• Merge that hotfix release pull request, a new version tag will be created

• Make a test deployment from the hotfix version tag, 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 deployment from the hotfix version tag, need to update the prod protection rule to allow deployment from a specific version. Verify if the new applications are set 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.

Note: If the team requires more user information like email etc, we need to send an email to let them know it's up to them to take care of these user information and include in their PIA.

Add Team Contact Information

Add the new team's contact information to our Consumer Applications Registry in confluence.

Confirm STRA/SOAR/PIA

Before the new application can be moved into production, we need to confirm with this application's team that they have updated their STRA/SOAR/PIA.

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: Chris.M.Smith@gov.bc.ca 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