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
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.
Mobile Identity Connect Architecture with Auth Link Connector
Mobile Identity Connect offers many out of the box integrations, but when one is not available for your identity provider, a custom AuthLink can be created 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 auth link connector sits between Kinvey and internal authentication systems. The adaptor is responsible for verifying the credentials provided from MIC against one or more internal enterprise authentication systems. 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 will be stored in the encrypted MIC vault and provided to Kinvey Data Link Connectors 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 from Kinvey will clear Kinvey's session and refresh tokens from the local device, and cause subsequent requests that use these tokens to fail with a 401 Unauthorized response. However, SSO providers may independently retain their sessions via cookies, enabling a user to log into 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 Ping Identity website after logging out from the associated Kinvey application. This would enable a user to login to their Kinvey app after being logged out, i.e. if they remain logged in to Ping Identity.
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:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth Service protocol to use, set this to SAML-Redirect or SAML-POST based on your IdP requirements. | Yes |
Provider URI | The single sign-on service URL provided by the SAML Identity Provider | Yes |
Redirect URI's | The OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth Grant | Yes |
Logout URI | The Logout URI provided by the SAML Identity Provider | Yes |
Certificate | The X.509 Certificate text provided by the SAML Identity Provider | Yes |
Do not customize the login experience | Do not use any customization for the OAuth login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth grant is valid to obtain an OAuth token | No |
Token TTL | The time (in seconds) that an OAuth token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
Configuring your SAML Identity Provider to accept Kinvey Requests
When configuring the SAML-Based SSO Identity Provider (IdP), the following information should be used. (note: if you are running a dedicated instance of Kinvey, replace auth.kinvey.com
with the URI of your MIC instance. Contact Kinvey Support if you do not know the URI of your instance).
Field | Description | Value |
---|---|---|
entityId | The unique SAML entityID for MIC. | https |
Metadata URI | The signle sign-on service URL provided by the SAML Identity Provider | https |
Assertion Consumer Service | The SAML Assertion URI where SAML assertions will be passed to MIC by the IdP | https |
Logout URL | The SAML logout URI | https |
Name ID Format | The format that Kinvey expects for the auth identifying NameID | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
The v1 entityID is kivney-mobile-identity-connect while the v2+ entityID is https
If the version component is left out of the url, the v1 metadata will be served.
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:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth Service protocol type to use, set this to OAuth2 | Yes |
Provider URI | The token endpoint provided by the OAuth2 Provider | Yes |
Redirect URI's | The 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 Grant | Yes |
Grant Type | The OAuth2 Grant Type to be requested. Authorization Code and Resource Owner Password Credentials are supported. | Yes |
Grant Endpoint | The OAuth 2.0 authorization grant endpoint provided by the OAuth2 provider | Yes |
Client Id | The client id supplied by the OAuth2 provider | Yes |
Client Secret | The client secret supplied by the OAuth2 provider | Yes |
User Id Attribute | The 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 Endpoint | An endpoint from which to obtain the user id, found in many OAuth2 implementations | No |
Scope | Any scope attributes as defined by the OAuth2 provider | No |
Do not customize the login experience | Do not use any customization for the OAuth login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth grant is valid to obtain an OAuth token | No |
Token TTL | The time (in seconds) that an OAuth token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
Configuring your OAuth2 Identity Provider to accept Kinvey Requests
When configuring the OAuth2-Based SSO Identity Provider, the following information should be used. (note: if you are running a dedicated instance of Kinvey, replace auth.kinvey.com
with the URI of your MIC instance. Contact Kinvey Support if you do not know the URI of your instance).
Field | Description | Value |
---|---|---|
Redirect Uri | The URI to which the grant code will be sent. | https |
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 attirbute. Note that the userId endpoint response must be in JSON format. If the uri for the endpoint requires an argument to use JSON, this should be included here.
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:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth service protocol type to use, set this to OpenID Connect | Yes |
Provider URI | The token endpoint provided by the OpenID Connect Provider | Yes |
Redirect URI's | The 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 Grant | Yes |
Grant Endpoint | The authorization grant endpoint provided by the OpenID Connect provider | Yes |
Client Id | The client id supplied by the OpenID Connect provider | Yes |
Client Secret | The client secret supplied by the OpenID Connect provider | Yes |
Issuer Identifier | The issuer identifier supplied by the OpenID Connect provider | Yes |
Scope | Any 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 experience | Do not use any customization for the OpenID Connect login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth 2.0 grant is valid to obtain an OAuth 2.0 token | No |
Token TTL | The time (in seconds) that an OAuth 2.0 token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth 2.0 refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth 2.0 refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
Configuring your OpenID Connect Identity Provider to accept Kinvey Requests
When configuring the OpenID Connect SSO Identity Provider, the following information should be used. (note: if you are running a dedicated instance of Kinvey, replace auth.kinvey.com
with the URI of your MIC instance. Contact Kinvey Support if you do not know the URI of your instance).
Field | Description | Value |
---|---|---|
Redirect Uri | The URI to which the grant code will be sent. | https |
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:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth service protocol to use, set this to Active Directory | Yes |
Provider URI | The Active Directory URI | Yes |
Redirect URI's | The OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth Grant | Yes |
Base DN | The Active Directory base DN | Yes |
Do not customize the login experience | Do not use any customization for the OAuth login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth grant is valid to obtain an OAuth token | No |
Token TTL | The time (in seconds) that an OAuth token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
LDAP
In the Kinvey console Auth Service configuration, the following fields should be filled in:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth service protocol to use, set this to LDAP | Yes |
Provider URI | The LDAP URI | Yes |
Redirect URI's | The OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth Grant | Yes |
Do not customize the login experience | Do not use any customization for the OAuth login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth grant is valid to obtain an OAuth token | No |
Token TTL | The time (in seconds) that an OAuth token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
SAML-WRAP
In the Kinvey console Auth Service configuration, the following fields should be filled in:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth service protocol to use, set this to SAML-WRAP | Yes |
Provider URI | The URI of the WRAP API | Yes |
Redirect URI's | The OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth Grant | Yes |
WRAP Scope | The requested scope as provided by your IdP | Yes |
Do not customize the login experience | Do not use any customization for the OAuth login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth grant is valid to obtain an OAuth token | No |
Token TTL | The time (in seconds) that an OAuth token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
Custom Authlink
In the Kinvey console Auth Service configuration, the following fields should be filled in:
Field | Description | Required? |
---|---|---|
Type of Provider | Auth service protocol to use, set this to Custom | Yes |
Provider URI | The URI of the Auth Link Connector | Yes |
Refresh Url | A url provided by the custom authentication server to provide a new access token via a refresh token. | No |
Redirect URI's | The OAuth 2.0 redirect URI - this should be configured to a Callback URI that will be used to pass the OAuth Grant | Yes |
Do not customize the login experience | Do not use any customization for the OAuth login page | No |
Use a custom CSS stylesheet for the login page | Use 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 host | Use a login page hosted outside of Kinvey for the login page (specify the URL of the hosted login page) | No |
Grant TTL | The time (in seconds) that an OAuth grant is valid to obtain an OAuth token | No |
Token TTL | THe time (in seconds) that an OAuth token is accepted before requiring a new login or refresh | No |
Allow Refresh Tokens | Enable OAuth refresh token support | No |
Refresh Token TTL | The time (in seconds) that an OAuth refresh token is accepted | No |
Allowed Attributes | See the section on attributes and mappings | Yes |
Data Link Header Mappings | See the section on attributes and mappings | Yes |
For details on building a custom AuthLink connector, see the section on Building a Custom AuthLink.
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
All requests to Mobile Identity Connect use the auth
subdomain which is translated to the full base URL of https://auth.kinvey.com/
. If you are using a dedicated instance of Kinvey with a different base URL, then modify the subdomain by setting the instanceId
property on your Client
object.
Kinvey.sharedClient.initialize(
appKey: "<Your App Key>",
appSecret: "<Your App Secret>",
instanceId: "<Your Instance ID>"
) {
switch $0 {
case .success(let user):
if let user = user {
print("User: \(user)")
}
case .failure(let error):
print("Error: \(error)")
}
}
Kinvey.sharedClient.initialize(
appKey: "<Your App Key>",
appSecret: "<Your App Secret>",
instanceId: "<Your Instance ID>"
) {
switch $0 {
case .success(let user):
if let user = user {
print("User: \(user)")
}
case .failure(let error):
print("Error: \(error)")
}
}
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.
You can specify the Auth Service ID either on a Kinvey Client
level or on a method level. The former means that all MIC requests going through this Client
will use the same Auth Service, while the latter only specifies an Auth service for the respective request such as login()
or presentMICViewController()
.
On
Client
level, use theOptions
structure to set theauthServiceId
option to the Auth Service ID you want:Kinvey.sharedClient.initialize( appKey: "<#Your app key#>", appSecret: "<#Your app secret#>" ) { switch $0 { case .success(let user): if let user = user { print("User: \(user)") } case .failure(let error): print("Error: \(error)") } } Kinvey.sharedClient.options = Options(authServiceId: "52c7159d3d8849538333ee6045346ee7")
On request level, pass the
authServiceId
value using theoptions
argument. The following example shows how to passauthServiceId
to thelogin()
method.var opts = Options() opts.authServiceId = "52c7159d3d8849538333ee6045346ee7" User.login(redirectURI: redirect, micURL: url, options: opts)
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.
Initiate the Login Flow
Kinvey provides a helper method that handles the MIC authentication steps for you. It is recommended for most users and consist in a modal view controller with an embedded Web View (SFAuthenticationSession
on iOS 11 or later, otherwise SFSafariViewController
). The following examples rely on this helper method.
Present a MIC View Controller
Present a MIC View Controller, giving the user the opportunity to authenticate using the identity provider's authentication interface.
let redirect = URL(string: "<#myRedirectUri://#>")! // this is the URI you registered in your .plist file as well as in the Console under your Auth Service configuration
User.presentMICViewController(redirectURI: redirect) { user, error in
if (user != nil) {
//logged in successfully
} else if (error != nil) {
//something went wrong if the error object is not nil
} else {
//should never happen!
}
}
let redirect = URL(string: "<#myRedirectUri://#>")! // this is the URI you registered in your .plist file as well as in the Console under your Auth Service configuration
User.presentMICViewController(redirectURI: redirect) {
switch $0 {
case .success(let user):
//logged in successfully
print("User: \(user)")
case .failure(let error):
//something went wrong
print("Error: \(error)")
}
}
Implement the UIApplicationDelegate application() Method
Remember to implement the application(_:open:options)
method of the UIApplicationDelegate
iOS class.
func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
if User.login(redirectURI: redirect, micURL: url, options: nil) {
return true
}
return false
}
Specify Custom URL Scheme
Add your custom URL Scheme
in your Info.plist
file. For example, if your MIC Redirect URI looks like myCustomURLScheme://
, you should add the value myCustomURLScheme
to the CFBundleURLSchemes
key.
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLSchemes</key>
<array>
<string>myCustomURLScheme</string>
</array>
</dict>
</array>
Automated Authorization Grant Flow
The Automated Authorization Grant flow is a modified version of the authorization code grant flow that allows a user's username and password to be submitted to a temporary URI rather than presenting a login page.
Initiate the Login Flow
To initiate an MIC login as part of the Automated Authorization Grant flow, call the login()
method, passing the temporary URI and the username and password combination.
User.login(
redirectURI: URL(string: "<#myRedirectURI://#>")!,
username: "<#myUsername#>",
password: "<#myPassword#>"
) { user, error in
if let user = user {
//logged in successfully
print("User: \(user)")
} else if let error = error {
//something went wrong if the error object is not nil
print("Error: \(error)")
} else {
//should never happen!
}
}
User.login(
redirectURI: URL(string: "<#myRedirectURI://#>")!,
username: "<#myUsername#>",
password: "<#myPassword#>"
) {
switch $0 {
case .success(let user):
//logged in successfully
print("User: \(user)")
case .failure(let error):
//something went wrong
print("Error: \(error)")
}
}
Building a Custom AuthLink
A custom authlink is a lightweight microservice that acts as a bridge between Mobile Identity Connect and an enterprise identity system. It can be deployed anywhere, and must implement a single HTTP endpoint (defined in the provider URI in the Kinvey console) which is invoked using an HTTP POST. If the provider URI is http://auth.example.com/a/u/th, it will be invoked as POST /a/u/th.
The payload is encoded as UTF-8 with Content-Type
set to application/json
. The payload contains:
{
username: <string>,
password: <string>
}
The adaptor is required to respond in one of two ways depending on error or success.
Error
On an error the adaptor is expected to return an HTTP status code of 401. An optional JSON body can be returned with a single property authError
. The authError property can either be an object or a string.
If an object, the object must have two properties: error
, and error_description
. The error
value must be one of the following:
- server_error
- access_denied
- temporarily_unavailable
If the error does not match one of these three, server_error
will be used. The error object returned to the client will be the contents of the authError
object.
If authError
is set to a string, then an error object will be constructed with authError.error
set to server_error
and the error_description
set to the contents of the string.
Success
On success the adaptor is required to return an HTTP status code of 200 with a body encoded as UTF-8 with Content-Type
set to application/json
. The payload should contain:
{
authenticated: true,
token: ""
}
where token
is an arbitrary Base64 encoded string. This string may be an opaque token or a serialized object that includes all enterprise tokens that need to be sent to the data link connector. This object gets stored encrypted in the MIC value and is provided to data link connectors (per configured attributes and mappings).
Additionally a refresh_token
and an expires_in
value can be provided in order to allow automatic refresh of the authentication token. The payload should look like:
{
authenticated: true,
token: "",
refresh_token: "",
expires_in: 3600
}
When a refresh_token
value and an expires_in
value is provided with the token, the system is will attempt to obtain a new token using the refresh token. Upon requesting a new MIC access token via the refresh flow or when validating the MIC access token, if the token is expired the system will attempt to refresh the token by sending the refresh_token
to the custom auth Refresh Url. If an expires_in
value is provided without a refresh token, the token value will be used in the refresh flow.
The payload is encoded as UTF-8 with Content-Type
set to application/json
. The payload contains:
{
refresh_token: "",
grant_type: "refresh_token"
}
At the this point the Custom AuthLink should respond with a Success or Error as described in this section. This allows the Custom AuthLink to implement features like: expiring tokens, revoking access etc.
Additional properties can be included in the response. These properties can be added to the user object by including them in the allowed attributes
of your MIC configuration.
Error Types
The following are the possible errors that can be returned, with the corresponing reasons:
Error | Cause |
---|---|
invalid_grant | The Grant code being sent for the token request is invalid. This usually occurs if the request takes longer than the grant TTL configurable in the console (default 10 seconds but can be changed) |
invalid_request | The parameters that were submitted in the request from the client are invalid (e.g. incorrect redirect_uri, client_id (app Key), or client_secret (app secret). |
invalid_client | The client (app id) is invalid, or the client secret (app secret) and redirect uri are invalid for the specific client |
invalid_token | The token is invalid. This often means that the token has expired, but can be caused by other issues (such as a token that was never valid). |
server_error | A server error has occurred. This may indicate an error accessing the underlying auth source (e.g. the SAML SSO system, the OAuth system, a custom AuthLink Connector, etc). |
access_denied | The credentials submitted by the user are invalid |
unauthorized_client | The app is not authorized. (App Key and secret don't match) |
unsupported_grant_type | The grant type isn't supported by MIC. This error should never be received if using the Library methods. |
invalid_scope | The scope requested by the client is invalid. |
temporarily_unavailable | The remote IdP service is temporarily unavailable. |
Unknown Error | An unknown error. Please submit to support along with a requestId (if possible) and the date and time the error occured. |