Setting up guest access

From DreamFactory
Jump to: navigation, search
DreamFactoryTutorialsSetting up guest access
(completed GUI section)
(completed most of API section)
Line 30: Line 30:
 
::[[File:Guest_app_api_key.png|600px]]
 
::[[File:Guest_app_api_key.png|600px]]
  
'''3. Create CORS entry.'''
+
'''3. Create a 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.
+
:* To allow truly anyone to retrieve this resource, CORS must permit all domains to access this REST path. Navigate to 'Config' > 'CORS' and click [ + ] to create a new CORS Entry.
  
 
:: [[File:Guest_cors_create.png|450px]]
 
:: [[File:Guest_cors_create.png|450px]]
Line 42: Line 42:
  
 
'''4. Test.'''
 
'''4. Test.'''
:* [[DreamFactory/Tutorials/Setting_up_guest_access#Testing|Skip down to the testing heading.]]
+
:* [[DreamFactory/Tutorials/Setting_up_guest_access#Testing|Skip down to the testing section.]]
 +
 
 +
## Example: using the API
 +
 
 +
The below API calls will be made from cURL for the sake of raw simplicity.
 +
 
 +
'''1. Instantiate an admin session.'''
 +
:* Since the below changes are made to system resources, an Admin user session must be used to make these API calls. (Refer to the [[DreamFactory/Tutorials/Logging_in#Log_in_as_an_Admin|Logging In]] and [[DreamFactory/Tutorials/Access_Using_JWT|Access Using JWT]] tutorials for details.)
 +
 
 +
<source lang="bash">
 +
$ curl -X POST api/v2/system/admin/session \
 +
-d '{"email":"[email protected]","password":"password"}'
 +
 
 +
{
 +
  "session_token":"eyJ0eCblwx",
 +
  "session_id":"eyJ0eXUpa1",
 +
  "id":4,
 +
  "name":"Admin Name",
 +
  "first_name":"Admin",
 +
  "last_name":"Name",
 +
  "email":"[email protected]",
 +
  "is_sys_admin":true,
 +
  "last_login_date":"2015-11-02 20:26:58",
 +
  "host":"console"
 +
}
 +
</source><br />
 +
:* For the remainder of this tutorial, the <code>session_token</code> received in response to the above call will be passed with every API call as HTTP header <code>X-DreamFactory-Session-Token</code>.
 +
 
 +
'''2. Create a role with the desired access.'''
 +
:* Construct a JSON definition of the desired role configuration. In this case, the <code>files</code> service is known to have <code>"service_id":3</code>, <code>"verb_mask":1</code> is known to be GET, and <code>"requestor_mask":1</code> is known to be API.
 +
 
 +
<source lang="bash">
 +
{
 +
  "resource":
 +
    [
 +
      {
 +
        "name":"General Public",
 +
        "description":"Resources available to everyone without login.",
 +
        "is_active":true,
 +
        "role_service_access_by_role_id":
 +
          [
 +
            {
 +
              "verb_mask":1,
 +
              "requestor_mask":1,
 +
              "component":"images/",
 +
              "service_id":3
 +
            },
 +
            {
 +
              "verb_mask":1,
 +
              "requestor_mask":1,
 +
              "component":"images/*",
 +
              "service_id":3
 +
            }
 +
          ]
 +
      }
 +
    ]
 +
}
 +
</source><br />
 +
 
 +
:* POST this JSON to <code>api/v2/system/role</code> and receive back the id of the created role.
 +
 
 +
<source lang="bash">
 +
$ curl -X POST api/v2/system/role \
 +
-H 'X-DreamFactory-Session-Token: eyJ0eCblwx' \
 +
-d '{ "resource": [ { "name":"General Public", "description":"Resources available to everyone without login.", "is_active":true, "role_service_access_by_role_id": [ { "verb_mask":1, "requestor_mask":1, "component":"images/", "service_id":3 }, { "verb_mask":1, "requestor_mask":1, "component":"images/*", "service_id":3 } ] } ] }'
 +
 
 +
{"resource":[{"id":6}]}
 +
</source><br />
 +
 
 +
'''3. Create an API key for guest usage.'''
 +
:*
 +
 
 +
'''4. Create a CORS entry.'''
 +
:* To allow truly anyone to retrieve this resource, CORS must permit all domains to access this REST path.
 +
 
 +
'''5. Test.'''
 +
:* [[DreamFactory/Tutorials/Setting_up_guest_access#Testing|Skip down to the testing section.]]
  
 
## Testing
 
## Testing
::''Note: To allow cross-domain access (for example, while testing an app locally with a DreamFactory instance hosted elsewhere), you will need to [[DreamFactory/Tutorials/Enabling_CORS_Access|configure a CORS rule]].''
+
::''Note: To allow cross-domain access (for example, while testing an app locally with a DreamFactory instance hosted elsewhere), you will need to [[DreamFactory/Tutorials/Enabling_CORS_Access|configure a 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.''
 
::''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 <code>api/v2/files/images/?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9</code> to list the contents of the <code>images</code> folder:
+
To test from the REST API client or app of your choice, simply make an unauthenticated API call to the resource(s) you've made available using the API key you've created.
 +
 
 +
### Using a browser
 +
Since all browsers perform a GET by default, navigate to <code>api/v2/files/images/?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9</code> to list the contents of the <code>images</code> folder:
 
<source lang="javascript">{ "resource":
 
<source lang="javascript">{ "resource":
 
   [
 
   [
Line 66: Line 145:
 
}</source><br />
 
}</source><br />
  
:: Now that you know the two files that exist in the folder, you can retrieve <code>awesome.gif</code> by navigating to <code>api/v2/files/images/awesome.gif?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9</code>
+
Now that you know the two files that exist in the folder, you can retrieve <code>awesome.gif</code> by navigating to <code>api/v2/files/images/awesome.gif?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9</code>
  
:: [[File:Guest_access_browser_file.png|950px]]
+
[[File:Guest_access_browser_file.png|950px]]
  
:* For example, to list the contents of the <code>images</code> folder from cURL:
+
### Using cURL
 +
To list the contents of the <code>images</code> folder from cURL:
 
<source lang="bash">
 
<source lang="bash">
 
$ curl -X GET api/v2/files/images/ \
 
$ curl -X GET api/v2/files/images/ \
Line 78: Line 158:
 
</source><br />
 
</source><br />
  
:: And then to download <code>awesome.gif</code> to the current folder:
+
And then to download <code>awesome.gif</code> to the current folder:
 
<source lang="bash">
 
<source lang="bash">
 
$ curl -O -X GET api/v2/files/images/awesome.gif \
 
$ curl -O -X GET api/v2/files/images/awesome.gif \
Line 88: Line 168:
 
</source><br />
 
</source><br />
  
:* For example, from a REST client such as the POSTman extension for Google Chrome, to list the contents of the <code>images</code> folder:
+
### Using a REST client
 +
From a REST client such as the POSTman extension for Google Chrome, to list the contents of the <code>images</code> folder:
  
 
:: [[File:Guest_postman_folder.png|800px]]
 
:: [[File:Guest_postman_folder.png|800px]]
Line 95: Line 176:
  
 
:: [[File:Guest_postman_file.png|800px]]
 
:: [[File:Guest_postman_file.png|800px]]
 
### Example: using the API
 

Revision as of 20:52, 5 November 2015

    1. Tutorial

Setting up access to certain API services for unauthenticated users and users without login accounts, also known as guest access.

    1. 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.

    1. 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'.
Guest role basic.png
  • 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.
Guest role access.png
Note the two access components granted: images/ permits the role to list the contents of the folder by calling api/v2/images/ and images/* permits access to all contents of the folder.
  • 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'.
Guest app create.png
  • 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.
Guest app api key.png

3. Create a CORS entry.

  • To allow truly anyone to retrieve this resource, CORS must permit all domains to access this REST path. Navigate to 'Config' > 'CORS' and click [ + ] to create a new CORS Entry.
Guest cors create.png
  • 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'.
Guest cors save.png
  • Click 'Save' and observe a green pop-up message informing you "CORS entry created successfully."

4. Test.

    1. Example: using the API

The below API calls will be made from cURL for the sake of raw simplicity.

1. Instantiate an admin session.

  • Since the below changes are made to system resources, an Admin user session must be used to make these API calls. (Refer to the Logging In and Access Using JWT tutorials for details.)
$ curl -X POST api/v2/system/admin/session \
-d '{"email":"[email protected]","password":"password"}'
 
{
  "session_token":"eyJ0eCblwx",
  "session_id":"eyJ0eXUpa1",
  "id":4,
  "name":"Admin Name",
  "first_name":"Admin",
  "last_name":"Name",
  "email":"[email protected]",
  "is_sys_admin":true,
  "last_login_date":"2015-11-02 20:26:58",
  "host":"console"
}

  • For the remainder of this tutorial, the session_token received in response to the above call will be passed with every API call as HTTP header X-DreamFactory-Session-Token.

2. Create a role with the desired access.

  • Construct a JSON definition of the desired role configuration. In this case, the files service is known to have "service_id":3, "verb_mask":1 is known to be GET, and "requestor_mask":1 is known to be API.
{
  "resource":
    [
      {
        "name":"General Public",
        "description":"Resources available to everyone without login.",
        "is_active":true,
        "role_service_access_by_role_id":
          [
            {
              "verb_mask":1,
              "requestor_mask":1,
              "component":"images/",
              "service_id":3
            },
            {
              "verb_mask":1,
              "requestor_mask":1,
              "component":"images/*",
              "service_id":3
            }
          ]
      }
    ]
}

  • POST this JSON to api/v2/system/role and receive back the id of the created role.
$ curl -X POST api/v2/system/role \
-H 'X-DreamFactory-Session-Token: eyJ0eCblwx' \
-d '{ "resource": [ { "name":"General Public", "description":"Resources available to everyone without login.", "is_active":true, "role_service_access_by_role_id": [ { "verb_mask":1, "requestor_mask":1, "component":"images/", "service_id":3 }, { "verb_mask":1, "requestor_mask":1, "component":"images/*", "service_id":3 } ] } ] }'
 
{"resource":[{"id":6}]}

3. Create an API key for guest usage.

4. Create a CORS entry.

  • To allow truly anyone to retrieve this resource, CORS must permit all domains to access this REST path.

5. Test.

    1. 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 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.

To test from the REST API client or app of your choice, simply make an unauthenticated API call to the resource(s) you've made available using the API key you've created.

      1. Using a browser

Since all browsers perform a GET by default, navigate to api/v2/files/images/?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9 to list the contents of the images 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 to api/v2/files/images/awesome.gif?api_key=c448049d7eecd5337b7cc531d68b0d46a94cd8eb8555ba1de3fb05566cad66d9

Guest access browser file.png

      1. Using cURL

To list the contents of the images folder from cURL:

$ 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:

$ 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

      1. Using a REST client

From a REST client such as the POSTman extension for Google Chrome, to list the contents of the images folder:

Guest postman folder.png
And then to retrieve awesome.gif:
Guest postman file.png