Connecting to Custom Authentication Providers

Providers are a way to describe to Auth Connect how to interact with your Authentication provider. We've shipped a number of providers out of the box to cover the most common scenarios, but there are many providers that exist that require a slightly different implementation than the ones we've provided. In these cases, you can create a custom provider to handle the specifics of your provider.

Extending an Existing Provider

In many cases, the providers Auth Connect ships with can get you 95% of the way with just about any authentication provider and it may be that you only need to make one or two small changes to get things working. Perhaps add a few extra parameters to your request, or read the url from a different location. In these cases, extending an existing provider can save you the work of needing to implement all the of the required methods for a completely custom provider. It can be done by simply extending the provider you want to extend and overriding the methods you need to change.

Add a custom parameter to an authorization request

import { Auth0Provider } from '@ionic-enterprise/auth';

export class MyCustomProvider extends Auth0Provider {
  async authorizeRequest(
    manifest: Manifest,
    options: ProviderOptions,
    config: Pick<
      AuthConnectConfig,
      'ios' | 'android' | 'web' | 'platform' | 'logLevel'
    >
  ) {
    const { url, params } = await super.authorizeRequest(
      manifest,
      options,
      config
    );

    params['custom_param'] = 'custom_value';

    return {
      url,
      params
    };
  }
}

This is ideal because you can simply re-use all of the logic that Auth Connect is already providing for you and only need to override the methods that need to be changed. This is a great way to get started with a custom provider. If you find that you need to override more and more methods, you may want to consider implementing a completely custom provider.

Creating a Custom Provider

If you find that you need to implement a completely custom provider, you can do so by implementing the AuthProvider abstract class. This class defines all of the methods that Auth Connect expects a provider to implement. You must implement all the required methods, and in each case, you must return the ProviderURLInfo object. You have full control over how to build that object in each case.

import { AuthProvider } from '@ionic-enterprise/auth';

export class MyCustomProvider extends AuthProvider {
  async authorizeRequest(
    manifest: Manifest,
    options: ProviderOptions,
    config: Pick<
      AuthConnectConfig,
      'ios' | 'android' | 'web' | 'platform' | 'logLevel'
    >
  ) {
    return {
      url: '',
      params: {}
    }
  }

  async tokenRequest(
    manifest: Manifest,
    options: ProviderOptions,
    config: Pick<
      AuthConnectConfig,
      'ios' | 'android' | 'web' | 'platform' | 'logLevel'
    >
  ) {
    return {
      url: '',
      params: {}
    }
  }

  async refreshTokenRequest(
    manifest: Manifest,
    options: ProviderOptions,
    config: Pick<
      AuthConnectConfig,
      'ios' | 'android' | 'web' | 'platform' | 'logLevel'
    >
  ) {
    return {
      url: '',
      params: {}
    }
  }

  async logoutRequest(
    manifest: Manifest,
    options: ProviderOptions,
    config: Pick<
      AuthConnectConfig,
      'ios' | 'android' | 'web' | 'platform' | 'logLevel'
    >
  ) {
    return {
      url: '',
      params: {}
    }
  }
}

The abstract class also provides two helper methods that you can use when generating your requests. The first is checkOrGenerateKeys(config). It will generate a PKCE compliant key and a nonce that you can use for your requests. You should call this anytime you need it and the values will be available as properties on the class instance.

async authorizeRequest(
  manifest: Manifest,
  options: ProviderOptions,
  config: Pick<
    AuthConnectConfig,
    'ios' | 'android' | 'web' | 'platform' | 'logLevel'
  >
) {
  await this.checkOrGenerateKeys(config);
  console.log({
    key: this.key,
    nonce: this.nonce
  });
}

The second helper method is usePKCE(config) which will tell you if PKCE is enabled based on the provided configuration. If you're writing your own provider, this method may be less helpful unless you allow your users to change the auth configuration, as you as the developer would know this value.

async authorizeRequest(
  manifest: Manifest,
  options: ProviderOptions,
  config: Pick<
    AuthConnectConfig,
    'ios' | 'android' | 'web' | 'platform' | 'logLevel'
  >
) {
  const isPKCE = this.usePKCE(config);
}

Once you've created your new provider, you can use it in your application same as any existing provider.

import { AuthConnect } from '@ionic-enterprise/auth';
import { MyCustomProvider } from './custom-provider';

async function tryLogin() {
  const authResult = await AuthConnect.login(new MyCustomProvider(), {...});
}