Authentication and access in App Services

App Services requests are authenticated via OAuth (Open Authorization) 2.0. OAuth is an authentication mechanism that allows users to grant access to their web resources or mobile apps safely, without having to share their passwords. The analogy of a valet key is sometimes used to describe OAuth, because users can permit general access, but limit access rights to perform certain operations. Instead of an app user having to share a password, OAuth enables access using a security token tied specifically to an app and device , for a specific set of resources and actions.

Unlike OAuth 1.0, which requires special support in the client code for signing requests, OAuth 2.0 can be used by any web service client libraries. Although the OAuth 2.0 specification isn’t finalized yet, it is sufficiently complete so that many web service providers, including Google and Facebook, are now using it for authentication. More information about OAuth 2.0 is available at oauth.net.

Requesting an access token

App Services takes advantage of standard OAuth 2.0 mechanisms that require an access token with data operation requests. To obtain the access token, you connect to an appropriate web service endpoint and provide the correct client credentials. The credentials required to get the token depend on the type of access you need.

Note: The one exception to the access token requirement is requests made with the sandbox app, a test application that is created for you automatically. Authentication is disabled in the sandbox app. So if you use the sandbox app, you do not require an access token for data operation requests.

Using an access token

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://api.usergrid.com/{org-name}/{app-name}/users?access_token={access_token}

• You can include the token in an HTTP authorization header:
  

  Authorization: Bearer {access_token}

Note: The App services 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 Roles and permissions.

Application user

The most commonly used type of access is application user. Application users are the users of your application. You create a user entity for each user. Each user entity has a username and password, which the application user associated with that entity uses to log in to your app. Your app then uses the username and password in a call to the OAuth 2.0 APl to get an application-level access token.

An example of this level of access is the mobile Twitter app. The app user logs into the app, which in turn, makes an API call to OAuth to get an application-level OAuth token. This token allows the user to access their user profile and resources that belong to them (such as tweets they have posted). The token does not allow them to modify any other user’s accounts or data.

Using the username and password values specified when the user entity was created, your app can connect to the App Services application endpoint to request an access token. Here is an example in cURL format of a request for application user access:

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token" -d '{"grant_type":"password","username":"john.doe","password":"testpw"}'

The results include the access token needed to make subsequent API requests on behalf of the application user:

{
  "access_token": "5wuGd-lcEeCUBwBQVsAACA:F8zeMOlcEeCUBwBQVsAACA:YXU6AAABMq0hdy4Lh0ewmmnOWOR-DaepCrpWx9oPmw",
  "expires_in": 3600,
  "user": …
  }
}
        

Application

A user can also log in with application level credentials (client secret and client id). These can be found in the Admin Portal on the Properties page. Application access is a higher level of access than application user and provides access to all the resources of the application — not just those governed by the user's permissions.

An example use of this level of access is a server-side application that needs access to resources through the App Services API. Imagine that you created a web site that lists every hiking trail in the Rocky Mountains. Anyone can go to the web site and view the content. However, you don’t want anyone to have access to the App Services API, where all the data is stored. But you do want to give your web server access so that it can generate the pages to serve to the website’s visitors.

Note: You should never use the client secret and client id to get an access token for a client-side app. A hacker could analyze your app and extract your id and secret for malicious use even if those credentials are compiled and in binary format. See Safe mobile access for additional considerations in keeping access to your app and its data secure.

Using your app’s client id and client secret values, your app can connect to the App Services application endpoint to request an access token. Here is an example in cURL format of a request for application access:

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'

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

Your app should rarely use the admin user level of access because it provides full access to all of the administration features of the App Services API. The Admin Portal uses this level of access because it does require full access to the administration features. Unless you have a specific need for administrative features, such as test scripts that require access to management functionality, you should not use the admin user level of access.

If you do require admin user access, your app can connect to the App Services management endpoint to request an access token. Your app supplies the username and password of an admin user in the request. Here is an example in cURL format of a request for admin user access:

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token"  -d '{"grant_type":"password","username":"testadmin","password":"testadminpw"}'

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

Organization access is the highest level of access. It provides access to perform any operation on an App Services organization. This level of access should be used sparingly and carefully. Currently, organization and admin user access are effectively the same. Eventually, the admin user level will be a configurable subset of the organization level of access.

If you do require organization level access, your app can connect to the App Services management endpoint to request an access token. Access to an organization requires the client id and client secret credentials. Here is an example in cURL format of a request for organization access:

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'

The results include the access token needed to make subsequent API requests to the organization:

{
  "access_token": "gAuFEOlXEeCfRgBQVsAACA:b3U6AAABMqz-Cn0wtDxxkxmQLgZvTMubcP20FulCZQ",
  "expires_in": 3600,
  "organization": {
  …
  }
}
        

Submitting auth token requests to other endpoints

You can submit requests for organization or admin user access to the https://api.usergrid.com/my-org/my-app/token endpoint (rather than the https://api.usergrid.com/management/token endpoint). These requests will generate valid application-level tokens. It will also give the user access to all the resources of the application.

In addition, you can submit requests for application access to the https://api.usergrid.com/management/token endpoint (instead of the https://api.usergrid.com/my-org/my-app/token endpoint). These requests will also generate valid application-level tokens.

However, when you submit an auth token request to these alternative endpoints, user aliases such as /users/me will not work because the token does not map to an actual user.

Note too that you can only submit requests for application user access to the https://api.usergrid.com/my-org/my-app/token endpoint.

Authentication token time to live

An access token has a “time to live”, that is, the maximum time that the access token will be valid for use within the application. The time to live value is a millisecond value that is set in the Application entity’s accesstokenttl property. The default time to live value is one week.

When you request an access token, you can override its time to live by specifying a ttl parameter and a value in milliseconds.

For example, the following sets a time to live value of 18000000 milliseconds (30 minutes) for an admin user:

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token?ttl=1800000" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'

The following sets the same time to live value for an application user.

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token?ttl=1800000" -d '{"grant_type":"password","username":"testadmin","password":"testadminpw"}'

If you don’t set a time to live value in the Application’s accesstokenttl property (or don’t specify a ttl parameter in the request to create the access token), the default time to live is used. If you set the ttlparametet value to 0, it’s the same as not specifying the ttl parameter.

Note: The ttl value must be equal to or less than the value of the 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.

Safe mobile access

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 level of the application user. This means that if you don’t want the user to be able to access or delete data in your App services 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, see Roles and permissions.