Mobile Identity Connect

Introduction

Mobile Identity Connect (MIC) is a service that bridges mobile applications with existing enterprise identity and single sign-on solutions. MIC enables mobile applications to integrate with a variety of identity solutions using a single OAuth2-based interface. This allows enterprise application developers to avoid the complexity of integrating these protocols into mobile, while providing enterprise IT the means to ensure that access to resources is secured only to authenticated users, as well as maintaining full control over a mobile user's identity.

Core Concepts

MIC Architecture

Mobile Identity Connect Architecture

Mobile Identity Connect (MIC) is the authentication layer for connecting to mobile identity systems. It uses OAuth2 as its underlying identity protocol for connecting client applications. A client application uses OAuth2 to authenticate with the Kinvey Authentication Service. The service provides a login page or redirects to an existing SSO login page, allowing the client user to authenticate.

MIC's architecture enables multi-factor authentication (MFA) for mobile clients during the authentication process by exposing MFA controls through the login page.

Once authenticated, MIC retrieves a token from the underlying identity provider, encrypts it, and securely stores it for use in all future requests to access enterprise resources through Data Link connectors. A Mobile Identity Connect access token is returned to the client, along with an (optional) refresh token.

The client exchanges this token for a Kinvey session token. The Kinvey Cloud Service (KCS) then validates this token with MIC for all future requests from that session token. User credentials are not stored on the device and are never passed directly to KCS.

MIC maintains an internal time-to-live (TTL) for access and refresh tokens which is configured via the Kinvey management console. MIC will re-authenticate the user after the TTL expires which will cause the underlying authentication system to be asked to obtain any tokens again. The TTL should be configured to match the lifetime of the internal authentication.

MIC Architecture with Custom MIC Connector

Mobile Identity Connect Architecture

Mobile Identity Connect offers many out of the box integrations, but when one is not available for your identity provider, you can develop a custom MIC connector to integrate with a host of custom identity systems, such as SSO cookies, database-based authentication, or authentication against a line of business application.

The custom connector sits between Kinvey and the identity system in question. Your adaptor needs to be responsible for verifying the credentials provided from MIC against the identity system. The adaptor is also responsible for obtaining any internal enterprise authentication tokens, such as SSO cookies, SAML assertions, OAuth tokens, or session tokens. Tokens passed back to MIC are stored in the encrypted MIC vault and provided to Kinvey data connectors (if you configure any) during normal Kinvey request processing.

All links controlled by Kinvey are encrypted using TLS. Links not controlled by Kinvey are expected to use TLS encryption for production deployments.

Keep in mind that SSO providers often store their own session data in cookies and logging out of Kinvey will clear the Kinvey session and refresh tokens from the local device. This, in turn, will cause subsequent requests that use these tokens to fail with a 401 Unauthorized response. However, SSO providers may independently retain their sessions through cookies, enabling a user to log in to the Kinvey app again through SSO without re-entering their password.

For instance, using Ping Identity with SAML-Redirect, the user will remain authenticated on the Ping Identity website after logging out of the associated Kinvey application. This would enable a user to log in to their Kinvey app after being logged out.

You need to implement you custom MIC connector as a FlexAuth service and similarly to any other Flex service, you can deploy it either in the Kinvey cloud as an internal Flex service or on infrastructure that you manage as an external Flex service.

Read the Flex Services guide to start off with Flex and the Flex SDK, or go directly to the FlexAuth section to learn how to write an auth service.

Single Sign on across multple Kinvey Mobile Apps

Applications developed with MIC can share authentication credentials between applications hosted on the same device when they use the same Auth Services. An access token granted by Mobile Identity Connect is valid for any environment that is using that specific Auth Service.

Configuring an Auth Service

When two applications share the MIC Auth Services, they can also share the access token between them. This allows a Single Sign On experience for a user on a single device. For example if an enterprise develops an expense reporting application and a separate field service management applications, users of the two apps will only need to log in to either app once to be logged in for both applications. The Kinvey mobile libraries support this feature by storing the access token in secure shared storage on the device. This is configured within Kinvey by using Auth Services on each environment from a shared scope, such as an Organization.

Service Catalog

Configuration of Authentication Services is performed in the Service Catalog of the management console. To configure a connector to an Enterprise Identity Source, click the “Add a Service” button and and select "RapidAuth" from the service types and follow up by selecting the type of connector that you want to configure. This will take you to a configuration page with a form specific to each type of connector. See the following sections for details of each specific type of connector.

An auth-service can be created with a scope of a specific environment or at an Organization level. Organization level Auth-services may be used by any environment belonging to the organization. During configuration, the connector must be associated with an environment by selecting the appropriate application and then the environment. Enterprise customers may also choose to associate the connector with their Organization. A list of one or more connectors can be created for each environment or organization.

Configuring the Environment

Once at least one auth connector has been configured for an environment or an organization, it can be activated by navigating to the Mobile Identity Connect tab of the environment details view.

Environment Mobile Identity Connect

On this page the user can view the set of available services and switch between the environment set or the organization level set, if applicable. Additionally, the default connector can be selected from this view. The default connector is used in the authentication flow if the developer chooses to not specify an auth connector by ID when initiating the authentication flow

Connector Specific Configuration

SAML

Mobile Identity Connect supports SAML SP initiated SSO via POST-POST and Redirect-Post Bindings. Mobile Identity Connect does not support IdP-initiated SSO.

Configuring Kinvey

Configure SAML

In the Kinvey console Auth Service configuration, the following fields should be filled in:

FieldDescriptionRequired?
Type of ProviderAuth Service protocol to use, set this to SAML-Redirect or SAML-POST based on your IdP requirements.Yes
Provider URIThe single sign-on service URL provided by the SAML Identity ProviderYes
Redirect URI'sThe OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth GrantYes
Logout URIThe Logout URI provided by the SAML Identity ProviderYes
CertificateThe X.509 Certificate text provided by the SAML Identity ProviderYes
Name ID Format URIAligns the expectations between the identity provider and Kinvey on the format of the user identity that is communicated. The identity provider specifies the user name or the identity of the authenticated user through the NameID attribute. The identity provider defines the format. The setting indicates what format Kinvey should expect from the Identity provider. If none is specified then the default format is "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"No
Do not customize the login experienceDo not use any customization for the OAuth login pageNo
Use a custom CSS stylesheet for the login pageUse a CSS file to customize the look-and-feel of the OAuth login page (specify the URL of the stylesheet)No
Use a custom login page that I will hostUse a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page)No
Grant TTLThe time (in seconds) that an OAuth grant is valid to obtain an OAuth tokenNo
Token TTLThe time (in seconds) that an OAuth token is accepted before requiring a new login or refreshNo
Allow Refresh TokensEnable OAuth refresh token supportNo
Refresh Token TTLThe time (in seconds) that an OAuth refresh token is acceptedNo
Allowed AttributesSee the section on attributes and mappingsYes
Data Link Header MappingsSee the section on attributes and mappingsYes

Users of Ping Identity's PingOne service should use the "Initiate Single Sign-On (SSO) URL" that is provided by PingOne when adding Kinvey as an application.

Configuring your SAML Identity Provider to accept Kinvey Requests

When configuring the SAML-Based SSO Identity Provider (IdP), the following information should be used.

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to prepend their Instance ID to the MIC base URL as follows:

https://<instance>-auth.kinvey.com

You can find your Instance ID on the dashboard of the Kinvey Console, next to your App Key and App Secret.

FieldDescriptionValue
entityIdThe unique SAML entityID for MIC.https://auth.kinvey.com/kinvey-mobile-identity-connect
Metadata URIThe single sign-on service URL provided by the SAML Identity Providerhttps://auth.kinvey.com/v2/saml/metadata
Assertion Consumer ServiceThe SAML Assertion URI where SAML assertions will be passed to MIC by the IdPhttps://auth.kinvey.com/v2/saml/assertion/
Logout URLThe SAML logout URIhttps://auth.kinvey.com/v2/saml/logout

Note the version component of the SAML urls. Ensure that this version number "v2" matches the version of the MIC API that is being used from your application. The SAML metadata may vary between versions.

The v1 entityID is kinvey-mobile-identity-connect while the v2+ entityID is https://auth.kinvey.com/kinvey-mobile-identity-connect. The various SAML urls in the metadata will also incorporate the version number.

If the version component is left out of the url, the v1 metadata will be served.

Users of Ping Identity's PingOne service can find a pre-configured link to Kinvey's Moble Identity Connect in the application catalog by searching for "Kinvey".

Kinvey does not directly support SSO Single Logout. The SAML identity provider should be accessed manually if single logout is required.

SAML Assertion Attributes

Kinvey supports the passing of SAML assertions to enterprise data sources through Data Link Connectors. Depending on the security requirements of your organization, different SAML attributes may be required for authorization purposes by your data sources. Mobile Identity Connect is configured to accept any attributes in the SAML assertion, and passes them through to any Data Link Connectors as-is.

OAuth2

Mobile Identity Connect supports Authorization Code and Resource Owner Password Credentials Authorization Grant credential types. See your OAuth2 provider administrator or Section 1.3 of the OAuth2 specification for more details.

Use the Facebook Auth connector instead of the OAuth2 connector to connect to Facebook as an IdP.

Configuring Kinvey

Configure OAuth2

In the Kinvey console Auth Service configuration, the following fields should be filled in:

FieldDescriptionRequired?
Type of ProviderAuth Service protocol type to use, set this to OAuth2Yes
Provider URIThe token endpoint provided by the OAuth2 ProviderYes
Redirect URI'sThe OAuth 2.0 redirect URI to be used by the client app - this should be configured to a Callback URI that will be used to pass the OAuth GrantYes
Grant TypeThe OAuth2 Grant Type to be requested. Authorization Code and Resource Owner Password Credentials are supported.Yes
Grant EndpointThe OAuth 2.0 authorization grant endpoint provided by the OAuth2 providerYes
Client IdThe client id supplied by the OAuth2 providerYes
Client SecretThe client secret supplied by the OAuth2 providerNo
User Id AttributeThe attribute to be used to obtain the userId. If no User Id endpoint is supplied, the service will look for the specified attribute in the id_token attribute of the token response. If a User Id endpoint is supplied, a request will be made to that endpoint and the user id will be obtained from the specified attribute.Yes
User Id EndpointAn endpoint from which to obtain the user id, found in many OAuth2 implementations. Response must be in JSON format. If the URI for the endpoint requires an argument to use JSON, include it here.No
ScopeAny scope attributes as defined by the OAuth2 providerNo
Do not customize the login experienceDo not use any customization for the OAuth login pageNo
Use a custom CSS stylesheet for the login pageUse a CSS file to customize the look-and-feel of the OAuth login page (specify the URL of the stylesheet)No
Use a custom login page that I will hostUse a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page)No
Grant TTLThe time (in seconds) that an OAuth grant is valid to obtain an OAuth tokenNo
Token TTLThe time (in seconds) that an OAuth token is accepted before requiring a new login or refreshNo
Allow Refresh TokensEnable OAuth refresh token supportNo
Refresh Token TTLThe time (in seconds) that an OAuth refresh token is acceptedNo
Allowed AttributesSee the section on attributes and mappingsYes
Data Link Header MappingsSee the section on attributes and mappingsYes

Configuring your OAuth2 Identity Provider to accept Kinvey Requests

When configuring the OAuth2-Based SSO Identity Provider, the following information should be used.

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to prepend their Instance ID to the MIC base URL as follows:

https://<instance>-auth.kinvey.com

You can find your Instance ID on the dashboard of the Kinvey Console, next to your App Key and App Secret.

FieldDescriptionValue
Redirect UriThe URI to which the grant code will be sent.https://auth.kinvey.com/oauth2/redirect

In addition, you should obtain a client id, client secret, authorization grant endpoint, and token endpoint from the administrator of your OAuth2 provider, along with the location of the userId attribute.

Refreshing expired Access Tokens

If a refresh_token is returned from the OAuth provider then it will be used to obtain a new token when the old one expires. This action is triggered when the client refreshes or validates the token provided by MIC. A failed refresh token response from the IdP will result in failure to refresh or validate the MIC access token.

OAuth Token Refresh

OpenID Connect

Configuring Kinvey

Configure OpenID Connect

In the Kinvey console Auth Service configuration, the following fields should be filled in:

FieldDescriptionRequired?
Type of ProviderAuth service protocol type to use, set this to OpenID ConnectYes
Provider URIThe token endpoint provided by the OpenID Connect ProviderYes
Redirect URI'sThe OAuth 2.0 redirect URI to be used by the client app - this should be configured to a Callback URI that will be used to pass the OAuth 2.0 GrantYes
Grant EndpointThe authorization grant endpoint provided by the OpenID Connect providerYes
Client IdThe client id supplied by the OpenID Connect providerYes
Client SecretThe client secret supplied by the OpenID Connect providerNo
Issuer IdentifierThe issuer identifier supplied by the OpenID Connect providerYes
ScopeAny scope attributes as defined by the OpenID Connect provider. Include multiple scopes by inserting a space between each scope. You can include both OpenID Connect specific scopes (profile, email, address, phone) and custom scopes.No
Do not customize the login experienceDo not use any customization for the OpenID Connect login pageNo
Use a custom CSS stylesheet for the login pageUse a CSS file to customize the look-and-feel of the OpenID Connect login page (specify the URL of the stylesheet)No
Use a custom login page that I will hostUse a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page)No
Grant TTLThe time (in seconds) that an OAuth 2.0 grant is valid to obtain an OAuth 2.0 tokenNo
Token TTLThe time (in seconds) that an OAuth 2.0 token is accepted before requiring a new login or refreshNo
Allow Refresh TokensEnable OAuth 2.0 refresh token supportNo
Refresh Token TTLThe time (in seconds) that an OAuth 2.0 refresh token is acceptedNo
Allowed AttributesSee the section on attributes and mappingsYes
Data Link Header MappingsSee the section on attributes and mappingsYes

Configuring your OpenID Connect Identity Provider to accept Kinvey Requests

When configuring the OpenID Connect SSO Identity Provider, the following information should be used.

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to prepend their Instance ID to the MIC base URL as follows:

https://<instance>-auth.kinvey.com

You can find your Instance ID on the dashboard of the Kinvey Console, next to your App Key and App Secret.

FieldDescriptionValue
Redirect UriThe URI to which the grant code will be sent.https://auth.kinvey.com/oidc/redirect

In addition, you should obtain a client id, client secret, authorization grant endpoint, token endpoint and issuer identifier from the administrator of your OpenID Connect provider.

Refreshing expired Access Tokens

If a refresh_token is returned from the OIDC provider then it will be used to obtain a new token when the old one expires. This action is triggered when the client refreshes or validates the token provided by MIC. A failed refresh token response from the IdP will result in failure to refresh or validate the MIC access token.

OAuth Token Refresh

Active Directory

Configure Active Directory

In the Kinvey console Auth Service configuration, the following fields should be filled in:

FieldDescriptionRequired?
Type of ProviderAuth service protocol to use, set this to Active DirectoryYes
Provider URIThe Active Directory URIYes
Redirect URI'sThe OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth GrantYes
Base DNThe Active Directory base DNYes
Do not customize the login experienceDo not use any customization for the OAuth login pageNo
Use a custom CSS stylesheet for the login pageUse a CSS file to customize the look-and-feel of the OAuth login page (specify the URL of the stylesheet)No
Use a custom login page that I will hostUse a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page)No
Grant TTLThe time (in seconds) that an OAuth grant is valid to obtain an OAuth tokenNo
Token TTLThe time (in seconds) that an OAuth token is accepted before requiring a new login or refreshNo
Allow Refresh TokensEnable OAuth refresh token supportNo
Refresh Token TTLThe time (in seconds) that an OAuth refresh token is acceptedNo
Allowed AttributesSee the section on attributes and mappingsYes
Data Link Header MappingsSee the section on attributes and mappingsYes

LDAP

Configure LDAP

In the Kinvey console Auth Service configuration, the following fields should be filled in:

FieldDescriptionRequired?
Type of ProviderAuth service protocol to use, set this to LDAPYes
Provider URIThe LDAP URIYes
Redirect URI'sThe OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth GrantYes
Do not customize the login experienceDo not use any customization for the OAuth login pageNo
Use a custom CSS stylesheet for the login pageUse a CSS file to customize the look-and-feel of the OAuth login page (specify the URL of the stylesheet)No
Use a custom login page that I will hostUse a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page)No
Grant TTLThe time (in seconds) that an OAuth grant is valid to obtain an OAuth tokenNo
Token TTLThe time (in seconds) that an OAuth token is accepted before requiring a new login or refreshNo
Allow Refresh TokensEnable OAuth refresh token supportNo
Refresh Token TTLThe time (in seconds) that an OAuth refresh token is acceptedNo
Allowed AttributesSee the section on attributes and mappingsYes
Data Link Header MappingsSee the section on attributes and mappingsYes

SAML-WRAP

Configure WRAPv0.9

In the Kinvey console Auth Service configuration, the following fields should be filled in:

FieldDescriptionRequired?
Type of ProviderAuth service protocol to use, set this to SAML-WRAPYes
Provider URIThe URI of the WRAP APIYes
Redirect URI'sThe OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth GrantYes
WRAP ScopeThe requested scope as provided by your IdPYes
Do not customize the login experienceDo not use any customization for the OAuth login pageNo
Use a custom CSS stylesheet for the login pageUse a CSS file to customize the look-and-feel of the OAuth login page (specify the URL of the stylesheet)No
Use a custom login page that I will hostUse a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page)No
Grant TTLThe time (in seconds) that an OAuth grant is valid to obtain an OAuth tokenNo
Token TTLThe time (in seconds) that an OAuth token is accepted before requiring a new login or refreshNo
Allow Refresh TokensEnable OAuth refresh token supportNo
Refresh Token TTLThe time (in seconds) that an OAuth refresh token is acceptedNo
Allowed AttributesSee the section on attributes and mappingsYes
Data Link Header MappingsSee the section on attributes and mappingsYes

Facebook Auth

Mobile Identity Connect supports version 3.0 of the Facebook Graph API for Identity Provider (IdP) purposes.

Configuring Kinvey

Complete these steps to create and set up a Facebook Auth connector:

  1. In the Kinvey Console, go to the Apps tab and select an app environment.
  2. Go to Identity > Mobile Identity Connect.
  3. Click Add Auth Service.
  4. Select the Facebook Auth type.
  5. Fill in the settings as indicated below and click Save Service.
FieldDescriptionRequired?
NameArbitrary name. Appears in the list of services. Note that duplicate names are allowed.Yes
DescriptionExplanatory text to help you distinguish this service easier.No
Scope (generic)Limits the visibility of the service to the selected domain: app environment or organization.Yes
Redirect URI'sIdP's authorization endpoint to be used by the client app. Should be configured to a callback URI that will be used to pass the OAuth grant.Yes
Client IdClient ID supplied by Facebook.Yes
Client SecretClient secret supplied by Facebook.No
User Id AttributeAttribute name to use as a unique identifier. Once set, changing it can produce duplicate Kinvey user accounts and is not recommended. Overwrites any value set through Unique User Context Field.Yes
Scope (OAuth)User attributes to request from Facebook with the initial authorization request. The user can prohibit Facebook from sending these.No
Unique user context fieldAttribute name from the OAuth access token to use as a unique identifier. If left blank, the username is used. Once set, changing it can produce duplicate Kinvey user accounts and is not recommended. The User ID Attribute value overwrites this value if set.
Grant TTLHow much time the client has to obtain an OAuth access token. Default is 10 s.No
Token TTLHow much time before requiring a new login or token refresh. Default is 3600 s.No
Allow Refresh TokensWhen the OAuth access token expires, you can request a token refresh instead of reauthenticating the user.No
Refresh Token TTLFor how long the refresh tokens is accepted. The user will have to reauthenticate after that. Default is 1209600 s (14 days).No
Allowed AttributesAttributes that the client is allowed to request from Kinvey after Kinvey reads all user data from Facebook. See Attributes and Mappings.Yes
Data Link Header MappingsAllows you to map attributes to custom Kinvey headers. See Attributes and Mappings.Yes

Configuring Facebook

Set your Facebook app to allow a redirect URI used internally by Kinvey. Log in to your Facebook developer account, open the app, go to Facebook Login > Settings> Valid OAuth Redirect URIs, and enter the following URI:

https://auth.kinvey.com/facebook/redirect

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to prepend their Instance ID to the MIC base URL as follows:

https://<instance>-auth.kinvey.com

You can find your Instance ID on the dashboard of the Kinvey Console, next to your App Key and App Secret.

Attributes and Mappings

The Allowed Attributes and Data Link Header Mappings settings in the Kinvey Console connector configuration control how enterprise authentication tokens are sent to a data link connector. The attributes id and audience must be included in this section. Click “Add an allowed attribute, and enter the properties.

Configure Attribute Mappings

To send any of these attributes to a data link connector a Data Link Header Mapping is required. Click “Add a header mapping …” and enter client_token as the key and X-Kinvey-Auth as the value. Data link requests will have a header named X-Kinvey-Auth containing the token as a Base64 encoded string.

Authenticating with Mobile Identity Connect

Clients authenticate with Kinvey’s MIC using the OAuth 2.0 protocol. Complete documentation of the OAuth 2.0 protocol is detailed by the IETF.

Information about Refresh Tokens can be found at http://tools.ietf.org/html/rfc6749#section-1.5.

All OAuth implementations authenticate the user and return a grant code via a redirect callback URI. For native applications (Android, iOS and Xamarin) the Redirect URI can be any valid URI, record the value and use it during the normal OAuth flow. For hybrid applications (PhoneGap, etc) follow the framework guides for intercepting redirects and use the same Redirect URL as specified in the console. For web applications choose the Redirect URL where the web app listens for OAuth grants.

Making MIC Requests

All requests to Mobile Identity Connect use the same base URL.

https://auth.kinvey.com/

To execute the requests in this section, append the provided path to the base URL. The rest of the information needed for building the request is provided in the respective sections.

Customers with dedicated Kinvey instances and Progress Health Cloud customers need to prepend their Instance ID to the MIC base URL as follows:

https://<instance>-auth.kinvey.com

You can find your Instance ID on the dashboard of the Kinvey Console, next to your App Key and App Secret.

Selecting an Auth Service

The OAuth2 Spec uses the notion of a client identifier to recognize the application that is accessing the identity service. For Kinvey mobile applications, the client id value is either the App Key from the environment or a combination of the App Key and an Auth Service ID value.

The Auth Service Id is displayed on the Auth Service Listing in the MIC section of the environment. See the following image for an example of where to obtain the Auth Service Id.

Auth Service Id Values

If your application only has a single MIC Auth Service configured, then you can simply use the App Key as the client ID value.

When you are using multiple Auth Service configurations, you can control which Auth Service is selected by providing a specific Auth Service ID with your App Key in the client ID. To create a composite client ID, concatenate the App Key with the Auth Service ID using a dot:

<appKey.authServiceId>

// Example
kid_HkJ8u8hGZ.52c7159d3d8849538333ee6045346ee7

Specifying API Version

You may need to change the MIC API Version used to authenticate with Mobile Identity Connect to enable some MIC features and authentication flows. The default MIC API version is v1.

To explicitly specify an MIC API version, append it to the base URL.

https://auth.kinvey.com/:apiVersion/

//For example, the token endpoint would look as follows
https://auth.kinvey.com/v2/oauth/token

Authorization Code Grant

The authorization code grant flow of the OAuth2 spec provides a two-step authentication process. In the first step, the user is presented with a server-side login page for authentication. In Kinvey's implementation, that login page can be either provided by Mobile Identity Connect (with or without custom styling) or can be independently created and hosted, with Kinvey acting as the router to that page. The login credentials are forwarded to the underlying authentication source for authentication. Upon successful authentication, a short-lived authorization grant code is generated which can be used to create an access token.

Users requiring multi-factor authentication (MFA) support must use the authorization code grant flow configured to use the authentication providers login page.

In the case of SAML-Redirect, the login page is provided by the SAML IdP. Upon successful authentication, a callback URI is invoked with a grant code included in the query string. The grant code is then exchanged for an access token, which is used to authenticate to Kinvey, and exchanged for a Kinvey token.

Keep in mind that a SSO Provider may maintain its own session state independent of the Kinvey app, and Kinvey apps with a third-party SSO Provider configured may be accessible via the Provider site after Kinvey session tokens have been invalidated (as a new session can simply be created by way of SSO). For instance, using Ping Identity with SAML-Redirect, the user will remain authenticated on Ping Identity website after logging out from the associated Kinvey application. This would enable a user to log in to their Kinvey app after being logged out, i.e. if they remain logged in to Ping Identity.

Initiate Grant Request

To initiate the auth flow, a grant request must first be initiated by invoking the below endpoint within your app using a WebView or linking directly to the browser:

GET /oauth/auth?client_id=<your_client_id>&redirect_uri=<redirect_uri>&response_type=code HTTP/1.1
HOST auth.kinvey.com

The query string parameters are:

ParameterDescription
client_idThe app key of the environment or the app key of the environment concatenated with an Auth Service Id.
redirect_uriThe uri that the grant will redirect to on authentication, as set in the console. Note, this must exactly match one of the redirect URIs configured in the console.
response_typeThis should be set to 'code'

This will render a login page for the user to authenticate from the Identity Provider.

Once authenticated, a callback will be initiated by issuing a 302 redirect to the url specified in the redirect_uri query parameter. For native apps, the URL scheme must be registered to intercept the appropriate redirects. For web apps, a service must be provided listening at the redirect URL. The redirect will include a query string parameter code which will contain the auth grant code. For example:

myAppUri://?code=<authGrantCode goes here>

or

https://someurl.com/oauth/callback?code=<authGrantCode goes here>

Note the auth grant code has a short time to live - it expires after 10 seconds.

Initiate Token Request

Once the auth grant code is obtained, an access token is generated by invoking the token endpoint:

POST /oauth/token HTTP/1.1
Host: auth.kinvey.com
Authorization: [app secret credentials]
Content-Type: application/x-www-form-urlencoded

client_id=<clientid>&grant_type=authorization_grant&redirect_uri=<redirect_uri>&code=<grant code>

The value of the Authorization header is composed of the word Basic followed by a whitespace and a base64-encoded string containing the client_id and app secret separated by a colon. In the context of Mobile Identity Connect, the client_id can be the App Key (kid), or the App Key followed by a dot and the id of the authentication service (kid.micId).

For more information about Basic Authentication in Kinvey, refer to the Basic Authentication article.

In the request body, include (in x-www-form-urlencoded format)

ParameterDescription
grant_typeAlways set to 'authorization_code'
client_idThe app key of the environment or the app key of the environment concatenated with an Auth Service Id.
redirect_uriThe same redirect uri used when obtaining the auth grant.
codeThe auth grant code obtained from the callback URI

A successful token request will return:

HTTP/1.1 200 OK
Content-Type: application/json

{
  access_token:  <token>,
  refresh_token: <refreshToken>,
  token_type: 'bearer',
  expires_in: <token lifetime>
}

Logging In to Kinvey

The access token is used to authenticate to Kinvey, and is exchanged for a Kinvey session token:

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "kinveyAuth":
    {
      "access_token": <access token>
    }
  }
}

This generates a Kinvey user that is authenticated with kinveyAuth, with a link to Mobile Identity Connect.

HTTP/1.1 201 Created
Location: https://baas.kinvey.com/user/:appKey/:id
Content-Type: application/json

{
  "_id": "507242b8a8fd60a5120020b4",
  "username": "2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
  "password": "3fc29620-0cdd-419c-ac26-d6006ebab22c",
  "_socialIdentity":
  {
     "kinveyAuth":
     {
       "id": "904292911550952250171",
     }
  },
  "_kmd":
  {
     "lmt": "2012-10-17T21:14:47.975Z",
     "ect": "2012-08-27T19:24:47.975Z",
     "authtoken": "66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0="
  },
  "_acl":
  {
    "creator": "507242b8a8fd60a5120020b4"
  }
}

For all subsequent requests until the user is logged out or the token is expired, the authtoken included in the response should be used in the Authorization header of each request.

Authorization kinvey 66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0=

The _socialIdentity.kinveyAuth.id attribute contains the user ID used to authenticate with MIC, and which can be used for subsequent token logins without having to create a new user. This is done by invoking the login method with a new access token and the user ID included:

POST /user/:appKey/login HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "kinveyAuth":
    {
      "access_token": <access token>,
      "id": <user id>
    }
  }
}

Resource Owner Credentials Grant (Username and Password)

The resource owner credentials grant flow allows an app to send credentials (username and password) directly to the token endpoint. It consists of a single request to obtain a token from the MIC Token endpoint.

The resource owner credentials grant flow requires the security trade-off of trusting the app to handle the credentials securely. With it, the user inputs a username and a password into the app, which exchanges the credentials for an access token. The Authorization Code Grant flow is the recommended flow because is never requires that the user trust the application with their credentials.

The Resource Owner Credentials Grant flow supports LDAP, Active Directory, OAuth2, and Custom Auth Services.

Obtaining Access Token

You can obtain an access token by invoking the Kinvey token endpoint and providing the username and password of the resource owner:

POST /oauth/token HTTP/1.1
Host: auth.kinvey.com
Authorization: [app secret credentials]
Content-Type: application/x-www-form-urlencoded

{
    "grant_type": "password",
    "username": <username>,
    "password": <password>
    "client_id": <client ID>
}
HTTP/1.1 200 OK
Content-Type: application/json

{
  access_token:  <token>,
  refresh_token: <refreshToken>,
  token_type: 'bearer',
  expires_in: <token lifetime>
}

The parameters you can send with the requests are as follows:

ParameterDescription
grant_typeAlways set to password.
usernameThe username to be used for resource owner authentication.
passwordThe password for the user.
client_idThe app key of the environment or the app key of the environment concatenated with an Auth Service Id.

Logging In to Kinvey

You can use the obtained OAuth access token in a login request to authenticate to Kinvey, receiving a Kinvey session token in exchange. In the request, you need to set the social identity to kinveyAuth for Mobile Identity Connect. A login request of this type generates a new Kinvey user account that does not have a username and a password in the normal sense but relies on the passed access_token to verify the user on each request.

POST /user/:appKey/ HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "kinveyAuth":
    {
      "access_token": <access token>
    }
  }
}
HTTP/1.1 201 Created
Location: https://baas.kinvey.com/user/:appKey/:id
Content-Type: application/json

{
  "_id": "507242b8a8fd60a5120020b4",
  "username": "2f127d3e-94ad-44fa-8cbe-48fde6ca12bb",
  "password": "3fc29620-0cdd-419c-ac26-d6006ebab22c",
  "_socialIdentity":
  {
     "kinveyAuth":
     {
       "id": "904292911550952250171",
     }
  },
  "_kmd":
  {
     "lmt": "2012-10-17T21:14:47.975Z",
     "ect": "2012-08-27T19:24:47.975Z",
     "authtoken": "66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0="
  },
  "_acl":
  {
    "creator": "507242b8a8fd60a5120020b4"
  }
}

The authtoken included in the response should be used in the Authorization header of each subsequent request until the user is logged out or the token expires.

Authorization kinvey 66569abc-79aa-11c3-a042-958f1bbf4661.luCTBPjmnPmu8PGMOxOrTnsvlK2H4dIQMC3jj8BULh0=

The _socialIdentity.kinveyAuth.id attribute contains the user ID used to authenticate with MIC. You can use it for subsequent token logins without having to create a new user. Simply invoke the login method with a new access token and the user ID included.

POST /user/:appKey/login HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "kinveyAuth":
    {
      "access_token": <access token>,
      "id": <user id>
    }
  }
}

Refreshing Access Tokens

When an OAuth access token expires and you can't log in the user anymore, you can use the refresh token that you've obtained with the access token to renew the access token. Note that a refresh token is available only if you've configured your Auth Service to issue refresh tokens in the Console.

Refresh Request

After an access token expires, an HTTP 401 response is returned to the client on any subsequent requests. The client can obtain another access token without reauthenticating by submitting a request to the token endpoint.

POST /oauth/token HTTP/1.1
Host: auth.kinvey.com
Authorization: [app secret credentials]
Content-Type: application/x-www-form-urlencoded

client_id=<clientid>&grant_type=refresh_token&redirect_uri=<redirect_uri>&refresh_token=<refresh_token>

The value of the Authorization header is composed of the word Basic followed by a whitespace and a base64-encoded string containing the client_id and app secret separated by a colon. In the context of Mobile Identity Connect, the client_id can be the App Key (kid), or the App Key followed by a dot and the id of the authentication service (kid.micId).

For more information about Basic Authentication in Kinvey, refer to the Basic Authentication article.

In the request body, include (in x-www-form-urlencoded format)

ParameterDescription
grant_typeAlways set to 'refresh_token'
client_idThe app key of the environment or the app key of the environment concatenated with an Auth Service Id.
redirect_uriThe same redirect uri used when obtaining the auth grant.
refresh_tokenThe refresh token

A successful refresh request will return:

HTTP/1.1 200 OK
Content-Type: application/json

{
  access_token:  <token>,
  refresh_token: <refreshToken>,
  token_type: 'bearer',
  expires_in: <token lifetime>
}

Note that both the access token and the refresh token are refreshed.

Refresh tokens are single-use. Once the token is used to obtain a new active token, it is no longer valid. A new refresh token is included in the refresh token response.

Logging In to Kinvey

Because a refresh assumes that a user has already been created, the login method for Kinvey should be used to pass the new access token along with the appropriate ID:

POST /user/:appKey/login HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [Basic Auth with app credentials]

{
  "_socialIdentity":
  {
    "kinveyAuth":
    {
      "access_token": <access token>,
      "id": <user id>
    }
  }
}

Invalidating Access and Refresh Tokens

Sometimes for security reasons, or to log a user out, tokens need to be invalidated. This can be accomplished by invoking the invalidate endpoint and passing the user ID in the query string.

GET /oauth/invalidate?user=<user id> HTTP/1.1
Authorization:  [app secret credentials]

This will invalidate both access tokens and refresh tokens for the given user id.

HTTP/1.1 204 OK

If, for any reason, all tokens need to be invalidated, forcing all users to re-login, the invalidateAll endpoint can be invoked:

GET /oauth/invalidateAll HTTP/1.1
Authorization:  [app secret credentials]

This will invalidate both access tokens and refresh tokens for all users associated with the given environment.

HTTP/1.1 204 OK