Authentication

An app can use one of two forms of authentication - Basic Auth and Session Auth. All credentials used to access any of the Kinvey REST APIs can be used with either style of authentication.

Basic Authentication

The first form of authentication - Basic Auth - authenticates each individual request using a username and password pair.

The Basic Auth token is reversible, however when all communication is over HTTPS the security context is completely protected. Basic Auth is trivial to use from HTTP client libraries. Tools such as cURL provide corresponding command line options.

To use Basic Auth, an app must send an HTTP Authorization header containing the username and password with every request. You will find more details on Basic Auth in IETF RFC 2617. In short, a Basic Auth authorization string is composed of the word Basic followed by a base64-encoded string containing the username and password separated by a colon.

Simple example:

Auth string (before encoding in base64): Basic myUsername:myPassword

Auth string (after base64 encoding): Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk

Complete authorization header: Authorization: Basic bXlVc2VybmFtZTpteVBhc3N3b3Jk

Session Authentication

The second form of authentication - Session Auth - authenticates each individual request using a Kinvey generated auth token.

By using Session Auth, an app eliminates exposure of passwords on every individual request. Only the initial request for setting up the session needs to be sent with the username and password. Session Auth provides an app fine grained access control whereby the Kinvey backend can grant, reject, expire, and invalidate access on a per session basis. Security can be managed without requiring user intervention (e.g.: change of password or disabling the account).

To use Session Auth, an app must first make a login request to collect an auth token from the Kinvey backend. The auth token is returned under the _kmd property in the JSON returned in the response. This auth token can then be used for authentication in subsequent requests across all Kinvey REST APIs.

The auth token is cleared from a device when a user is logged out, but only on the client device. It is important to note that logging out does not invalidate session tokens in Mobile Identity Connect (MIC).

Mobile Identity Connect (MIC) provides an OAuth2 authentication interface for integrating with a number of types of identity providers, including SAML-Redirect, OpenID Connect, Active Directory, and LDAP. MIC maintains a session token for users who are logged in. When a user is logged out on the client device, the session token in MIC remains valid in the event of a logout and invalidation of the auth token on the client device.

To send the auth token with a request, use the HTTP Authorization header with the Kinvey scheme. It’s trivial to add an Authorization header from any HTTP client library or tools such as cURL which provide easy options for customizing standard HTTP headers. Session Auth is only available when accessed for API version 1 or higher.

Authorization: Kinvey 0a8368d7-cbb8-473d-8fec-a1f7f50b764b.X0KQYoRCFEdyBW9WIP/RpzYBrmyraGA5u9cEHprUGk8=

The auth token is cryptographically secured and cannot be reversed. Hence, it’s impervious to forgery. Kinvey auth tokens are long lived, which greatly reduces the security burden on app users. To get info on token inactivity configuration and expiration policies head to User sessions.

To terminate a session, an app should invoke the logout request. A logout will destroy the auth token presented for authenticating the logout request. Any subsequent attempts to re-use that auth token will be rejected with a 401 invalid error response. We recommend apps provide logout functionality to users as a standard security practice for terminating sessions. The Kinvey backend also provides additional security measures by implementing controls for invalidating auth tokens (e.g.: when the password for a user is changed).

MFA Session Authentication

MFA session authentication authenticates an individual request using a Kinvey generated MFA session token. It can be used only in some special cases:

• to complete the login flow when MFA is enabled and the user has to use the second factor to login;

• to set up MFA when the app requires MFA but the user has no MFA setup.

To send the MFA session token with a request, use the HTTP Authorization header with the KinveyMFA scheme. MFA session authentication is only available when accessed for API version 6 or higher.

Authorization: KinveyMFA 0a8368d7-cbb8-473d-8fec-a1f7f50b764b.X0KQYoRCFEdyBW9WIP/RpzYBrmyraGA5u9cEHprUGk8=

The MFA session token is cryptographically secured and short-lived.

Credentials

There are three types of credentials used in our service. User credentials can be used with both Basic Auth and Session Auth, while Master and App credentials can only be used with Basic Auth.

• Master credentials represent the 'admin account' which has complete access over all data. These credentials must never be part of the released mobile app, as the app may be reverse engineered to extract the credentials. The master secret is typically for administrative tasks. Your management console account uses the master credentials to access data from interfaces such as the data browser. You can use the master credentials to create your own custom admin console or scripts, or to access Kinvey data from business logic running in a trusted environment.
• User credentials are what authenticate all communication between the mobile app and Kinvey.
• App credentials are used to bootstrap an app by authenticating the request that creates the user. Since they have very limited grants, there is no expectation that they must remain uncompromised.