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

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.

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

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

Configuring your SAML Identity Provider to accept Kinvey Requests

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

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

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.

Configuring Kinvey

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

Configuring your OAuth2 Identity Provider to accept Kinvey Requests

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

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

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.

OpenID Connect

Configuring Kinvey

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

Configuring your OpenID Connect Identity Provider to accept Kinvey Requests

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

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

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.

Active Directory

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

LDAP

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

SAML-WRAP

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

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.

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

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

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.

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

By default, all requests to Mobile Identity Connect use the base URL of https://auth.kinvey.com/. If you are using a dedicated instance of Kinvey, you need to set the Instance ID to modify the base URL.

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

Client.Builder builder = new Client
                .Builder(your_app_key, your_app_secret)
                .SetInstanceID("<Your Instance ID");

Client kinveyClient = builder.Build();

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.

If your application only has a single MIC Auth Service configured, you don't need to take additional steps.

When you are using multiple Auth Service configurations, you can control which Auth Service is selected by providing a specific Auth Service ID. If you fail to provide an Auth Service ID, MIC uses the service marked as Default in the Console.

The MIC login function accepts an additional authServiceId parameter for the Auth Service ID. Specifying an Auth Service ID is always optional.

await User.LoginWithMIC(
        myUsername,
        myPassword,
        "myRedirectURI://",
        authServiceId,
        kinveyClient);

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

The code snippet below sets the MIC API version on Client instance level.

Client.SharedClient.MICApiVersion = "v2";

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.

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.

Follow the instructions to implement Authorization Code Grant for each of the supported OSes:

• Authorization Code Grant for Android
• Authorization Code Grant for iOS

Authorization Code Grant for Android

The Authorization Code Grant login flow on Android is provided through a distribution of the Kinvey Library on nuget:

nuget Install-Package Kinvey-Android

After you install the package, take the following steps to implement the flow:

• Add Intent-Filter to AndroidManifest.xml
• Override onNewIntent
• Initiate the Login Flow

Add Intent-Filter to AndroidManifest.xml

This login flow uses a Redirect URI to return data to the client after the user has been authenticated. The Android operating system will intercept the redirect and bundle it into an Intent, so that it can be recognized by native applications. First, add an <intent-filter> to the main <activity> tag in the AndroidManifest.xml. The below code snippet shows a sample Activity declaration, containing the new <intent-filter>.

In the code below, replace myredirecturi with a completely lowercase version of the scheme of the application's configured redirect URI. For example, a redirect of MyOauth:// would be entered here as myoauth.

<activity
    android:name="com.kinvey.auth.sample.MainActivity"
    android:label="@string/app_name"
    android:launchMode="singleInstance" >
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>


        <!-- This is the new Intent filter  -->
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="myredirecturi" />  <!-- Change this scheme -->
        </intent-filter>

</activity>

Override onNewIntent

Android uses the intent filter to send the intent to the onNewIntent(Intent intent) method of your activity. Override this method and pass the intent to the Kinvey Client.

protected override void OnNewIntent(Intent intent)
{
    base.OnNewIntent(intent);
    Client.SharedClient.ActiveUser.OnOAuthCallbackRecieved(intent);
}

Initiate the Login Flow

After writing the code to manage the redirect intent, use the next code snippet to initiate the login flow. The action OnReadyToRender(String myURL) executes as soon as the login page URL is generated. You can either render the URL in a webview or pass it to the browser to provide the user with a login page. After the user logs in successfully, the redirect URI is used to return the necessary tokens to the client. After this, the client automatically finishes the login flow and returns a fully initialized, logged-in User to the onSuccess(User user) method. If any error occurs at any point during this oAuth flow, the onError(Exception e) method executes with details of the exception.

User.LoginWithMIC("myRedirectURI://", new KinveyMICDelegate<User>()
{
    onSuccess = (u) => { Console.WriteLine("logged in as: " + u.Id); },
    onError = (error) => { Console.WriteLine("something went wrong: " + error.Message); },
    onReadyToRender = (url) =>
    {
        var uri = Android.Net.Uri.Parse(url);
        var intent = new Intent(Intent.ActionView, uri);
        this.StartActivity(intent);
    }
}, authServiceId);

Authorization Code Grant for iOS

The Authorization Grant Login Flow on iOS is provided through a distribution of the Kinvey Library on nuget:

nuget Install-Package Kinvey-ios

After you install the package, take the following steps to implement the flow:

• Add URL Scheme to info.plist
• Override OpenURL
• Initiate the Login Flow

Add URL Scheme to info.plist

This login flow uses a Redirect URI to return data to the client after the user has been authenticated. iOS will intercept the redirect hand it off to your application, so that it can be recognized by native applications. First, modify the info.plist file at the root of your project.

In the instructions below, replace myRedirectURI with the application's configured redirect URI, ignoring the trailing ://. For example, a redirect of MyOauth:// would be entered here as MyOauth.

1. In Xamarin Studio, open info.plist
2. Click the Advanced tab at the bottom of the editor window.
3. Scroll down to the URL Types section and click Add URL Type
4. Set the URL Schemes value to your Redirect URI - myRedirectURI. Ignore the trailing :// here.
5. Set the Role to be Editor.
6. Leave Identifier and Icon blank and save the file.

Override OpenURL

iOS will use the above described URL Scheme to delegate a request to the AppDelegate, and will execute the OpenURL method. Inside your AppDelegate.cs class insert the following method override:

public override bool OpenUrl (
            UIApplication application,
            NSUrl url,
            string sourceApplication,
            NSObject annotation
)
{
    return Client.SharedClient.ActiveUser.OnOAuthCallbackRecieved(url);
}

Initiate the Login Flow

After writing the code to manage the redirect intent, use the below code snippet to initiate the login flow. The action onReadyToRender(String myURL) will be executed when the login page URL has been generated. This URL can be rendered in a webview or passed to the browser, and will provide the user with a login page. Once they have successfully logged in, the redirect URI will be used to return the necessary tokens to the client. After this, the client will automatically finish the login flow and return a fully initialized, logged-in User to the onSuccess(User user) method. If any error occurs at any point during this oauth flow, the onError(Exception e) method will be executed with details of the exception.

User.LoginWithMIC("myRedirectURI://", new KinveyMICDelegate<User>()
{
    onSuccess = (u) => { Console.WriteLine("logged in as: " + u.Id); },
    onError = (error) => { Console.WriteLine("something went wrong: " + error.Message); },
    onReadyToRender = (url) => { UIApplication.SharedApplication.OpenUrl(new NSUrl(url)); }
}, authServiceId);

Resource Owner Credentials Grant (Username and Password)