Web access management (WAM)
Traditionally WAM was handled either via proprietary agent software installed on each target node or via a reverse proxy architecture. Nevis uses the latter approach.
Proxy access to Google.com
- Authenticate to Nevis. You are presented with a welcome screen directing you to create or import a fresh project. However, we will first introduce you to the default inventory.
- Select the “Infrastructure” tab. Observe that a default inventory called “NEVIS” was created as part of the installation.
- Observe that:
- The “schemaType” is set to “Kubernetes”.
- The “consts” (constants) section specifies some values that can be re-used in multiple variables - this can make configuration more efficient whereby changing a single constant can then automatically update multiple variables.
- The “services” section is remarked out (as in a Kubernetes deployment, there is no need to define the services).
- The “vars” (variables) section provides some sample variables that apply to the entire inventory and can make project configuration more efficient.
- The “deployment-repository” section contains the configuration to connect to the Git deployment repository. Generated service configurations are transferred to Kubernetes via this repository.
- The “kubernetes-cluster” section contains the configuration to connect to the Kubernetes cluster for the deployment. As this nevisAdmin4 is also running within Kubernetes, it is only necessary to specify the namespace that the nevis components will be deployed into.
- Highlight and copy the “deployment-repository url” to your buffer. It should be “ssh://[email protected]/azuregitea/deploy.git” (We will need this in a moment.).
- As we haven’t changed any config at this point, there should be no need to select the “Save changes” button.
- Return to the “Configuration” tab.
- We will be building a project from scratch, so beneath the Welcome message, select “Create project”.
- Enter your custom “Project key”. In our example, we named the project “Workshop”.
- Tick the option “Enable GIT”
- Paste your buffer contents (from step 4) into the “Git repository field”.
This URL is specifically for the deploy repository that Admin4 uses when deploying the configuration. However, as a best practice we should use different repositories for deployments, projects and inventories. The bundled gitea instance now comes with 3 repositories setup:
- deploy.git
- project.git
- inventory.git
- As we want to use the “project.git”, adjust the Git repository URL so that it is now “ssh://[email protected]/azuregitea/project.git”.
- Select the refresh icon within the input field. This will contact git and populate the Branch information (“master”).
- Leave other fields unchanged.
- Click “Create”.
- Observe that your new project will be selected (converted to uppercase) and that there is a warning status, as it is currently blank.
- Click the “+” symbol to add a pattern.
- Use the search window to find the “nevisProxy Instance” pattern and add it.
- Note the default name that is assigned. Click on the name and change it to remove the “New” part i.e. a sensible name to use is simply “nevisProxy Instance”.
- Within the “Basic Settings” tab, for “Deployment Target”, enter the name “proxy” (With a classic deployment, that name would also have to be specified in the inventory, so that there is a match. But with a Kubernetes deployment, that is not required, so you could use any name you wish.).
- Save changes. Note that the status will still be red at this point.
- Click the “+” symbol to add a pattern.
- This time, search for and select the “Virtual Host” pattern.
- Change the name to “Virtual Host”.
- Within the “Basic Settings” tab, for the nevisProxy value, select the previously-created “nevisProxy Instance”.
- For the Frontend Addresses, we will use a variable that was automatically specified by the deployment within the default inventory. The variable name is “domain”. In this way, IF you had multiple stages (e.g. Prod and Test) which had their own specific inventories, then that variable would be assigned the relevant stage-specific value. You will need both the variable name and a sample value (for validation). Probably the easiest way to do this is to switch to the “Infrastructure>>NEVIS” view (save changes first, if prompted) and copy the contents of the “azure-domain” constant value into your buffer (e.g. https://xxx.yyy.cloudapp.azure.com”).
- Back in “Configuration” >> “Patterns” view, click on the “var” icon next to the Frontend Addresses tag. Replace the suggested variable name with “domain”. Also, paste your buffer into the “Sample value” field.
- Click “Set variable”.
- Save changes.
- Note that the status of the WORKSHOP project is now green.
At this point, we have specified an instance of the proxy and a logical virtual host assigned to it. The config has a front-end listener but we now need to tell nevisProxy where to proxy requests to. At this stage we will proxy to just one service - Google, for illustrative purposes. Of course, in most deployments a single virtual host / nevisProxy Instance combination will handle multiple target proxied sites (multi-homing).
- Click the “+” symbol to add a pattern.
- This time, search for and select the “Web Application” pattern.
- Change the name to “Google Web App”.
- Within the “Basic Settings” tab, for “Virtual Hosts”, select the “Virtual Host” pattern you created earlier.
- For “Frontend Path(s)” enter “/” - which means all requests to our frontend will be forwarded via this particular pattern (unless patterns with more specific paths are added at a later point).
- Select the “Backend Connection” tab.
- For “Backend addresses”, enter “https://www.google.com”.
nevisProxy implements web application firewall functionality (WAF) that includes enforcing the OWASP ModSecurity Core Rule Set (CRS) which is a set of generic attack detection rules for use with ModSecurity or compatible web application firewalls. These can lead to some false positives such that the settings may need to be adjusted. However, due to time constraints, we won’t be addressing ModSecurity in detail in this course and so we will simply disable such checks.
- From the “Security” tab, set “Request Validation (ModSecurity)” to “off”.
- Save changes.
Testing
- After the changes have been saved, deploy your project.
- Within the pop-up window, make sure the “WORKSHOP” project, “NEVIS” inventory and “Primary” Deploy as options are selected. Then click “Validate deployment”.
- Assuming validation is successful, select “Preview deployment”.
- Expand and view the preview items and observe some of the details.
- When you’re ready, click “Deploy now”.
- After perhaps 30 secs or so observe successful completion. You can click on “Close wizard”.
- Back on your test browser tab, hit refresh - you should now observe the Google homepage (most likely with Google’s cookie statement).
- If you have access, return to the Azure Portal and within your “Kubernetes service” object, under the “Kubernetes resources” section, select “Services and ingresses” and see that the "proxy" ingress have been added.
- It is good practice to keep the config in GIT uptodate (so that you can recover from erroneous changes in future), from the Configuration tab, select the action to “Publish to Git”.
- Observe the config changes and modify the “Publish comment” if you wish, to reflect the exercise completed.
- Select the “Publish” button.
- Select the “OK, Return” button in the pop-up to acknowledge the result and return to the “Patterns” view.
- Select the “Revert” option and observe the dropdown list of previously stored revisions. This is a very useful capability to recover to a known good state. We will publish to git after completion of each subsequent lab exercise where the project is updated.
- Select “Cancel” as we don’t need to revert any configuration at this point.
This publishing to Git only relates to the configuration and its patterns. It does not include the inventory we are using from the infrastructure tab. We will now also connect your inventory to the GIT repository called “inventory” that is present by default with an Azure deployment. Although there is no “Revert” to a specific previous configuration with inventories, there IS the option to “Clear local changes” which will restore the configuration to the last published configuration which is useful in case an accidental misconfiguration is made.
- Select the “Settings” option on the “Infrastructure” tab.
- On the right-hand side, select the “Connect to Git”. Browser autofill will probably suggest your previous value. Modify it to reflect the “inventory.git” repository i.e. “ssh://[email protected]/azuregitea/inventory.git”.
- Select the refresh icon within the input field. This will contact git and populate the Branch information (“master”).
- Leave the Directory field unchanged.
- Click “Connect”.
- Select “Publish to Git”.
- Observe the config changes and modify the “Publish comment” if you wish, to reflect the exercise completed.
- Select the “Publish” button.
- Select the “OK, Return” button in the pop-up to acknowledge the result.
Adding Local Authentication
In this exercise we will build out a series of patterns that together will permit user authentication based upon initial default credentials held within the nevisIDM component.
- From the “Patterns” view, add a new pattern of type “nevisAuth Database” and change the name to “nevisAuth Database”.
- Within the “Basic Settings” tab, for “Database Type”, select “PostgreSQL”.
- For “Database Host”, click the “var” icon. Replace the suggested variable name with “auth-db-host” and click “Set variable”.
- Click the “Save changes” button.
- Select the Infrastructure tab and ensure the “NEVIS” inventory is selected. Within the main window, locate and copy the PostgreSQL endpoint via the “database-host” constant. It will look something like “postgrese861ce37.postgres.database.azure.com”. Copy it into your buffer.
- From Configuration >> Variables view, locate the new variable and paste in the contents of your buffer as the “Sample value”.
- Save changes.
For “Database Host”, we will use a variable to reference the specific PostgreSQL instance used in your cluster. Recall that in the real world, this will allow you to have a unique value per stage/environment which uses a common variable name in the configuration. In this case, your default NEVIS inventory already has a variable defined as a result of the OneClick installation. It is called “auth-db-host”. However, the variable name has not yet been added to this new Project and so must be referenced AND also, for validation purposes, the variable must be assigned a sample name (we will use the real name for your instance for clarity).
- Back in the “nevisAuth Database” pattern, within the “Basic Settings” tab, for “Root Credential”, click the “var” icon.
- For “Variable name”, replace the suggested name with “k8s-root-credential” (which was specified in the default inventory) and click “Set variable”.
- Save changes.
- From the “Patterns” view, add a new pattern of type “nevisAuth Instance” and change the name to “nevisAuth Instance”.
- Within the “Basic Settings” tab, for “Deployment Target”, enter “auth” (With a classic deployment, that name would also have to be specified in the inventory so that there is a match. But with a Kubernetes deployment, that is not required, so you could use any name you wish.).
- For “Database”, select the “nevisAuth Database” pattern you created above.
- Click the “Save changes” button.
- From the “Patterns” view, add a new pattern of type “NEVIS SecToken” and change the name to “NEVIS SecToken”.
- Select the “Content” tab and observe the default attributes that will be added to any created SecT okens - this is what will be passed to the nevisIDM Administration GUI (which we will be creating in a moment) for authentication purposes.
- Save changes.
- From the Patterns view, add a new pattern of type “nevisIDM Database” and change the name to “nevisIDM Database”.
- Within the “Basic Settings” tab, for “Database Type”, select “PostgreSQL”.
- For “Database Host”, click the “var” icon. Replace the suggested variable name with “idm-db-host” and click “Set variable”.
- Save changes.
For “Database Host”, as with the nevisAuth database, we will use a variable that is already defined in your default NEVIS inventory (“idm-db-host” ) to reference the specific PostgreSQL instance used in your cluster. As all the databases used in this training are provided from a single PostgreSQL service, we could use the same variable name as for the nevisAuth database, but we will follow the default inventory convention and specify unique variable names. As before, the variable name has not yet been added to this new Project and so must be referenced AND also, for validation purposes, the variable must be assigned a sample name (we will use the real name for your instance for clarity).
Select the Infrastructure tab and ensure the “NEVIS” inventory is selected. Within the main window, locate and copy the PostgreSQL endpoint via the “database-host” constant. It will look something like “postgrese861ce37.postgres.database.azure.com”. Copy it into your buffer.
From Configuration >> Variables view, locate the new variable and paste in the contents of your buffer as the “Sample value”.
Click the “Save changes” button.
Back in the “nevisIDM Database” pattern, within the “Basic Settings” tab, for “Root Credential”, click the “var” icon.
For “Variable name”, select the existing “k8s-root-credential” (which was specified in the default inventory) and click “Set variable”.
Click “Save changes”.
From the Patterns view, add a new “nevisIDM Instance” pattern.
Within the “Basic Settings” tab, for “Deployment Target”, enter “idm”. (With a classic deployment, that name would also have to be specified in the inventory so that there is a match. But with a Kubernetes deployment, that is not required, so you could use any name you wish.)
Scroll down and for “Database”, select the “nevisIDM Database” pattern you created above.
For “Encryption Key”, click the “var” icon. We can accept the default variable name (“nevisidm-instance-encryption-key”). Click “Set variable”.
Save changes.
Encryption KeyFor “Encryption Key” we basically need a random string of characters in Base64 format that is either 8,16, or 24 bytes in length. If you have OpenSSL handly, the recommended way to generate the string is to use “openssl rand -base64 16”. If not, for this workshop we can simply use an example key in the correct format (NOT FOR PRODUCTION USE) - HCI0iyMAEgQli+Z0gQdAyA==. If you wish to copy and paste this string then you will find an electronic version of this document in pdf format from the “SupportingMaterials.zip” file you downloaded in Exercise A. Additionally, the pattern wants to encourage best practice and so also suggests using a variable. Furthermore, the key itself will be inserted into the config as a secret and so not be directly readable within the configuration.
Select the “variables” tab and note that the variable name has been added.
Select the "Infrastructure" tab and ensure the “NEVIS” inventory is selected. Within the main window, add a new line in the “vars” section (spacing is critical, so ensure that the variable is preceded by 2 spaces - NOT a tab). Paste in the variable name followed by a colon and space. e.g. “nevisidm-instance-encryption-key:”.
Click the padlock symbol at the bottom which has the tooltip label of “Insert secret” and within the pop-up enter your Base64 random string (at least 18 bytes long - use “HCI0iyMAEgQli+Z0gQdAyA==” if you don’t have your own) and click “Insert secret”. It should look something like:
Click “Insert secret”.
Save changes.
Return to the “Configuration” >> “Patterns” view.
From the “Patterns” view, add a new “nevisIDM Password Login” pattern.
Within the “Basic Settings” tab, for “nevisIDM”, select the “nevisIDM Instance” pattern you created above.
Save changes.
From the Patterns view, add a new “nevisLogrend Instance” pattern.
Within the “Basic Settings” tab, for “Deployment T arget”, enter “login”. (With a classic deployment, that name would also have to be specified in the inventory so that there is a match. But with a Kubernetes deployment, that is not required, so you could use any name you wish.)
Save changes.
From the “Patterns” view, add a new “Authentication Realm” pattern and call it “Password Realm”.
Within the “Basic Settings” tab, for “Initial Authentication Flow”, select the “nevisIDM Password Login” pattern you created above.
For “Application Access Tokens”, select the “NEVIS SecToken” pattern you created above.
On the “nevisAuth Connection” tab, for “nevisAuth”, select the “nevisAuth Instance” pattern you created above.
On the “GUI Rendering” tab (you may have to scroll across), for “Login renderer” select the “nevisLogrend Instance” pattern you created above.
Save changes.
The final configuration step is to actually apply the new authentication configuration to the Google Web Application:
- Select the “Google Web App” pattern.
- For “Authentication Realm”, select the “Password Realm” that you created above.
- Save changes.
- Deploy your project.
- Within the pop-up window, make sure the “WORKSHOP” project, “NEVIS” inventory and “Primary” Deploy as options are selected. Then click “Validate deployment”.
- Assuming validation is successful, select “Preview deployment”.
- Expand and view the preview items and observe some of the details.
- When you’re ready, click “Deploy now”.
- After a couple of minutes, observe successful completion. You can click on “Close wizard”.
Testing
Enable access to the nevisIDM Administration GUI
- From the “Patterns” view, add a new “nevisIDM Administration GUI” pattern
- Within the “Basic Settings” tab, for “Virtual Hosts”, select the “Virtual Host” pattern you created in Exercise B.
- For “nevisIDM”, select the “nevisIDM Instance” pattern you created in "Adding a Local Authentication".
- For “Authentication Realm”, select the “Password Realm” pattern you created in "Adding a Local Authentication".
- For “Application Access Token, select the “Nevis SecToken” pattern you created in "Adding a Local Authentication".
- Click “Save changes”.
- Deploy your “WORKSHOP” project to the “NEVIS” inventory as “Primary”.
- If you want to see a summary of the endpoints that are actually protected, select the “Overview” option on the left-hand side.
- Select the “Applications” tab and observe the paths
- Select the “Reports” tab from the left-hand navigation.
- Select the “Application Mapping Report”.
- Ensure that the “NEVIS” inventory is selected from the dropdown and then press “Generate”. This shows a little more information than the project overview - in particular the backend address/path information.
Create test user
- From the tab used in step 14, return to “/nevisidm/admin” and click “Create user” from the left-hand navigation.
- Provide the following information:
- Login ID - testuser
- Last name - User
- First name - Test
- Email - [email protected]
- Phone number - 0123456789
- Mobile phone - +44123456789
- Leave all other values at default (either blank or pre-set)
- Click “Save”.
- Under “User credentials”, click “New”.
- Click on the “Type” dropdown and observe the different supported mechanisms. We will be using the default “Password” type in this exercise.
- Attempt to save a password of “password” in both the “New value” and “Confirmation” fields.
- Observe that you are not permitted, as it does not comply with the default policy. This gives you an idea of the control you have over the password policy.
- Provide your desired (compliant) initial password in both the “New value” and “Confirmation” fields.
- Click on the dropdown next to the “Boot Strap” user account in the top right corner.
- Click the “logout” link and observe that you are taken to a page with “?logout” appended. In other words, selecting the nevisIDM logout option will also terminate the nevisProxy session.
- Click “Continue”.
- Try to login with your new “testuser” account using the password you set in step 8.
- Observe that again, due to the default password policy, you will be prompted to change the password on first access (after an admin-driven change of password).
- After changing your password, observe that you are taken to the nevisIDM selfadmin page (as the testuser has no rights to the actual “admin” page.
You can set up a different nevisIDM password policy which does not require the password to be changed on 1st access if you wish.
Completing a real-world deployment
This final WAM exercise is to introduce additional patterns which would typically also be deployed in the real world. This diagram illustrates the four new patterns to add:
As the 4 suggested patterns are all leaf patterns, rather than creating them in isolation first, select the existing relevant patterns (see diagram above) and start configuration from those patterns.
![Here the training uses this section as a challenge lab, and so no detailed instruction is provided. That is fine for training purposes, but for DOCS, this section must be as detailed as the rest.]
- For the three log patterns, setup is straightforward, the UI highlights the mandatory fields in red that need to be set.
- For the database-related pattern, you need to specify the database host. Although the same database service is used here, that may not always be the case.
- For the nevisProxy Remote/Hybrid Session Store create a new variable called “proxy-db-host” (which will match the inventory).
- You can set a meaningful “Sample value” for validation purposes, but as the variable will be populated with the value specified in the inventory you can simply use a value of “x” which will satisfy the UI validation requirement.
- Make sure to set the “Database Type” to “PostgreSQL”.
- You also need to specify the Root Credential - you can use the same variable that you originally defined in "Adding Local Authentication".
- Publish to Git.