Setting up guest access
- Tutorial
Setting up access to certain API services for unauthenticated users and users without login accounts, also known as guest access.
- Background
You may provide access to certain API services and resources based on the provisioned API key alone, without requiring authentication or session instantiation. The permissions granted these users are based solely on the API key they provide and the access granted by the default role of that API key. Calls to the API using this API key will be treated as guest calls as long as no session token is provided along with the call, so both non-existent users and not-logged-in users are treated the same with respect to access.
- Example: using the admin app GUI
1. Create a role with the desired access.
- Navigate to 'Roles' > 'Create', enter 'Name' and 'Description' values, and check the box labeled 'Active'.
-
- Navigate to the 'Access' tab of the role being created and add access rule(s) as desired. In this example, we will allow GET access to all contents of the local storage folder called
images
.
- Navigate to the 'Access' tab of the role being created and add access rule(s) as desired. In this example, we will allow GET access to all contents of the local storage folder called
- Note the two access components granted:
images/
permits the role to list the contents of the folder by callingapi/v2/images/
andimages/*
permits access to all contents of the folder.
- Note the two access components granted:
- Click 'Create Role' and observe a green pop-up message informing you "Role saved successfully."
2. Create an API key for guest usage.
- Navigate to 'Apps' > 'Create', enter 'Application Name' and 'Description' values, select the role you created in step #1 under 'Assign a Default Role', and check the box labeled 'Active'.
-
- Click 'Create Application' and observe a green pop-up message informing you "{Application Name} saved successfully."
- Navigate back to 'Apps' > 'Manage', click on the row of the app you just created, and make note of the API key that has been generated for you.
3. Create CORS entry.
- To allow truly anyone to access this resource, CORS must allow all domains access to this REST path. Navigate to 'Config' > 'CORS' and click [ + ] to create a new CORS Entry.
- During development and testing, a CORS entry with Origin=*, Paths=*, Headers=*, Max Age=0, and all Methods permitted is the easiest to work with. When moving into production, security can be further restricted. For this example, we only need to provide GET Method access to
api/v2/files/images/*
. So enter Origin=*, Paths=api/v2/files/images/*, Headers=*, Max Age=0, select the GET Method, and check the box labeled 'Enabled'.
- During development and testing, a CORS entry with Origin=*, Paths=*, Headers=*, Max Age=0, and all Methods permitted is the easiest to work with. When moving into production, security can be further restricted. For this example, we only need to provide GET Method access to
- Click 'Save' and observe a green pop-up message informing you "CORS entry created successfully."
4. Test.
- Testing
- Note: To allow cross-domain access (for example, while testing an app locally with a DreamFactory instance hosted elsewhere), you will need to configure a CORS rule.
- During development and testing, a CORS entry with Origin=*, Paths=*, Headers=*, Max Age=0, and all Methods permitted is the easiest to work with.
- From the REST API client of your choice, make an unauthenticated API call to the resource(s) you've made available using the API key you've created.
- For example, from a browser, since all browsers perform a GET by default, navigate to
api/v2/files/images/?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9
to list the contents of theimages
folder:
{ "resource": [ { "path":"images/awesome.gif", "content_type":"image/gif", "last_modified":"Thu, 05 Nov 2015 15:44:11 GMT", "content_length":25947, "name":"awesome.gif", "type":"file" }, { "path":"images/howrude.jpg", "content_type":"image/jpeg", "last_modified":"Thu, 05 Nov 2015 16:11:08 GMT", "content_length":17436, "name":"howrude.jpg", "type":"file" } ] }
- Now that you know the two files that exist in the folder, you can retrieve
awesome.gif
by navigating toapi/v2/files/images/awesome.gif?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9
- Now that you know the two files that exist in the folder, you can retrieve
- For example, to list the contents of the
images
folder from cURL:
- For example, to list the contents of the
$ curl -X GET api/v2/files/images/ \ -H 'X-DreamFactory-Api-Key: c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9' {"resource":[{"path":"images/awesome.gif","content_type":"image/gif","last_modified":"Thu, 05 Nov 2015 15:44:11 GMT","content_length":25947,"name":"awesome.gif","type":"file"},{"path":"images/howrude.jpg","content_type":"image/jpeg","last_modified":"Thu, 05 Nov 2015 16:11:08 GMT","content_length":17436,"name":"howrude.jpg","type":"file"}]}
- And then to download
awesome.gif
to the current folder:
- And then to download
$ curl -O -X GET api/v2/files/images/awesome.gif \ -H 'X-DreamFactory-Api-Key: c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9' % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 25947 100 25947 0 0 193k 0 --:--:-- --:--:-- --:--:-- 193k
- For example, from a REST client such as the POSTman extension for Google Chrome, to list the contents of the
images
folder:
- For example, from a REST client such as the POSTman extension for Google Chrome, to list the contents of the
- And then to retrieve
awesome.gif
:
- And then to retrieve
- Example: using the API