Overview
This article explains how you can add role based access control to the SmartDocs content in your Dev Portal. If you are looking for general information on how content access control works, check out our Content Access Control on Developer Portal article.
For this example, we have the “Weather API” and “Petstore Example” SmartDocs models on our Dev Portal. We are going to add access control so that only users with the “pet store api” role can view the “Pet Store Example API” Smartdocs API documentation.
By default, when you click the APIs menu link on the site, you will see a listing of all published API models. You can see we have two API models published on the site by default on an “out of the box” Developer Portal:
If you click on either of the links above, it will display all the SmartDocs methods for each model. For this example, we are going to use the Taxonomy Access Control Drupal module to hide the "Pet Store Example API from anonymous and registered users, and create a new role in the system that we can give to users to allow them to view the “Pet Store Example API” documentation.
Each of the SmartDocs methods are called nodes in Drupal. The way you group each node to a model is by using Drupal taxonomy. If you log in as an admin to your site you can see there is a taxonomy vocabulary named “SmartDocs models” by clicking Structure > Taxonomy on the admin menu. If you click on “list terms”, you will see that there is a term for each SmartDocs model:
If you click on “petstore_example”, you will see the listing page of all the nodes (pages) associated with this taxonomy term.
The Taxonomy Access Control module allows us to associate a user role to each of these terms in order to only display these terms and associated nodes with specific roles.
We will now go through configuring this example step by step.
Step 1: Install and enable Taxonomy Access Control module
The Taxonomy Access Control module is not in our default Dev Portal release, so you will need to install the module first. Installing modules is not the scope of this article and there is a lot of information on how to do this on the Internet, but here is a quick overview:
- If you are using Apigee cloud, you can add the module your site’s code using Git, or use SFTP mode to upload the module.
- If you are using our private cloud, use Drush to download the module (using the command "drush dl taxonomy_access_control") or download the module to your local computer, then scp it over to the sites/all/modules/contrib directory.
Once you have installed the module, as an admin go to Module in the admin bar, then search for the “Taxonomy Access Control”. Enable it, then click "Save configuration on the bottom of the screen.
Step 2: Create a role to add users to that should see our Pet Store API documentation
Privileges in Drupal are not given to users directly, but to roles which users can have. To hide our documentation we need to create a role for the persons that have access to see the documentation.
As an admin, click on People > Permissions > Roles to view the current roles in the system. On the bottom of the page add a role named “pet store example api” and click “Add role”:
Note that there are two default roles:
- anonymous user: This role is given to anyone browsing the website who is not logged in.
- authenticated user: This role is given to anyone logged in.
Step 3: Configure Taxonomy Access Control
We now need to configure the Taxonomy Access Control module, denying permission for “anonymous user” and authenticated users from viewing the Pet Store Example documentation, and granting access for anyone in the “petstore example api” role to view it.
Click on Configuration > People > Taxonomy access control, and you will now see a page listing the each role.
First, let’s configure the anonymous user role to not view the Pet Store documentation.
- Click on “Configure” next to “anonymous user”.
- Make sure the “Global default” has “View” set to “Allow”, and “View Tag” is set to “Allow”.
- Click on “Add vocabulary”, select “SmartDocs models”, then click “Add”.
- Set the “SmartDocs models” default “View” to “Ignore” and set the “View Tag” to “Allow”. This will make sure that by default all models can be viewed.
- Now, let’s deny the Pet Store model by denying access. Click “Add term”, pick “petstore_example” from the dropdown, change “View” to “Deny” and “View Tag” to “Deny”.
Click “Save all” on the bottom of the screen.
This image should make it more clear of what the access rules should look like for anonymous user once you are done:
If you open up the API list on your site in a browser where you are not logged in, you should no longer see the Petstore Example API.
Now that we have the anonymous users properly configured, we need to do the same for authenticated users and users who have our new “pet store example api” role. Let’s start with authenticated users:
- Click on Configuration > People > Taxonomy access control
- Click on “Configure” next to “authenticated user”.
- Make sure the “Global default” has “View” set to “Allow”, and “View Tag” is set to “Allow”.
- Click on “Add vocabulary”, select “SmartDocs models”, then click “Add”.
- Set the “SmartDocs models” default “View” to “Ignore” and set the “View Tag” to “Allow”. This will make sure that by default all models can be viewed.
- Now, let’s deny the Pet Store model by denying access to authenticated users. Click “Add term”, pick “petstore_example” from the dropdown, change “View” to “Deny” and “View Tag” to “Deny”.
Click “Save all” on the bottom of the screen.
This configuration should look exactly like the anonymous user configuration screen when you are done.
If you open up the API list on your site in a browser where you are logged in, you should no longer see the Petstore Example API. Make sure to use a user that does not have an administrator or any other role.
OK, one more to go, we will now configure the “pet store example api” role:
- Click on Configuration > People > Taxonomy access control
- Click on “Configure” next to “pet store example api”, and enable it if asked.
- Make sure the “Global default” has “View” set to “Allow”, and “View Tag” is set to “Allow”.
- Click on “Add vocabulary”, select “SmartDocs models”, then click “Add”.
- Set the “SmartDocs models” default “View” to “Ignore” and set the “View Tag” to “Allow”. This will make sure that by default all models can be viewed.
Since we do not need to deny access to any SmartDocs models for this role, we do not need to add and configure the “petstore_example” term.
Click “Save all” on the bottom of the screen. This image should make it more clear of what the access rules should look like for “pet store example api” role once you are done:
I hope this helps you understand how to configure access control for SmartDocs. You should not be able to understand how you can modify and change this example to suit your own needs.
More Resources
