Create Dev Okta Setup

Create Dev Okta Account

1. Go to https://developer.okta.com and click the Go to Workforce Identity Cloud docs button or click the X in the upper right.

2. Click the Log in button.

3. You can choose however you would like to authenticate.

Create New Okta Application

1. Once logged in, click Applications > Applications in the side navigation.

2. Click the Create App Integration button to create your new app. Your new account with come with some default applications, but this project requires a SPA application.

3. In the modal that opens, select OIDC and Single-Page Application and click the Next button.

4. Name your application.

5. Add the following urls, these are the urls you will need for local development. If the site is hosted somewhere else use those urls.

Sign-in redirect URIs:

• http://localhost:8080/implicit/callback
• http://localhost:8001/implicit/callback
• http://localhost:8081/implicit/callback

Sign-out redirect URIs:

• http://localhost:8080
• http://localhost:8001
• http://localhost:8081

6. Click the radio button next to Enable immediate access with Federation Broker Mode and click the Save button.

7. Your new application should appear in the Applications list. Add an environment variable OKTA_CLIENT_ID and set it to the Client ID beneath the new Application. Then, click on the new application name to open the application details.

8. Click on Okta API Scopes tab. The list will show all available scopes. Leave the default scopes granted. Click ✔️Grant next to the following scopes:

• okta.clients.read
• okta.users.read
• okta.users.read.self

The image below shows the scopes already granted.

Create the API Key

1. Click Security > API in the side navigation.

2. Create an environment variable named OKTA_AUDIENCE and set it to the value under the Audience header. It defaults to api://default. Create an environment variable named OKTA_DOMAIN and set it to the domain from the Issuer URI. Create an environment variable named OKTA_SERVER_ID and set to the last part of the URI. This defaults to default.

3. Click the Tokens tab. Then, click the Create token button.

4. A modal will open. Name your token. Then, click the Create token button.

5. Copy the Token Value that appears, because you will not be able to see it again. Then, click the OK, got it button.

6. Click the Trusted Origins tab. Then, click the Add origin button.

7. Add the url for your web server. The project sets the default web url to http://localhost:8080. Click the radio buttons next to Cross-Origin Resource Sharing (CORS) and Redirected. Click the Save button.

8. Click the Add origin button again. Add the url for your API server. The project sets the default API url to http://localhost:8081. Click the radio buttons next to Cross-Origin Resource Sharing (CORS) and Redirected. Click the Save button.

Add Test Users

1. Open the file documentation/eAPD_Users.csv and update the email addresses. They need to be actual email addresses that you have sustained access to, because they will be used in the event of updating passwords, getting one-time passwords, reseting locked accounts, etc. The development team used the Gmail trick of adding +something into your email address. For example, a person with the email address [email protected] could use [email protected] to create a unique email for the State Admin user. Make sure the file is saved in csv format. Explanation of Test Users:

Username	Usage	Role	Affiliation Seeded?
[email protected]	Standard testing user	State Admin	Yes
fedadmin	Testing as a Federal Administrator user	Fed Admin	Yes
stateadmin	Testing as a State Administrator user	State Admin	Yes
statestaff	Testing as a State Staff user	State Staff	Yes
statecontractor	Testing as a State Contractor user	State Contractor	Yes
sysadmin	Testing as a System Administrator user	System Admin	No, added via LaunchDarkly
requestedrole	Testing as a user who has requested a role that hasn't been reviewed yet	N/A	Yes
deniedrole	Testing as a user who had their role requrest denied	N/A	Yes
revokedrole	Testing as a user who had their role revoked	N/A	Yes
norole	Testing as a user who does not have any roles to test the requesting roles process	N/A	No
expiredadmin	Testing as a user whose State Administrator role has expired (logging in as the user should revoke their role)	State Admin	Yes
pendingadmin	Testing as a user who has an approved State Staff role and has a valid State Administrator Certification letter, this can be used by the Federal Administrator user to approve a State Administrator	State Staff	Yes
betauser	Testing as a user who is a Beta User in LaunchDarkly	State Staff	Yes
notingroupmfa	Testing the error message for a user not in our Okta group	N/A	No
lockedout	Testing the error message for a user who has locked their account with too many failed login attempts	N/A	No
expired	Testing the error message for a user with an expired password	N/A	No
[email protected]*	Standard testing with MFA required	State Staff	Yes
lockedoutmfa*	Testing the error message and login flow for a MFA enabled user who has too many failed login attempts	N/A	No
resetmfa*	Testing the flow for setting the MFA for a user who requires MFA and doesn't have one set	N/A	No
norolemfa*	Testing as a MFA enabled user who does not have any roles to test the requesting roles process	N/A	No
expiredmfa*	Testing the error message for a MFA enabled user with an expired password	N/A	No

*You don't need to add the MFA accounts if you aren't using MFA with your site

2. Before we add users, we need to removed the Okta profile default of requiring logins to be in email format. Click on Directory > Profile Editor in the side navigation.

3. Click on User (default) in the Profile list.

4. Click on the i button in the Username row.

5. Change Format restrictions to None. Click the Save Attribute button.

6. Click Directory > People in the side navigation.

7. Click the More actions button.

8. Click the Import users from CSV item in the dropdown list.

9. Click the Browse button. Navigate to the eAPD_Users.csv file.

10. Click the Upload CSV button. The modal will change to show the progress of parsing the file.

11. Click the Next button.

12. Click the checkbox next to Automatically activate new users. Then click the Import Users button.

13. The modal should update to show that all users have been imported successfully. Click the Done button.

If there are issues with the upload, there will be an option to download the CSV with error messages added to it. You can remove the successful rows and then fix the errors and try the upload again.

14. You will get emails for all of the new accounts with links for setting the passwords. Create passwords for each account and save them for future use. Once all of the passwords have been set, the Status of all of the accounts should be Active.

15. Two accounts are used to test the expired account error messages, so they need to have their passwords expired. Click on the Password Expired account.

16. Get the user's ID from the url https//[OKTA_DOMAIN]/admin/user/profile/view/[userID] in the browser.
17. Open Postman/Insomnia/Terminal, set the Authorization header to SSWS [OKTA_API_KEY], braces are just to distinguish that the value needs to be replaced. Then POST to [OKTA_DOMAIN]/api/v1/users/[userID]/lifecycle/expire_password to manually expire the password.
18. The account should now show that the password is expired. Repeat steps 10-12 for the Expired MFA account.

Create User Groups

1. Click Directory > Groups in the side navigation.

2. Click the Add group button.

3. Create a group for eAPD Users. Click the Save button.

4. Click the new eAPD Users group.

You might need to manually refresh the page to see the new group.

5. Click the Assign people button.

6. Click the + sign next to all of the users, except NotInGroup MFA, to add them to the group.

7. Click the Done button.

8. Repeat steps 5-7 until all of the users, except NotInGroup MFA, have been added to the eAPD User group. There should be 20 of these users in this group. If NotInGroup MFA is in the group some of the Cypress tests will fail. If they were added, you can remove them by opening the group and clicking the X button in the row with their name.

9. Repeat steps 2-7 to create an eAPD MFA group to hold the users needed to test MFA functionality. Add all of the users with MFA in their name to this group. There should be 6 of these users in this group.

Add eAPD User Group to the Application

1. Click Applications > Applications in the side navigation.

2. Click on the application.

3. Click the Assign button.

4. Click the Assign to Groups item in the dropdown lists.

5. Click the Assign button next to the eAPD Users group.

6. Click the Done button.

Set Up Failed Login Attempt Limit

The CMS Okta policies only allows users 3 failed log in attempts before their account is locked out. The Cypress tests in 01-authentication/02-invalid-login-attempts.cy expect this to be the case. A few settings have to be enabled as well to return the appropriate error message that the front end expects to see for failed login attempts and user lock outs.

1. Click Security > Authentication in the side navigation.

2. Click the Edit button on the Default Policy.

3. Scroll down to Lock out and change Lock out user after _ unsuccessful attempts to 3. Click the checkbox next to Account is automatically unlocked after 60 minutes. Click the checkbox next to Show lock out failures. Click the checkbox next to Password expires after 120 days. Click the Update Policy button.

Set Up MFA Requirements

The CMS Okta configurations require MFA for all accounts. We were allowed to have a group of users without MFA on the non-production environments. So the Cypress tests do not assume MFA requirements. However, the project is set up to handle MFA, if you would like to also require it. The instructions explain how to create a group where MFA is required and the rest of the accounts do not require it, for simplicity. The more secure method would be require MFA by default for all users and then creating and exempt group.

1. Click Security > Multifactor in the side navigation.

2. Click on the factors that you would like to use. Click the Inactive button on the factors you want.

3. Click the Activate item in the dropdown list.

4. Click the Factor Enrollment tab to see the active factors.

5. Click Security > Authentication in the side navigation.

6. Click the Sign On tab. Click the Add New Okta Sign-on Policy button.

7. Create a policy and assign it to the eAPD MFA group. Click the Create policy and add rule button.

8. Click the radio button next to Required and Set time limit (Recommended). Click the Create rule button.

9. The new policy should be created and active.