Skip to main content
Version: 3.x

Installation

Don't have an Auth Connect subscription? Try it free now.

Follow these steps to install Auth Connect into your app.

Installation​

If you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.

Next, install the plugin:

npm install @ionic-enterprise/auth@3 
npx cap sync

Capacitor users will need to manually update the native project config files.

For Android, update the manifest file located at android/app/src/main/AndroidManifest.xml by adding the following intents next to the other intents in the main activity node:


_11
<intent-filter>
_11
<data android:scheme="$AUTH_URL_SCHEME"/>
_11
<action android:name="android.intent.action.VIEW"/>
_11
<category android:name="android.intent.category.DEFAULT"/>
_11
<category android:name="android.intent.category.BROWSABLE"/>
_11
</intent-filter>
_11
<intent-filter>
_11
<action android:name="android.intent.action.SEND"/>
_11
<category android:name="android.intent.category.DEFAULT"/>
_11
<data android:mimeType="text/*"/>
_11
</intent-filter>

For iOS, update the file located at ios/App/App/Info.plist by adding the following inside the existing CFBundleURLTypes node:


_10
<dict>
_10
<key>CFBundleURLSchemes</key>
_10
<array>
_10
<string>$AUTH_URL_SCHEME</string>
_10
</array>
_10
</dict>

note

You will need to update the $AUTH_URL_SCHEME placeholder with the bundle id of your app in both files when using Capacitor.

Auth Scheme Naming Consideration​

It is recommended to replace $AUTH_URL_SCHEME with your application's bundle id (com.company.myapp), or another value unique from other custom URL schemes (such as myapp://) registered with your app.

This prevents plugins that handle deep linking from intercepting callbacks made by authentication providers that Auth Connect relies on to complete login/logout functionality.

Common Workflow Primer​

The typical Auth Connect workflow consists of:

  1. Your client app instantiates the Auth Connect Plugin, passing in the IonicAuthOptions object. Configure it based on the chosen auth provider.
  2. On app load, the hosting app calls IsAuthenticated to check if the user is logged in already.
  3. If the user isn't logged in, redirect the app to a Login page and call the Login method. Auth Connect loads the chosen auth provider's login page.
  4. The app user enters their username and password and taps the provider's login button.
  5. On success, Auth Connect automatically retrieves and stores the user's access token. The onLoginSuccess method is fired, and the app can redirect to the desired protected homepage.
  6. The IsAuthenticated method can be called at any point to refresh the access token.
  7. Use GetAccessToken to retrieve the access token if making any API requests to the auth provider.

Configuring Auth Connect​

The main entry point into Auth Connect is done via the IonicAuth class. To configure IonicAuth, you pass in a configuration object when creating a new instance of the class.

This is done by passing in an instance of IonicAuthOptions to the IonicAuth class. The IonicAuth class is the main interface exposed by the Auth Connect plugin, and is expected to be subclassed for specific behaviors and/or events.

Token Storage Provider​

On native devices Auth Connect defaults to storing all of the data and tokens it needs using localStorage as it provides a simple solution that works across all platforms and allows developers to get up and running as quickly as possible. However, before pushing your application to production, we strongly advise implementing a different token storage provider to prevent tokens from being cleared by the device operating system clearing localStorage.

Auth Connect is designed to work easily with Identity Vault to provide a complete security solution for authentication and storage of logged-in credentials by simply passing an instance of Identity Vault to the tokenStorageProvider configuration option for Auth Connect. Alternatively, you can provide your own storage solution by implementing the TokenStorageProvider interface and providing it to the Auth Connect configuration.

Contents