http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/authenticating-api-requests.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/authenticating-api-requests.txt b/content/docs/_sources/security-and-auth/authenticating-api-requests.txt new file mode 100644 index 0000000..af52bf6 --- /dev/null +++ b/content/docs/_sources/security-and-auth/authenticating-api-requests.txt @@ -0,0 +1,38 @@ +# Authenticating API requests + +With the exception of the 'sandbox' application that is created with every Usergrid organization, all applications are secured by default. This means that to access your data store, a valid access token must be sent with all API requests to authenticate that the requester is authorized to make API calls to the resources they are attempting the access. + +This article describes how to use access tokens to access the Usergrid API, and how to manage access tokens, including revoking and changing token time to live. + +For information on generating access tokens/authenticating users and clients, see Authenticating users and application clients. + +## Authenticating with access tokens +When you obtain an access token, you must provide it with every subsequent API call that you make. There are two ways to provide your access token. + +You can add the token to the API query string: + + https://<usergrid-host>/{org-name}/{app-name}/users?access_token={access_token} + +You can include the token in an HTTP authorization header: + + Authorization: Bearer {access_token} + +<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">⨠+Note: The Usergrid documentation assumes you are providing a valid access token with every API call whether or not it is shown explicitly in the examples. Unless the documentation specifically says that you can access an API endpoint without an access token, you should assume that you must provide it. One application that does not require an access token is the sandbox application. The Guest role has been given full permissions (/** for GET, POST, PUT, and DELETE) for this application. This eliminates the need for a token when making application level calls to the sandbox app. For further information on specifying permissions, see Managing access by defining permission rules. +</p></div> + +## Authenticating with client ID and client secret + +Another option for authenticating your API requests is using either your organization client ID and client secret, or your application client ID and client secret, which will authenticate your request as an organization or application admin, respectively. Organization credentials can be found in the 'Org Overview' section of the admin portal, and application credentials can be found in the 'Getting Started' section of the admin portal. + +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+Warning: For server-side use only +You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See Security best practices for additional considerations in keeping access to your app and its data secure. +</p></div> + +This can be a convenient way to authenticate API requests, since there is no need to generate and manage an access token, but please note that you should be very cautious when implementing this type of authentication. Organization-level authentication grants full permission to perform any supported call against your organization and every application in it, and application-level authentication grants full permission to perform any supported call against all of the resources in an application. Should your client id and client secret be compromised, a malicious user would gain broad access to your organization or application. + +To authenticate using client id and secret, append the following parameters to your request URL: + + client_id=<your-client-id>&client_secret=<your-client-secret> + \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt b/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt new file mode 100644 index 0000000..eaa52f4 --- /dev/null +++ b/content/docs/_sources/security-and-auth/authenticating-users-and-application-clients.txt @@ -0,0 +1,128 @@ +# Authenticating users & app clients + +To protect your Usergrid application data, one of the steps you'll take is to authenticate your app's users. By ensuring that they are who they say they are, you can help ensure that your application's data is available in secure ways. After you've created permission rules that define access to your application and have associated these rules with users, you'll want to add code that authenticates your user, as described in this topic. + +<div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">⨠+You manage access to your application's data by creating permission rules that govern which users can do what. Users authenticated as Application User have access according to these rules. For more about managing permissions, see [Using Permissions](using-permissions.html). +</p></div> + + +## Authentication levels +Usergrid supports four levels of authentication: + +* __Application user__: Grant's user access to an API Services application, based on the roles and permissions assigned to the user. +* __Application client__: Grants full access to perform API requests against an API Services application. +* __Organization client__: Grants full access to perform API requests against an API Services organization. +* __Admin user__: Grants full access to perform API requests against any API Services organization that the user is an admin of. + +Because the scope of access provided by the application client, organization client, and admin user authentication levels is so broad (and as a result, so powerful), it's a bad practice to use them from a mobile app or any client-side code. Instead, they're better suited to server-side implementations, such as web applications. + +For a more detailed description of available authentication levels, see [Authentication levels](user-authentication-types.html). + +## Application user authentication (user login) +Using the username and password values specified when the user entity was created, your app can connect to the Usergrid application endpoint to request an access token. It's also acceptable to use the user's email address in place of the username. + +### Using the SDKs +When a user is logged in using the Usergrid iOS, JavaScript, node.JS and Android SDKs, the returned token is automatically stored in the UsergridDataClient (iOS), DataClient (Android), or Usergrid.Client (JavaScript/node.JS) class instance, and will be sent to the API with all subsequent method calls. + +#### Request syntax + + curl -X POST "https://api.usergrid.com/<orgName>/<appName>/token" -d '{"grant_type":"password", "username":<username>, "password":<password>}' + +#### Example request + + curl -X POST "https://api.usergrid.com/my-org/my-app/token"; -d '{"grant_type":"password", "username":"john.doe", "password":"testpw"}' + +#### Example response + +The results include the access token needed to make subsequent API requests on behalf of the application user: + + { + "access_token": "5wuGd-lcEeCUBwBQVsAACA:F8zeMOlcEeCUBwBQVsAACA:YXU6AAABMq0hdy4", + "expires_in": 3600, + "user": { + ... + } + } + +## Application client authentication +Using your appâs client id and client secret values, your app can connect to the Usergrid application endpoint to request an access token. The client ID and secret for your app can be found in 'Getting Started' section of the API Services admin portal, under 'Server App Credentials'. + +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+Warning: You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html) for additional considerations in keeping access to your app and its data secure. +</p></div> + +### Request syntax + + curl -X POST "https://api.usergrid.com/<orgName>/<appName>/token" -d '{"grant_type":"client_credentials", "client_id":<application_clientID>, "client_secret":"<application_client_secret>"}' + +### Example request + + curl -X POST "https://api.usergrid.com/my-org/my-app/token"; -d '{"grant_type":"client_credentials", "client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ", "client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}' + +### Example response + +The results include the access token needed to make subsequent API requests on behalf of the application: + + { + "access_token": "F8zeMOlcEeCUBwBQVsAACA:YXA6AAABMq0d4Mep_UgbZA0-sOJRe5yWlkq7JrDCkA", + "expires_in": 3600, + "application": { + ... + } + } + +## Admin user authentication +If you do require admin user access, your app can connect to the Usergrid management endpoint to request an access token. Your app supplies the username and password of an admin user in the request. + +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+Warning: Authenticating as an admin user grants full access to one or more organizations and all of the applications contained in those organizations. Due to this, be cautious when implementing this type of authentication in client-side code. Instead, consider implementing admin user access in server-side code only. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html) for additional considerations in keeping access to your app and its data secure. +</p></div> + +### Request syntax + + curl -X POST "https://api.usergrid.com/management/token"; -d '{"grant_type":"password", "username":<admin_username>, "password":<admin_password>}' + +### Example Request + + curl -X POST "https://api.usergrid.com/management/token"; -d '{"grant_type":"password", "username":"testadmin", "password":"testadminpw"}' + +### Example response + +The results include the access token needed to make subsequent API requests on behalf of the admin user: + + { + "access_token": "f_GUbelXEeCfRgBQVsAACA:YWQ6AAABMqz_xUyYeErOkKjnzN7YQXXlpgmL69fvaA", + "expires_in": 3600, + "user": { + ... + } + } + +## Organization client authentication +If you do require organization level access, your app can connect to the Usergrid management endpoint to request an access token. Access to an organization requires the client id and client secret credentials. The client ID and secret for your organization can be found on the 'Org Administration' page of the API Services admin console under 'Organization API Credentials'. + +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+Warning: You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See "safe mobile access" in [Authenticating API requests](authenticating-api-requests.html for additional considerations in keeping access to your app and its data secure. +</p></div> + +### Request syntax + + curl -X POST "https://api.usergrid.com/management/token"; -d '{"grant_type":"client_credentials", "client_id":<org_clientID>, "client_secret":<org_client_secret>}' + +### Example request + + curl -X POST "https://api.usergrid.com/management/token"; -d '{"grant_type":"client_credentials", "client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ", "client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}' + +### Example response + +The results include the access token needed to make subsequent API requests to the organization: + + { + "access_token": "gAuFEOlXEeCfRgBQVsAACA:b3U6AAABMqz-Cn0wtDxxkxmQLgZvTMubcP20FulCZQ", + "expires_in": 3600, + "organization": { + ... + } + } + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/changing-token-time-live-ttl.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/changing-token-time-live-ttl.txt b/content/docs/_sources/security-and-auth/changing-token-time-live-ttl.txt new file mode 100644 index 0000000..2148d36 --- /dev/null +++ b/content/docs/_sources/security-and-auth/changing-token-time-live-ttl.txt @@ -0,0 +1,61 @@ +# Changing token expiration (time-to-live) + +An access token has a âtime-to-liveâ (ttl), which is the maximum time that the access token will be valid for use within the application. With the Usergrid, you can change the default ttl for all application user tokens, set the ttl for an individual token at the time of creation, or revoke one or more tokens. This gives you a high degree of control over access to your Usergrid account and data store. + +## Default ttl +By default, all tokens have a system-defined time-to-live of 7 days (604800 seconds). Note that Token ttl is specified in milliseconds, but when a token is created, the API response will return the ttl in seconds. + +## Changing the default ttl +You can change the default ttl for all application user tokens (that is, tokens associated with a user entity) by updating the application entityâs accesstokenttl property. Changing the default ttl will only affect new tokens. Any existing tokens will not be affected. + +Please note that this does not apply to application client, organization client or admin user tokens. For more on obtaining tokens for these other authorization levels, see [Authenticating users and application clients](authenticating-users-and-application-clients.html). + +__Note__: If you set ttl=0, the token will never expire. This can pose a security risk and should be used with caution. + +### Request syntax + + curl -X PUT https://api.usergrid.com/<org_name>/<app_name> -d '{"accesstokenttl":<ttl_in_milliseconds>}' + +### Example Request + + curl -X PUT https://api.usergrid.com/your-org/your-app -d '{"accesstokenttl":"1800000"}' + +### Example response + + { + "action" : "put", + "application" : "d878de4r-99a7-11e3-b31d-5373d7165c2d", + "params" : { + "access_token" : [ "DFR4d5M1mJmoEeOGVPncm-g9qgAAAURv_lfQ7uu6aYHjJJn7QCrGoVnvU-ob5Ko" ] + }, + "uri" : "https://api.usergrid.com/amuramoto/secured";, + "entities" : [ { + "uuid" : "d878de4r-99a7-11e3-b31d-5373d7165c2d", + "type" : "application", + "name" : "your-org/your-app", + "created" : 1392843003032, + "modified" : 1392843615777, + "accesstokenttl" : 1800000, + "organizationName" : "your-org", + "applicationName" : "your-app", + "apigeeMobileConfig" : "{...}", + "metadata" : { + "collections" : [ "activities", "assets", "devices", "events", "folders", "groups", "roles", "users" ] + } + } ], + "timestamp" : 1392843615767, + "duration" : 28, + "organization" : "your-org", + "applicationName" : "your-app" + } + +## Changing ttl when a token is created +When you request an access token, you can override its ttl by including a ttl property in the body of the request when the token is created. This applies to tokens for all authentication levels, including application user, admin user, organization client, and application client authentication levels. + +The ttl must be equal to or less than the value of the application entity's accesstokenttl property. If you specify a ttl value greater than the value of accesstokenttl, an error message is returned that indicates the maximum time to live value that can be specified. + +For example, the following would create an application user token with a ttl of 180000000 milliseconds: + + curl -X POST https://api.usergrid.com/your-org/your-app/token -d '{"username":"someUser", "password":"somePassword", "grant_type":"password", "ttl":"180000000"}' + +__Note__: If you set ttl=0, the token will never expire. This can pose a security risk and should be used with caution. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/facebook-sign.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/facebook-sign.txt b/content/docs/_sources/security-and-auth/facebook-sign.txt new file mode 100644 index 0000000..e2c7411 --- /dev/null +++ b/content/docs/_sources/security-and-auth/facebook-sign.txt @@ -0,0 +1,158 @@ +# Facebook sign in + +You can authenticate your Usergrid requests by logging into Facebook. To access Usergrid resources, you need to provide an access token with each request (unless you use the sandbox app). You can get an access token by connecting to an appropriate web service endpoint and providing the correct client credentials â this is further described in Authenticating users and application clients. However, you can also obtain an access token by logging into Facebook. + +To enable authentication to Usergrid through Facebook, do the following in your app: + +1. Make a login call to the Facebook API (do this using the Facebook SDK or API). If the login succeeds, a Facebook access token is returned. +2. Send the Facebook access token to Usergrid. If the Facebook access token is valid and the user does not already exist in Usergrid, Usergrid provisions a new Usergrid user. It also returns an Usergrid access token, which you can use for subsequent Usergrid API calls. Behind the scenes, Usergrid uses the Facebook access token to retrieve the user's profile information from Facebook. +3. If the Facebook access token is invalid, Facebook returns an OAuth authentication error, and the login does not succeed. + +The request to authenticate to Usergrid using a Facebook access token is: + + GET https://api.usergrid.com/{my_org}/{my_app}/auth/facebook?fb_access_token={fb_access_token} + +where: + +* ``{my_org}`` is the organization UUID or organization name. +* ``{my_app}`` is the application UUID or application name. +* ``{fb_access_token}`` is the Facebook access token. + +## Facebook login example +The Facebook technical guides for login present detailed information on how to add Facebook login to your app. Instructions are provided for JavaScript, iOS, and Android. + +In brief, here are the steps for JavaScript. You can see these steps implemented in the Facebook login example packaged with the JavaScript SDK for Usergrid (which you can download in ZIP format or tar.gz format). The Facebook login example is in the /examples/facebook directory of the extracted download. The code example snippets shown below are taken from the Facebook login example. + +### Step 1: Create a Facebook app +Create a new app on the Facebook App Dashboard. Enter your app's basic information. Once created, note the app ID shown at the top of the dashboard page. + +### Step 2: Invoke the Facebook OAuth dialog +Invoke the Facebook OAuth Dialog. To do that, redirect the user's browser to a URL by inserting the following Javascript code after the opening <body> tag in your appâs HTML file: + + https://www.facebook.com/dialog/oauth/? + client_id={YOUR_APP_ID} + &redirect_uri={YOUR_REDIRECT_URL} + &state={YOUR_STATE_VALUE} + &scope={COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES} + &response_type={YOUR_RESPONSE_TYPE} + +where: + +``{YOUR_APP_ID}`` is the app ID. +``{YOUR_REDIRECT_URL}`` is the application UUID or application name. +``{YOUR_STATE_VALUE}`` is a unique string used to maintain application state between the request and callback. +``{COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES}`` is a comma separated list of permission names which you would like the user to grant your application. +``{YOUR_RESPONSE_TYPE}``is the requested response type, either code or token. Defaults to code. Set the response type to token. With the response type set to token, the Dialog's response will include an OAuth user access token in the fragment of the URL the user is redirected to, as per the client-side authentication flow. + +Here is how itâs done in the Facebook login example: + + var apiKey = $("#api-key").val(); + var location = window.location.protocol + '//' + window.location.host; + var path = window.location.pathname; + + var link = "https://www.facebook.com/dialog/oauth?client_id=";; + link += apiKey; + link += "&redirect_uri="; + link += location+path + link += "&scope&COMMA_SEPARATED_LIST_OF_PERMISSION_NAMES&response_type=token"; + + //now forward the user to facebook + window.location = link; + +Notice that the response type is set to token. As a result, a Facebook access token will be appended to the URL to which the user is redirected. + +### Step 3: Add the JavaScript SDK for Facebook +Add the following Javascript SDK initialization code after the code that invokes the Facebook OAuth Dialog. The code will load and initialize the JavaScript SDK in your HTML page. Replace ``YOUR_APP_ID`` with the App ID noted in Step 1, and WWW.YOUR_DOMAIN.COM with your own domain. + + window.fbAsyncInit = function() { + FB.init({ + appId : 'YOUR_APP_ID', // App ID + channelUrl : '//WWW.YOUR_DOMAIN.COM/channel.html', // Channel File + status : true, // check login status + cookie : true, // enable cookies to allow the server to access the session + xfbml : true // parse XFBML + }); + +Here is how the window.fbAsynchInit() function is implemented in the Facebook login example: + + //load up the facebook api sdk + window.fbAsyncInit = function() { + FB.init({ + appId : '308790195893570', // App ID + channelUrl : '//usergridsdk.dev//examples/channel.html', // Channel File + status : true, // check login status + cookie : true, // enable cookies to allow the server to access the session + xfbml : true // parse XFBML + }); + }; + +### Step 4. Setup FB.login +Whenever a user is either not logged into Facebook or not authorized for an app, it is useful to prompt them with the relevant dialog. The ``FB.login()`` Javascript SDK function automatically displays the correct one to the user. + +To integrate ``FB.login()`` function in your existing code: + + function login() { + FB.login(function(response) { + if (response.authResponse) { + // connected + } else { + // cancelled + } + }); + } + +Here is how ``FB.login()`` is implemented in the Facebook login example: + + function login(facebookAccessToken) { + client.loginFacebook(facebookAccessToken, function(err, response){ + var output = JSON.stringify(response, null, 2); + if (err) { + var html = '<pre>Oops! There was an error logging you in. \r\n\r\n'; + html += 'Error: \r\n' + output+'</pre>'; + } else { + var html = '<pre>Hurray! You have been logged in. \r\n\r\n'; + html += 'Facebook Token: ' + '\r\n' + facebookAccessToken + '\r\n\r\n'; + html += 'Facebook Profile data stored in Usergrid: \r\n' + output+'</pre>'; + } + $('#facebook-status').html(html); + }) + } + +The ``client.loginFacebook()`` function is provided by the Usergrid JavaScript SDK. It uses the Facebook auth token to obtain an Usergrid auth token. If the Facebook access token is valid and the user does not already exist in Usergrid, the function creates a user entity for the user. It also uses the Facebook access token to retrieve the user's profile information from Facebook. + +Here is what the ``client.loginFacebook()`` function looks like: + + Usergrid.Client.prototype.loginFacebook = function (facebookToken, callback) { + var self = this; + var options = { + method:'GET', + endpoint:'auth/facebook', + qs:{ + fb_access_token: facebookToken + } + }; + this.request(options, function(err, data) { + var user = {}; + if (err && self.logging) { + console.log('error trying to log user in'); + } else { + user = new Usergrid.Entity('users', data.user); + self.setToken(data.access_token); + } + if (typeof(callback) === 'function') { + callback(err, data, user); + } + }); + } + +Notice that the function also returns an Usergrid access token, which you can use for subsequent Usergrid API calls. + +Remember to create a client for your app, which is the main entry point to the JavaScript SDK for Usergrid. You need to do this before you can use the SDK. Hereâs the code to create a client: + + var client = new Usergrid.Client({ + orgName:'yourorgname', + appName:'yourappname', + logging: true, //optional - turn on logging, off by default + buildCurl: true //optional - turn on curl commands, off by default + }); + http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/revoking-tokens-logout.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/revoking-tokens-logout.txt b/content/docs/_sources/security-and-auth/revoking-tokens-logout.txt new file mode 100644 index 0000000..386f04f --- /dev/null +++ b/content/docs/_sources/security-and-auth/revoking-tokens-logout.txt @@ -0,0 +1,32 @@ +# Revoking tokens (logout) + +Under certain circumstances, you may need to explicitly revoke one or more tokens associated with a user entity, such as when a user logs out of your app. This is accomplished by making a PUT request to the /revoketoken and /revoketokens endpoints. + +## Revoking tokens (user logout) +If a user has been logged in using the Usergrid iOS, Android, JavaScript or node.JS SDKs, the returned token is automatically stored in the UsergridDataClient (iOS), DataClient (Android), Usergrid.Client (JavaScript), Usergrid.Client (node.JS) class instance. Calling the logout method of the SDK will destroy the token on the server, as well as in the client object. + +### Request syntax + +Revoke all tokens associated with a user entity + + curl -X PUT https://api.usergrid.com/<org_name>/<app_name>/users/<user_uuid_or_username>/revoketokens + +Revoke a specific token associated with a user entity + + curl -X PUT https://api.usergrid.com/<org_name>/<app_name>/users/<user_uuid_or_username>/revoketoken?token=<token_to_revoke> + +### Example request + + curl -X PUT https://api.usergrid.com/your-org/your-app/users/someUser/revoketokens + +Example response + + { + "action" : "revoked user token", + "timestamp" : 1382050891455, + "duration" : 24 + } + +### Revoking admin user tokens + +The /revoketoken and /revoketokens endpoints also work for revoking admin user tokens by making a PUT request to /management/users/<org_admin_username>/ http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/securing-your-app.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/securing-your-app.txt b/content/docs/_sources/security-and-auth/securing-your-app.txt new file mode 100644 index 0000000..6eb043f --- /dev/null +++ b/content/docs/_sources/security-and-auth/securing-your-app.txt @@ -0,0 +1,44 @@ +# Security best practices + +There a number of actions you should take to ensure that your app is secure before you put it into production. The following is not an exhaustive list, but offers some common best practices you should consider following to keep your app secure when using the Usergrid. + +## Never use the 'sandbox' for a production app +By default, every new Usergrid account has an app named âsandboxâ that is already created under your new organization. This app is no different than any other app that you might create, except that the Guest role has been given full permissions (that is, /** for GET, POST, PUT, and DELETE). This eliminates the need for a token when making application level calls, and can make it much easier to get your app up and running; however, it also means that any data in the sandbox application is completely unsecured. + +As with any other app, you can secure the sandbox application by updating its roles and permissions. For more on working with permissions and roles, see [Using Permissions](using-permissions.html). + +## Review permissions in your apps +Prior to launching your app into a production environment, it is advisable to review all the roles and permissions you have set up, as well as the groups and users you have assigned those permissions and roles to. During development, you may find that you added various permissions which may or may not still be required once the app is complete. Review all permissions and delete any that are no longer required. + +Prior to taking your app live, you should secure it by removing any unnecesary Guest permissions. (See [Using Permissions](using-permissions.html) for further information about setting permissions.) After you secure your the app, any calls to the API will need to include an OAuth token. Oauth tokens (also called access tokens) are obtained by the API in response to successful authentication calls. Your app saves the token and uses it for all future calls during that session. Learn more about access tokens in Authenticating users and application clients. + +## Edit the 'default' role +When preparing an application for production use, a good first step is to edit permission rules for the Default role. The permissions in this role will be applied to every user who authenticates with a valid access token. + +For example, in the Default role, you will most likely first want to remove the permission rule that grants full access to all authenticated users: + + GET,PUT,POST,DELETE:/users/me/** + +For more on roles, see [Using Permissions](using-permissions.html). + +Review test accounts +If you created any test user or test administrator accounts during development, these should also be reviewed for relevancy and security. Delete any test accounts that are no longer needed. If these accounts are still needed, make sure that passwords have been secured to the standards required by your app. + +## Use https +Make sure that any calls you make to the API are done using the secure https protocol, and not the insecure http protocol. + +If your app is a web app, that is, an app served by a web server, make sure that the app is served using https. + +## Acquire access tokens in a secure way +There are various methods for acquiring an access token (see [Authenticating users and application clients](authenticating-users-and-application-clients.html). One method is to use the application or organization level client secret-client id combination. This method should not be used in client applications (this is, apps that are deployed to a device, and which authenticate and make calls against the API). + +Thatâs because a hacker could analyze your app (even a compiled, binary distribution of your app), and retrieve the secret-id combination. Armed with this information, an attacker could gain full access to the data in your account. + +Instead, use application user credentials. This means that your appâs users should provide a username and password. Your app would use these to authenticate against the API and retrieve an access token. + +The client secret-client id combination should be used only in secure, server-side applications where there is no possibility of a hacker gaining control of the credentials. + +## Treat mobile clients as untrustworthy +For mobile access, it is recommended that you connect as an application user with configured access control policies. Mobile applications are inherently untrusted because they can be easily examined and even decompiled. + +Any credentials stored in a mobile app should be considered secure only to the Application User level. This means that if you donât want the user to be able to access or delete data in your Usergrid application, you need to make sure that you donât enable that capability through roles or permissions. Because most web applications talk to the database using some elevated level of permissions, such as root, itâs generally a good idea for mobile applications to connect with a more restricted set of permissions. For more information on restricting access through permission rules, see [Using Permissions](using-permissions.html). http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/user-authentication-types.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/user-authentication-types.txt b/content/docs/_sources/security-and-auth/user-authentication-types.txt new file mode 100644 index 0000000..1a14f50 --- /dev/null +++ b/content/docs/_sources/security-and-auth/user-authentication-types.txt @@ -0,0 +1,63 @@ +# Authentication levels + +Usergrid supports four levels of authentication, but only one of them is used when checking a registered user's permissions. The other three levels are useful for authenticating other application or web clients that require higher-level access to your Usergrid application or organization. Because the scope of access that the other authentication levels provide is so broad (and as a result, so powerful), it's a bad practice to use them from a mobile app. Instead, they're better suited to other client apps, such as web applications. + +## Configuring authentication levels +Access permissions can only be configured for the 'application user' â this can be done both programmatically and in the admin portal. The application, organization and admin clients cannot be configured, and can only be accessed programmatically via the API. + +For more about creating and managing roles and permissions for application users, see Managing access by defining permission rules. For a look at how security features fit together, see App Security Overview. + +## User authentication level + +<table class="usergrid-table"> +<tr> + <th>Authentication Level</th> + <th>Description</th> +</tr> +<tr> + <td>Application user</td> + <td>This is the standard authentication type you will use to implement user login for your app. The application user level allows access to your Usergrid application as governed by the permission rules you create and associated with users and user groups. For more on setting permissions see Managing access by defining permission rules. Each Application User is represented by a User entity in your Usergrid application. For more about the User entity, see User.</td> +</tr> +</table> + +## Admin authentication levels + +<div class="admonition warning"> <p class="first admonition-title">WARNING</p> <p class="last">⨠+Warning: Safe use of admin authentication levels. Never use client ID and client secret, or any hard-coded credentials to authenticate this way from a client-side app, such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. Even when authenticating with username and password, be cautious when using these authentication levels since they grant broad access to your Usergrid account. See "safe mobile access" in Authenticating API requests for additional considerations in keeping access to your app and its data secure.</p></div> + +<table class="usergrid-table"> +<tr> + <th>Authentication Level</th> + <th>Description</th> +</tr> +<tr> + <td>Application client</td> + <td>Grants full access to perform any operation on an Usergrid application (but not other applications within the same organization). + + <p>Authentication at this level is useful in a server-side application (not a mobile app) that needs access to resources through the Usergrid API. For example, imagine you created a website that lists every hiking trail in the Rocky Mountains. You would want anyone to be able to view the content, but would not want them to access the Usergrid API and all your data directly. Instead, you would authenticate as an application client in your server-side code to access the data via the API in order to serve it to your website's visitors.</p></td> +</tr> +<tr> + <td>Organization client</td> + <td>Grants full access to perform any operation on an Usergrid organization. + + <p>This authentication level provides the greatest amount of access to an individual organization, allowing a client to perform any operation on an Usergrid organization and any applications in that organization. This level of access should be used sparingly and carefully.</p></td> +</tr> +<tr> + <td>Admin user</td> + <td>Allows full access to perform any operation on all organization accounts of which the admin user is a member. + + <p>This authentication level is useful from applications that provide organization-wide administration features. For example, the Usergrid admin portal uses this level of access because it requires full access to the administration features.</p> + + Unless you have a specific need for administrative features, such as to run test scripts that require access to management functionality, you should not use the admin user authentication level.</td> +</tr> +</table> + + + + + + + + + + http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/security-and-auth/using-permissions.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/security-and-auth/using-permissions.txt b/content/docs/_sources/security-and-auth/using-permissions.txt new file mode 100644 index 0000000..34ec664 --- /dev/null +++ b/content/docs/_sources/security-and-auth/using-permissions.txt @@ -0,0 +1,115 @@ +# Using permissions + +Permissions allow you to define user access to perform GET, POST, PUT, or DELETE operations on specific resources. When the user submits a request via your app code to the Usergrid API, the userâs permissions are checked against the resource paths that the user is trying to access. The request succeeds only if access to the resource is allowed by the permission rules you specify. + +## Permissions syntax +In Usergrid, permissions are represented in the following format: + + <operations>:<resource_path> + +* ``<operations>``: A comma-delimited set of HTTP methods (``GET``, ``PUT``, ``POST``, ``DELETE``) that are allowed for the specified resource path. For example, ``get``, ``post`` would allow only ``GET`` and ``POST`` requests to be made to the specified resource. +* ``<resource_path>``: The path to the resources to be accessed. For example, ``/users`` would apply the permission to the users collection, while ``/users/Tom`` would apply the permission to only the user entity with username 'Tom'. + +## Complex paths +Complex paths can be defined using [Apache Ant pattern syntax](http://ant.apache.org/manual/dirtasks.html#patterns). The following special path variables are supported for the construction of complex paths: + +<table> +<tr> + <td>Parameter</td> + <td>Description</td> +</tr> +<tr> + <td>*</td> + <td>Treated as a wildcard. Assigns the permission to all paths at the specified level in the path hierarchy. For example, ``/*`` would match any collection, while ``/users/Tom/*`` would match /users/Tom/likes and ``/users/Tom/owns``.</td> +</tr> +<tr> + <td>**</td> + <td>Assigns the permission to the path recursively. For example, ``**/likes`` would match ``/likes`` and ``/users/likes``, while ``/users/**`` would match ``/users`` and ``/users/likes``.</td> +</tr> +<tr> + <td>\${user}</td> + <td>Automatically sets the path segment to the UUID of the currently authenticated user. For example, if you sent a request with a valid access token for a user with UUID ``bd397ea1-a71c-3249-8a4c-62fd53c78ce7``, the path ``/users/${user}`` would be interpreted as ``/users/bd397ea1-a71c-3249-8a4c-62fd53c78ce7``, assigning the permission only to that user entity.</td> +</tr> +</table> + +## Assigning permissions +Permissions can only be assigned to user, group or role entities. Assigning permissions to roles can be particularly useful, as it allows you to create sets of permissions that represent complex access definitions, which can then be assigned to user and group entities. For more on roles, see Using roles. + +### Request syntax + + curl -X POST https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions -d '{"permission":<permissions>}' + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +collection The collection of the entity that the permissions are to be assigned to. +entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted. +permissions The permissions to assign to the entity. See Permissions syntax for format. + +For collections, Valid values are users and groups. + +### Example request +For example, the following cURL request would give the user 'Tom' POST permission to the /users collection: + + curl -X POST https://api.usergrid.com/your-org/your-app/users/Tom/permissions -d '{"permission":"post:/users"}' + +### Example response +The newly assigned permission is returned in the data property of the response: + + { + "action" : "post", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "uri" : "https://api.usergrid.com/your-org/your-app";, + "entities" : [ ], + "data" : [ "post:/users" ], + "timestamp" : 1402349612382, + "duration" : 19, + "organization" : "your-org", + "applicationName" : "your-app" + } + + +## Removing permissions +Using a DELETE request, you can remove one of more permissions from a user, group, or role entity. + +### Request syntax + + curl -X DELETE https://api.usergrid.com/<org>/<app>/<collection>/<entity>/permissions?=<permissions> + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +collection The collection of the entity that the permissions are to be assigned to. Valid values are users and groups. +entity The UUID of the entity to assign the permissions to. For users, username and for groups, name are also accepted. +permissions The permissions to assign to the entity. See [Permissions syntax](using-permissions.html) for format. + + +### Example request + + curl -X DELETE https://api.usergrid.com/your-org/your-app/users/Tom/permissions?permission=post:/users + +### Example response +The deleted permission is returned in the params.permission property of the response: + + { + "action" : "delete", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { + "permission" : [ "post:/users" ] + }, + "uri" : "https://api.usergrid.com/your-org/your-app";, + "entities" : [ ], + "data" : [ "post:/assets" ], + "timestamp" : 1402349951530, + "duration" : 20, + "organization" : "your-org", + "applicationName" : "your-app" + } + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/user-management/activity.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/activity.txt b/content/docs/_sources/user-management/activity.txt new file mode 100644 index 0000000..2703ab8 --- /dev/null +++ b/content/docs/_sources/user-management/activity.txt @@ -0,0 +1,440 @@ +# Activity + +Most modern applications struggle to manage data streams, such as those +that contain an ongoing list of comments, activities, and tweets. In +particular, mobile applications are prone to generating very large +amounts of data in a data stream. Beyond that, additions to a data +stream must often be routed automatically to subscribers or filtered or +counted. + +Usergrid provides an activity entity that is specifically designed +for data streams. An activity is an entity type that represents activity +stream actions (see the [JSON Activity Streams 1.0 +specification](http://activitystrea.ms/specs/json/1.0/) for more +information about these actions). + +When a user creates an activity, it creates a relationship between the +activity and the user who created it. Because this relationship exists, +the activity will appear in the feed of any of the userâs followers. +Think of the Activities endpoint (/users/{uuid|username}/activities) as +an "outbox" of news items created by the user. Think of the Feed +endpoint (/users/{uuid|username}/feed) as an "inbox" of news items meant +to be seen or consumed by the user. + +A user can also post an activity to a group (located at +/groups/{uuid|groupname}/activities). This allows you to emulate +Facebook-style group functionality, where a limited number of users can +share content on a common "wall". In any of these cases, there is no +need to construct publish/subscribe relationships manually. + +Activity entities are particularly useful in applications that enable +users to post content to activity streams (also called feeds) and to +display activity streams. Some examples of these applications are +Twitter, foursquare, and Pinterest. For example, when a Twitter user +posts a short, 140-character or less, "tweet", that activity gets added +to the user's activity stream for display as well as to the activity +streams of any of the user's followers. + +Using Usergrid APIs you can create, retrieve, update, and delete +activity entities. See You do not have access to view this node for +descriptions of these APIs. + +**Note:** Although not shown in the API examples below, you need to +provide a valid access token with each API call. See +[Authenticating users and application clients](../security-and-auth/authenticating-users-and-application-clients.html) for details. + + +## Posting activities + +Posting a user activity + +Use the POST method to create an activity in the activities collection. + +### Request URI + + POST /<org_id>/<app_id>/users/<uuid | username>/activities { request body } + +Parameters + +Parameter Description +--------- ----------- +arg uuid|string org_id Organization UUID or organization name +arg uuid|string app_id Application UUID or application name +request body One or more sets of activity properties + +Here's an example request body: + + { + "actor":{ + "displayName":"John Doe", + "uuid":"1f3567aa-da83-11e1-afad-12313b01d5c1", + "username":"john.doe", + "image":{ + "duration":0, + "height":80, + "url":"http://www.gravatar.com/avatar/","width":80}, + "email":"john....@gmail.com" + }, + "verb":"post", + "content":"Hello World!" + } + } + +### Example - Request + + curl -X POST "https://api.usergrid.com/my-org/my-app/users/john.doe/activities"; -d '{"actor":{"displayName":"John Doe","uuid":"1f3567aa-da83-11e1-afad-12313b01d5c1","username":"john.doe", "image":{"duration":0,"height":80,"url":"http://www.gravatar.com/avatar/","width":80}, "email":"john....@gmail.com"},"verb":"post","content":"Hello World!"}' + +### Example - Response + + { + "action" : "post", + "application" : "5111c463-6a42-11e1-b6dd-1231380a0284", + "params" : { + }, + "path" : "/users/1f3567aa-da83-11e1-afad-12313b01d5c1/activities", + "uri" : "https://api.usergrid.com/5111c463-6a42-11e1-b6dd-1231380a0284/users/1f3567aa-da83-11e1-afad-12313b01d5c1/activities";, + "entities" : [ { + "uuid" : "da448955-f3aa-11e1-8042-12313d331ae8", + "type" : "activity", + "created" : 1346445092974, + "modified" : 1346445092974, + "actor" : { + "displayName" : "John Doe", + "uuid" : "1f3567aa-da83-11e1-afad-12313b01d5c1", + "username" : "john.doe", + "image" : { + "duration" : 0, + "height" : 80, + "url" : "http://www.gravatar.com/avatar/";, + "width" : 80 + }, + "email" : "john....@gmail.com" + }, + "content" : "Hello World!", + "metadata" : { + "path" : "/users/1f3567aa-da83-11e1-afad-12313b01d5c1/activities/da448955-f3aa-11e1-8042-12313d331ae8" + }, + "published" : 1346445092974, + "verb" : "post" + } ], + "timestamp" : 1346445092827, + "duration" : 1406, + "organization": "my-org", + "applicationName": "my-app" + } + +__Note__: Anytime a logged-in user makes a request, you can substitute "me" for the uuid or username. So the format of a request to create an activity for the currently logged-in user would look like this: + + POST /<org_id>/<app_id>/users/me/activities { request body } + +The ``/users/me`` endpoint is accessible only if you provide an access token with the request. If you don't provide an access token with the request, that is, you make an anonymous (or "guest") call, the system will not be able to determine which user to return as ``/users/me``. + +When you create an activity it creates a relationship between the activity and the user who created it. In other words, the newly created activity above belongs to john.doe. Another way of saying this is the user "owns" the activity. And because this relationship exists, the activity will appear in the feed of any of the userâs followers (in this example, anyone who is following john.doe). However, it will not appear in the feed of people the user follows. The activity is accessible at the ``/activities`` endpoint to users who have the permission to read that endpoint. + +Notice the properties specified in the request body in the previous example are actor, verb, and content. The actor, verb, and content properties are built into the Activity entity (see Default Data Entity Types). The actor property specifies properties of the entity that performs the action (here, user john.doe). The gravatar URL is used to create an icon for the activity. And because an Activity is simply an API Services data entity, you can also create custom properties. + +The verb parameter is descriptive. You can use it to indicate what type of activity is posted, for example, an image versus text. The value post is defined in the JSON Activity Streams specification as âthe act of authoring an object and then publishing it online.â + +## Posting an activity to a group + +Use the POST method to post an activity to a specific group. In this case the activity is created in the activities collection and is accessible at the /activities endpoint to users who have the permission to read that endpoint. In addition, a relationship is established between the activity and the group, and because of that, the activity will appear in the groupâs feed. The group "owns" the activity. Also, the activity will be published in the feed of all users that are members of the group. + +### Request URI + + POST /{org_id}/{app_id}/groups/{uuid|groupname}/activities {request body} + +Parameters + +Parameter Description +--------- ----------- +arg uuid|string org_id Organization UUID or organization name +arg uuid|string app_id Application UUID or application name +arg uuid|string groupname UUID or name of the group +request body One or more sets of activity properties. + +Here's a sample request body: + + { + "actor": + { + "displayName":"John Doe", + "uuid":"1f3567aa-da83-11e1-afad-12313b01d5c1", + "username":"john.doe", + "image":{ + "duration":0, + "height":80, + "url":"http://www.gravatar.com/avatar/","width":80}, + "email":"john....@gmail.com"}, + "verb":"post", + "content":"Hello World!" + } + +### Example - Request + + curl -X POST "https://api.usergrid.com/my-org/my-app/groups/mygroup/activities"; -d '{"actor":{"displayName":"John Doe","uuid":"1f3567aa-da83-11e1-afad-12313b01d5c1","username":"john.doe", "image":{"duration":0,"height":80,"url":"http://www.gravatar.com/avatar/","width":80}, "email":"john....@gmail.com"},"verb":"post","content":"Hello World!"}' + +Because this relationship exists, this activity will appear in the feed of all users who are members of mygroup. It won't appear in the feeds of the group membersâ followers or in feeds of users they follow. + +### Example - Response + + { + "action": "post", + "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491", + "params": {}, + "path": "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/activities", + "uri": "https://api.usergrid.com/my-org/my-app/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/activities";, + "entities": [ + { + "uuid": "563f5d96-37f3-11e2-a0f7-02e81ae640dc", + "type": "activity", + "created": 1353952903811, + "modified": 1353952903811, + "actor": { + "displayName": "John Doe", + "uuid": "1f3567aa-da83-11e1-afad-12313b01d5c1", + "username": "john.doe", + "image": { + "duration": 0, + "height": 80, + "url": "http://www.gravatar.com/avatar/";, + "width": 80 + }, + "email": "john....@gmail.com" + }, + "content": "Hello World!", + "metadata": { + "path": "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/activities/563f5d96-37f3-11e2-a0f7-02e81ae640dc" + }, + "published": 1353952903811, + "verb": "post" + } + ], + "timestamp": 1353952903800, + "duration": 81, + "organization": "my-org", + "applicationName": "my-app" + } + +## Creating an activity for a user's followers in a group + +Use the POST method to create an activity that will be published only in the feeds of users who (1) follow you, and (2) are in the same group to which you posted the activity. This is useful if you want to create specific groups of friends (for example, acquaintances or colleagues) and publish content to them with more precise privacy settings. This allows you to re-create a privacy model similar to Google+âs Circles or Facebook current privacy system. + +When you create an activity for a userâs followers in a group: + +The activity is accessible at the ``/activities`` endpoint to users who have the permission to read that endpoint. The activity will not be cross-posted to the groupâs activity endpoint (``/groups/{uuid|groupname}/activities``) +A relationship is automatically created between the activity entity that was just created and the user within that group (``/groups/{uuid|groupname}/users/{uuid|username}``) +The user within the group (``/groups/{uuid|groupname}/users/{uuid|username}```) becomes the owner of the activity (through the owner property in the activity). + +### Request URI + + POST /{org_id}/{app_id}/groups/{uuid|groupname}/users/{uuid|username}/activities {request body} + +Parameters + +Parameter Description +arg uuid|string org_id Organization UUID or organization name +arg uuid|string app_id Application UUID or application name +arg uuid|string groupname UUID or name of the group +arg uuid|string username UUID or name of the user +request body One or more sets of activity properties + +Example request body: + + { + "actor": + { + "displayName":"John Doe", + "uuid":"1f3567aa-da83-11e1-afad-12313b01d5c1", + "username":"john.doe", + "image":{ + "duration":0, + "height":80, + "url":"http://www.gravatar.com/avatar/","width":80}, + "email":"john....@gmail.com"}, + "verb":"post", + "content":"Hello World!" + } + +### Example - Request + + curl -X POST "https://api.usergrid.com/my-org/my-app/groups/mygroup/users/john.doe/activities"; -d '{"actor":{"displayName":"John Doe","uuid":"1f3567aa-da83-11e1-afad-12313b01d5c1","username":"john.doe", "image":{"duration":0,"height":80,"url":"http://www.gravatar.com/avatar/","width":80}, "email":"john....@gmail.com"},"verb":"post","content":"Hello World!"}' + +Because this relationship exists, this activity will appear in the feed of all users who are members of mygroup. It won't appear in the feeds of the group membersâ followers or in feeds of users they follow. + +### Example - Response + + { + "action" : "post", + "application" : "3400ba10-cd0c-11e1-bcf7-12313d1c4491", + "params" : { }, + "path" : "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/activities", + "uri" : "https://api.usergrid.com/my-org/my-app/ + /groups/d87edec7-fc4d-11e1-9917-12313d1520f1/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/activities", + "entities" : [ { + "uuid" : "2440ca58-49ff-11e2-84c0-02e81adcf3d0", + "type" : "activity", + "created" : 1355937094825, + "modified" : 1355937094825, + "actor" : { + "displayName" : "John Doe", + "uuid" : "1f3567aa-da83-11e1-afad-12313b01d5c1", + "username" : "john.doe", + "image" : { + "duration" : 0, + "height" : 80, + "url" : "http://www.gravatar.com/avatar/";, + "width" : 80 + }, + "email" : "john....@gmail.com" + }, + "content" : "Happy New Year!", + "metadata" : { + "path" : "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/users/34e26bc9-2d00-11e2-a065-02e81ae640dc/activities/2440ca58-49ff-11e2-84c0-02e81adcf3d0" + }, + "published" : 1355937094825, + "verb" : "post" + } ], + "timestamp" : 1355937094789, + "duration" : 95, + "organization" : "my-org", + "applicationName" : "my-app" + } + +## Retrieving activity feeds + +Retrieving a user's activity feed + +Use the GET method to retrieve a userâs feed. + +### Request URI + + GET /{org_id}/{app_id}/users/{uuid|username}/feed + +### Example - Request + + curl -X GET "https://api.usergrid.com/my-org/my-app/users/john.doe/feed"; + +### Example - Response + + { + "action" : "get", + "application" : "3400ba10-cd0c-11e1-bcf7-12313d1c44914", + "params" : {}, + "path" : "/users/d9693ec3-61c9-11e2-9ffc-02e81adcf3d0/feed", + "uri" : "https://api.usergrid.com/3400ba10-cd0c-11e1-bcf7-12313d1c44914/users/d9693ec3-61c9-11e2-9ffc-02e81adcf3d0/feed";, + "entities" : [ { + "uuid" : "ffd79647-f399-11e1-aec3-12313b06ae01", + "type" : "activity", + "created" : 1346437854569, + "modified" : 1346437854569, + "actor" : { + "displayName" : "John Doe", + "image" : { + "duration" : 0, + "height" : 80, + "url" : "http://www.gravatar.com/avatar/";, + "width" : 80 + }, + "uuid" : "d9693ec3-61c9-11e2-9ffc-02e81adcf3d0", + "email" : "john....@gmail.com", + "username" : "john.doe" + }, + "content" : "Hello World!", + "metadata" : { + "cursor" : "gGkAAQMAgGkABgE5ffM1aQCAdQAQ_9eWR_OZEeGuwxIxOwauAQCAdQAQABlaOvOaEeGuwxIxOwauAQA", + "path" : "/users/d9693ec3-61c9-11e2-9ffc-02e81adcf3d0/feed/ffd79647-f399-11e1-aec3-12313b06ae01" + }, + "published" : 1346437854569, + "verb" : "post" + }, { + "uuid" : "2482a1c5-e7d0-11e1-96f6-12313b06d112", + "type" : "activity", + "created" : 1345141694958, + "modified" : 1345141694958, + "actor" : { + "displayName" : "moab", + "image" : { + "duration" : 0, + "height" : 80, + "url" : "http://www.gravatar.com/avatar/";, + "width" : 80 + }, + "uuid" : "d9693ec3-61c9-11e2-9ffc-02e81adcf3d0", + "email" : "masso...@mfdsadfdsaoabl.com", + "username" : "moab" + }, + "content" : "checking in code left and right!!", + "metadata" : { + "cursor" : "gGkAAQMAgGkABgE5MLFh7gCAdQAQJIKhxefQEeGW9hIxOwbREgCAdQAQJNEP6ufQEeGW9hIxOwbREgA", + "path" : "/users/d9693ec3-61c9-11e2-9ffc-02e81adcf3d0/feed/2482a1c5-e7d0-11e1-96f6-12313b06d112" + }, + "published" : 1345141694958, + "verb" : "post" + } ], + "timestamp" : 1346438331316, + "duration" : 144, + "organization": "my-org", + "applicationName": "my-app" + } + +## Retrieving a group's activity feed + +Use the GET method to retrieve the feed for a group. This gets a list of all the activities that have been posted to this group, that is, the activities for which this group has a relationship (owns). + +### Request URI + + GET /{org_id}/{app_id}/groups/{uuid|groupname}/feed + +Parameters + +Parameter Description +--------- ----------- +arg uuid|string org_id Organization UUID or organization name +arg uuid|string app_id Application UUID or application name +arg uuid|string groupname UUID or name of the group + +### Example - Request + + curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mygroup/feed"; + +### Example - Response + + { + "action": "get", + "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491", + "params": {}, + "path": "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/feed", + "uri": "https://api.usergrid.com/my-org/my-app/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/feed";, + "entities": [ + { + "uuid": "563f5d96-37f3-11e2-a0f7-02e81ae640dc", + "type": "activity", + "created": 1353952903811, + "modified": 1353952903811, + "actor": { + "displayName": "John Doe", + "image": { + "duration": 0, + "height": 80, + "url": "http://www.gravatar.com/avatar/";, + "width": 80 + }, + "uuid": "1f3567aa-da83-11e1-afad-12313b01d5c1", + "email": "john....@gmail.com", + "username": "john.doe" + }, + "content": "Hello World!", + "metadata": { + "cursor": "gGkAAQMAgGkABgE7PeHCgwCAdQAQVj9dljfzEeKg9wLoGuZA3ACAdQAQVkVRCTfzEeKg9wLoGuZA3AA", + "path": "/groups/d87edec7-fc4d-11e1-9917-12313d1520f1/feed/563f5d96-37f3-11e2-a0f7-02e81ae640dc" + }, + "published": 1353952903811, + "verb": "post" + } + ], + "timestamp": 1353953272756, + "duration": 29, + "organization": "my-org", + "applicationName": "my-app" + } + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/user-management/group.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/group.txt b/content/docs/_sources/user-management/group.txt new file mode 100644 index 0000000..4f76cb6 --- /dev/null +++ b/content/docs/_sources/user-management/group.txt @@ -0,0 +1,365 @@ +# Working with group data + +You can organize app users into groups. Groups have their own Activity Feed, their own permissions and be a useful alternative to Roles, depending on how you model your data. Groups were originally designed to emulate Facebook Groups, so they will tend to function about the same way Facebook Groups would. + +Groups are hierarchical. Every member of the group ``/groups/california/san-francisco`` is also a member of the group ``/groups/california``. + +Groups are also a great way to model things such a topic subscriptions. For example, you could allow people to subscribe (i.e. become a member of the group and be alerted via Activities) to ``/groups/memes/dogs/doge`` or subscribe to all ``/groups/memes/dogs``. + +See the [Group Model section of the API Reference](../rest-endpoints/api-docs.html#group) for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application. + +## Creating groups + +A group entity represents an application group of users. You can create, retrieve, update, delete, and query group entities. See User entity properties for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application. + +### Request Syntax + + curl -X POST "https://api.usergrid.com/your-org/your-app/groups"; '{ request body }' + +Use the POST method to create a new group. Groups use paths to indicate their unique names. This allows you to create group hierarchies by using slashes. For this reason, you need to specify a path property for a new group. + +### Request URI + + POST /{org_id}/{app_id}/groups + +Parameters + +Parameter Description +--------- ----------- +uuid | org_id Organization UUID or organization name +uuid | app_id Application UUID or application name +request body One or more sets of group properties of which path is mandatory. + +The ``path`` property is required and must be unique, it may include forward slashes to denote hierarchical relationships. + + { + "path" : "somegroup/somesubgroup", + "title" : "Some SubGroup" + } + +### Example + +__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details. + +### Request + + curl -X POST "https://api.usergrid.com/my-org/my-app/groups"; -d '{"path":"mynewgroup"}' + +### Response + + { + "action": "post", + "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22", + "params": {}, + "path": "/groups", + "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups";, + "entities": [{ + "uuid": "a668717b-67cb-11e1-8223-12313d14bde7", + "type": "group", + "created": 1331066016571, + "modified": 1331066016571, + "metadata": { + "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7", + "sets": { + "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/rolenames", + "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/permissions" + }, + "collections": { + "activities": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/activities", + "feed": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/feed", + "roles": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/roles", + "users": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users" + } + }, + "path": "mynewgroup" + }], + "timestamp": 1331066016563, + "duration": 35, + "organization": "my-org", + "applicationName": "my-app" + } + +## Retrieving groups + +Retrieving group data + +You can retrieve data about groups through cURL or one of the SDKs. Each provides a way to filter the list of groups by data associated with the group, such as title or path, or other properties in the group entity. + +See the [Group Model section of the API Reference](../rest-endpoints/api-docs.html#group) for a list of the system-defined properties for group entities. In addition, you can create group properties specific to your application. + +### Request Syntax + + curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mynewgroup"; + +Use the GET method to retrieve group data. + +### Request URI + + GET /<org_id | uuid>/<app_id | uuid>/groups</groupPath | uuid> | <?ql=query_string> + +Parameters + +Parameter Description +--------- +org_id | uuid Organization UUID or organization name +app_id | uuid Application UUID or application name +groupPath | uuid Group UUID or group path, which must be unique. +query_string A data store query. For more on queries, see Data queries. + +### Request + + # Get a group by the group path, "employees/managers". + curl -X GET "https://api.usergrid.com/my-org/my-app/groups/employees/managers"; + + # Get a group by UUID. + curl -X GET "https://api.usergrid.com/my-org/my-app/groups/a407b1e7-58e8-11e1-ac46-22000a1c5a67e"; + + # Get group data filtering by their title. + curl -X GET "https://api.usergrid.com/my-org/my-app/groups?ql=select%20*%20where%20title%3D'Management%20Employees'" + +### Response + +The following is an example of JSON returned by a query for a single group. + + { + "action" : "get", + "application" : "db1e60a0-417f-11e3-9586-0f1ff3650d20", + "params" : { }, + "path" : "/groups", + "uri" : "https://api.usergrid.com/steventraut/mynewapp/groups";, + "entities" : [ { + "uuid" : "5005a0fa-6916-11e3-9c1b-b77ec8addc0d", + "type" : "group", + "created" : 1387503030399, + "modified" : 1387503030399, + "path" : "managers", + "metadata" : { + "path" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d", + "sets" : { + "rolenames" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/roles", + "permissions" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/permissions" + }, + "collections" : { + "activities" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/activities", + "feed" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/feed", + "roles" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/roles", + "users" : "/groups/5005a0fa-6916-11e3-9c1b-b77ec8addc0d/users" + } + }, + "title" : "Management Employees" + } ], + "timestamp" : 1391020491701, + "duration" : 15, + "organization" : "my-org", + "applicationName" : "my-app" + } + +## Retrieving a group's users + +Use the GET method to retrieve all the users in a group. + +### Request URI + + GET /{org_id}/{app_id}/groups/{uuid|groupname}/users + +### Parameters + +Parameter Description +--------- -------------- +arg uuid|string org_id Organization UUID or organization name +arg uuid|string app_id Application UUID or application name +arg uuid|string groupname UUID or name of the group + +### Example - Request + + curl -X GET "https://api.usergrid.com/my-org/my-app/groups/mygroup/users"; + +### Example - Response + + { + "action" : "get", + "application" : "e7127751-6985-11e2-8078-02e81aeb2129", + "params" : { }, + "path" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users", + "uri" : "http://api.usergrid.com/myorg/sandbox/groups/d20976ff-802f-11e2-b690-02e81ae61238/users";, + "entities" : [ { + "uuid" : "cd789b00-698b-11e2-a6e3-02e81ae236e9", + "type" : "user", + "name" : "barney", + "created" : 1359405994314, + "modified" : 1361894320470, + "activated" : true, + "email" : "bar...@apigee.com", + "metadata" : { + "path" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9", + "sets" : { + "rolenames" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/rolenames", + "permissions" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/permissions" + }, + "collections" : { + "activities" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/activities", + "devices" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/devices", + "feed" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/feed", + "groups" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/groups", + "roles" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/roles", + "following" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/following", + "followers" : "/groups/d20976ff-802f-11e2-b690-02e81ae66238/users/cd789b00-698b-11e2-a6e3-02e81aeb26e9/followers" + } + }, + "name" : "barney", + "picture" : "http://www.gravatar.com/avatar/00767101f6b4f2cf5d02ed510dbcf0b4";, + "test" : "fred", + "username" : "barney" + } ], + "timestamp" : 1361903248398, + "duration" : 24, + "organization" : "myorg", + "applicationName" : "sandbox" + } + +## Deleting a group + +To delete a group, delete the associated group entity as you would any other entity. Note that this will only delete the group. Any entities in the group will be preserved. + +For more information and code samples, see [Deleting Data Entities](../data-storage/entities.html#deleting-data-entities). + +## Adding a user to a group + +See all application entities + +You can add users to groups from client code using cURL commands or one of the SDKs, as described here. + +When setting up your application on the server, you might find it easier and more convenient to create and populate groups with the admin portal. There, you can create groups, create roles, and define permission rules that govern user access to data and services in your application. For more information, see Security & token authentication. + +Use the POST method to add a user to a group. If the named group does not yet exist, an error message is returned. + +### Request syntax + + curl -X POST https://api.usergrid.com/<org_id>/<app_id>/groups/<uuid | groupname>/users/<uuid | username> + +### Request URI + + POST /<org_id>/<app_id>/groups/<uuid | groupname>/users/<uuid | username> + +Parameters + +Parameter Description +--------- ----------- +arg uuid | string org_id Organization UUID or organization name +arg uuid | string app_id Application UUID or application name +arg uuid | string groupname UUID or name of the group +arg uuid | string username UUID or username of user + +### Example + +__Note__: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details. + +### Request + + curl -X POST "https://api.usergrid.com/my-org/my-app/groups/mynewgroup/users/john.doe"; + +### Response + + { + "action": "post", + "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22", + "params": {}, + "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users", + "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/groups/a668717b-67cb-11e1-8223-12313d14bde7/users";, + "entities": [{ + "uuid": "6fbc8157-4786-11e1-b2bd-22000a1c4e22", + "type": "user", + "name": "John Doe", + "created": 1327517852364015, + "modified": 1327517852364015, + "activated": true, + "email": "john....@mail.com", + "metadata": { + "connecting": { + "owners":"/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/connecting/owners" + }, + "path": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22", + "sets": { + "rolenames": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/rolenames", + "permissions": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/permissions" + }, + "collections":{ + "activities":"/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/activities", + "devices": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/devices", + "feed":"/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/feed", + "groups": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/groups", + "roles":"/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/roles", + "following": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/following", + "followers": "/groups/a668717b-67cb-11e1-8223-12313d14bde7/users/6fbc8157-4786-11e1-b2bd-22000a1c4e22/followers" + } + }, + "picture": "https://www.gravatar.com/avatar/90f823ba15655b8cc8e3b4d63377576f";, + "username": "john.doe" + }], + "timestamp": 1331066031380, + "duration": 64, + "organization" : "my-org", + "applicationName": "my-app" + } + +## Removing a user from a group + +Use the DELETE method to remove a user from the specified group. + +### Request syntax + + curl -X DELETE https://api.usergrid.com/<org>/<app>/groups/<group>/users/<user>" + +Parameters + +Parameter Description +--------- ----------- +org Organization UUID or organization name +app Application UUID or application name +group UUID or name of the group +user UUID, username or email of user to be deleted + +### Example request + + curl -X DELETE https://api.usergrid.com/your-org/your-app/groups/someGroup/users/someUser + +### Example response + + { + "action" : "delete", + "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0", + "params" : { }, + "path" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users", + "uri" : "https://api.usergrid.com/your-org/your-app/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users";, + "entities" : [ { + "uuid" : "74d2d7da-e694-11e3-b0c6-4d2664c8e0c3", + "type" : "user", + "name" : "someUser", + "created" : 1401301104077, + "modified" : 1401301104077, + "username" : "someUser", + "email" : "your-...@apigee.com", + "activated" : true, + "picture" : "http://www.gravatar.com/avatar/0455fc92de2636fc7a176cc5d298bb78";, + "metadata" : { + "path" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3", + "sets" : { + "rolenames" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/roles", + "permissions" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/permissions" + }, + "collections" : { + "activities" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/activities", + "devices" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/devices", + "feed" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/feed", + "groups" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/groups", + "roles" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/roles", + "following" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/following", + "followers" : "/groups/cd796d0a-b90c-11e3-83de-83ceb9965c26/users/74d2d7da-e694-11e3-b0c6-4d2664c8e0c3/followers" + } + } + } ], + "timestamp" : 1401751485776, + "duration" : 220, + "organization" : "your-org", + "applicationName" : "your-app" + } http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/4a92ab09/content/docs/_sources/user-management/groups.txt ---------------------------------------------------------------------- diff --git a/content/docs/_sources/user-management/groups.txt b/content/docs/_sources/user-management/groups.txt new file mode 100644 index 0000000..04bed26 --- /dev/null +++ b/content/docs/_sources/user-management/groups.txt @@ -0,0 +1,38 @@ +# Groups + +You can organize app users into groups. Groups have their own Activity Feed, their own permissions and be a useful alternative to Roles, depending on how you model your data. Groups were originaly designed to emulate Facebook Groups, so they will tend to function about the same way Facebook Groups would. + +Groups are hierarchical. Every member of the group /groups/california/san-francisco is also a member of the group /groups/california. + +Groups are also a great way to model things such a topic subscriptions. For example, you could allow people to subscribe (i.e. become a member of the group and be alerted via Activities) to /groups/memes/dogs/doge or subscribe to all /groups/memes/dogs + + +### General properties + + Property Type Description + ---------- -------- --------------------------------------------------------------------------------- + uuid UUID Groupâs unique entity ID + type string Type of entity, in this case âuserâ + created long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity creation + modified long [UNIX timestamp](http://en.wikipedia.org/wiki/Unix_time) of entity modification + path string Valid slash-delimited group path (mandatory) + title string Display name + +### Set properties + + Set Type Description + ------------- -------- --------------------------------------- + connections string Set of connection types (e.g., likes) + rolenames string Set of roles assigned to a group + credentials string Set of group credentials + +### Collections + + Collection Type Description + ------------ ---------- ------------------------------------------------------ + users user Collection of users in the group + activities activity Collection of activities a user has performed + feed activity Inbox of activity notifications a group has received + roles role Set of roles to which a group belongs + +Â
