Setting up Okta - CDCgov/prime-simplereport GitHub Wiki

We use Okta for identity management, both in production and lower test environments. We have a separate production instance, with real users, and a preview instance for lower environments.

Setting up Okta for Testing in Lower Environments

To set up your Okta account for testing in a lower deployed environment, you will need to follow a few steps in Okta preview, where we manage Okta groups for deployed applications in lower environments.

First, ask a team member to invite you to the Okta Preview group (they can do so by inviting you to an organization through the SimpleReport UI.) Once you've received the welcome email and activated your account, ask someone to add you to the following Okta groups:

  • PRIME Team Members
  • SimpleReport Engineering
  • SR-{ENV}-ADMINS

Next, (once you've deployed to an environment) you'll want to set yourself up within the application:

  1. Go to {env}.[simplereport.gov/app/sign-up, for instance test.simplereport.gov/app/sign-up
  2. Select “my org is new to SimpleReport”
  1. Fill out the organization information (note that you will need to use a dummy email address, you’ll get an error if you try to register with an email already in the Okta system) and submit
  2. It’ll take you to a “personal details” form, which you don’t want to fill out - this is for the Experian automated ID verification flow, which is disabled and/or uses a dummy database for almost all lower environments.
  3. Go back to plain {env}.simplereport.gov/app, and you should see the superadmin view if you’re part of the Okta group SR-{ENV}-ADMINS (you may need to log out/in for the changes to take effect) Screen Shot 2022-08-09 at 9 49 46 AM
    • If you don't see this view, ask a team member to add you to the Okta group SR-{ENV}-ADMINS
  4. Go to “organizations pending identity verification” - it’s the first link
  5. Select and verify your organization.

At this point, you have an organization that exists in both the database and as an Okta group! yay! However, you still can’t log into it... 8. Go back to the Okta preview admin view and find the Okta group for the org you just created. It’ll follow the pattern SR-{ENV}-TENANT:{State abbrv.}-{ORG-NAME}-{ORG EXTERNAL ID}

  1. Add yourself to the ADMIN and NO_ACCESS groups for that organization
  2. Go back to the environment and you should see the facility creation page this time! Which means you’ve successfully created the org, you’re in it, and now need to add a facility for it. (You may need to log in/out for the changes to take effect). Voila!

Note that it's advisable to do these separate tasks for your "real" and "dummy" user accounts in separate incognito browser windows.

Setting up Okta for Local Development

You may wish to run the app locally with Okta enabled. To do so, be sure to follow setup instructions first to run the app.

Once you've completed setup, you can log in with your Okta credentials. At this point, you will need to follow the same steps for Setting up Okta for Testing in Lower Environments, see above.

  • Make sure you have an account set up in Okta Preview
  • Follow the steps outlined above to create a new organization, including creating an account with a dummy email address
  • In Okta Preview, assign yourself to the appropriate groups

Setting up Okta for Prod

Ask a developer who already has production access to add you to "Real" Okta.

See Adding-a-Developer for instructions on the specific groups to add.

More Info

For more information about Okta and managing support requests through the Okta UI, see the docs repo wiki.