Before you begin
- No Other Authentication Module should be installed.
- No other AuthAnvil Module for WordPress should be installed.
- You will need to remove any Module that fall into the criteria above before continuing.
Configuring AAOD and Drupal users
- Users are linked by username when using AAOD for authentication.
- This means that the username used to log onto Drupal must match the username used to sign into AAOD.
Configuring Web Auth Agent
2FA policy and agent Policy: You will need to create a policy for 2FA only prompting.
- To configure this policy do this, log onto AAOD and go to the Policy Manager section.
- Click the green plus (+) sign at the bottom right to add a new Policy.
- You will be presented with a blank policy screen.
- Fill in a name for your new policy. You can name it whatever you like.
- For the 'Select Policy Element', click the drop down and select 'User'.
- You will see a 'Select Criteria' drop down appear to the right.
- Open the drop down and pick 'Is signing in'
- in the 'then' section, open the drop down entitled 'Select action'
- Open the drop down and select 'Set Allowed Methods'.
- To the right you will see some options. Uncheck 'Require Password Authentication'.
- click the green plus (+) sign just below the 'Set Allowed Methods'
- Open the 'Select Action' drop down menu and select 'Require MFA'.
You can verify your new Policy by checking it against the provided screen shot of a completed 2FA policy.
Create a web auth embedded application
- Go to the Auth Manager->Agents section and select the green plus(+) sign at the bottom left to add a new agent.Select 'Embedded Web Auth' as the agent type.
- Give your agent a Name: Name your agent- something descriptive like "Drupal 2FA Agent".
- Redirect URI needs to be filled in. The Redirect URI should be the url to your Drupal landing page. ie: http://<my Drupal 7 server name>/acquia-drupal7/
- Set the 'Authentication Policy' to the Policy created in the creating a policy step.
You should see the name of the policy in the drop down.
- you will need the values of the following Agent fields when configuring Drupal:
ID, Key and Home Realm.
- Make a note of them.
- Click the Add Agent Button at the bottom right.
- AAOD configuration is complete
- Settings required from you AAOD web auth agent. You will need the home Realm, Agent id and Agent Key values when configuring Drupal
Install the Module
- Download the AuthAnvil On Demand Logon Agent for Drupal from here.
- The Module is also available from the Drupal store.
- Upload the zip file to Drupal via the modules menu and follow the installation.
Enable the Module
- In the Module menu, find the AuthAnvil Demand Module and enable it.
Configure the Module
Create and Configure 2FA role in Drupal
Important: if you do not perform this step, you may not be able to log on to Drupal.
- From the Modules menu, find the AuthAnvil On Demand Logon Agent and click the permissions link. By default, any role added to Drupal is enabled for administrators.
- Uncheck The option to require AuthAnvil On Demand 2FA for administrators.
Adding a new Role
- We are going to add a new role.
- Click the Roles button.
- Give the new role a name ie: 'Authenticate with 2FA'
- Save the new Role.
- Go back to the permissions section and enable AuthAnvil On Demand 2FA for the new Role.
Assign new Role to users
To enable 2FA authentication for a given Drupal user, edit the user and add the new 2FA Role to the user.
Important Note: A Drupal user will also have to exist on AAOD, as noted at the begining of this document.
Any user that does not also exist as an AAOD user will not be able authenticate with 2FA and will be blocked.
Note: it is highly recommended that the user's username that your are currently logged into Drupal with has a matching user on AAOD.
- Go to the configuration module and find AuthAnvil On Demand 2FA and click on it.
- This will open the configuration screen.
- Enter the HomeRealm, Agent Key and Agent ID values obtained from AAOD.
- There is an option for enabling 2FA authentication for the Super Admin. This is the the Drupal user with the user id of 1.
- The Super Admin always has access to all roles even if they are not 2FA role enabled. Checking this setting will force the Super Admin to use 2FA to logon. The 2FA authentication for the Super Admin is turned off by default to ensure you do not lock your self out of your site when configuring the AuthAnvil On Demand Logon Agent.
Please note: This is the only place you can control the Super Admin 2FA prompt.
- Save the configuration.
- The Sign on preview screen will load.
- If you are logged on as a user that exists in AAOD, then you should see a sign in screen prompting for a 2FA authentication method.
- If you are logged on as a user that does not exist in AAOD, the preview window will show a dialog: 'Server Authentication is unavailable'.
- The preview window emulates what will be show for the given user at log on if they are 2FA role enabled.
- The preview window is read only.
Testing the Agent
Before you log off of Drupal, make sure you have at least one administrative user that is not 2FA role enabled and/or you have disabled 2FA for the super admin. This will allow you access to your site in case there is an unforeseen error.
Disabling authentication if you are locked out of the site
- The easiest way to disable the AAOD Authentication is to have access to the physical files for your site.
- Navigate to the folder that contains the AuthAnvil module ie: acquia-drupal7\sites\all\modules
- Make a backup copy of the 'authanvil_on_demand_logon_agent' folder and store somewhere safe.
- Now delete or move the original 'authanvil_on_demand_logon_agent' folder.
- There should not be an 'authanvil_on_demand_logon_agent' folder within the Drupal site.
- You should now be able to log onto Drupal without being prompted for 2FA.
- You will see some errors , that is expected.
- Once you are logged onto the site, copy the 'authanvil_on_demand_logon_agent' folder back to it's
- Original position from your backup location.
- Refresh the page and the errors should disappear.
- You can now modify your AuthAnvil On Demand settings to correct the issue.