How to Sign In with Okta Using Capacitor¶

Okta is a widely used identity platform that powers single sign-on (SSO) and user management for thousands of organizations. If you need to add Okta authentication to a Capacitor app, the OAuth plugin supports the Authorization Code flow with PKCE out of the box. In this guide, you'll learn how to register your app in Okta, implement sign-in and sign-out, manage tokens, and retrieve user profile data on Android, iOS, and web. This is also a great alternative to Ionic Auth Connect for teams looking for a lightweight, open approach.

Build and deploy your Capacitor app with Capawesome Cloud

Prerequisites¶

Before getting started, make sure you have:

An Okta developer account. You can sign up for a free Okta developer account if you don't already have one.
A Capacitor app with the OAuth plugin installed. For installation instructions, head over to the Installation section in the plugin documentation.

Setting Up Okta¶

Creating an Application¶

To get started, you need to register a new application in the Okta Admin Console:

Sign in to your Okta Admin Console.
Go to Applications > Applications and click Create App Integration.
Select OIDC - OpenID Connect as the sign-in method.
Choose Native Application as the application type and click Next.
Give your application a Name (e.g. My Capacitor App).
Under Grant type, make sure Authorization Code and Refresh Token are selected.
Configure the Sign-in redirect URIs and Sign-out redirect URIs (see sections below).
Under Assignments, choose the appropriate controlled access option for your use case.
Click Save.
On the application's General tab, note the Client ID and your Okta domain (e.g. dev-123456.okta.com). You'll need both values later.

Add a redirect URI for each platform your app supports. You can add multiple URIs in the Sign-in redirect URIs section of your application settings.

Android and iOS: Use a custom scheme based on your app's package name or bundle identifier:

com.example.app://oauth/callback

Web: Use your local development URL:

http://localhost:3000/oauth/callback

Configuring Sign-out Redirect URIs¶

Similarly, configure the Sign-out redirect URIs so Okta knows where to send users after they log out.

Android and iOS:

com.example.app://oauth/logout

Web:

http://localhost:3000/oauth/logout

Implementing Authentication¶

In the examples below, replace {okta-domain} with your Okta domain (e.g. dev-123456.okta.com) and {client-id} with your application's Client ID.

Signing In¶

Kick off the OAuth flow using the login(...) method. The plugin fetches Okta's OpenID Connect discovery document automatically and takes care of the PKCE challenge:

import { Oauth } from '@capawesome-team/capacitor-oauth';

const login = async () => {
  const result = await Oauth.login({
    issuerUrl: 'https://{okta-domain}/oauth2/default',
    clientId: '{client-id}',
    redirectUrl: 'com.example.app://oauth/callback',
    scopes: ['openid', 'profile', 'email', 'offline_access'],
  });
  console.log('Access token:', result.accessToken);
  console.log('ID token:', result.idToken);
  console.log('Refresh token:', result.refreshToken);
};

Adding offline_access to the scopes ensures you receive a refresh token.

Handling the Redirect Callback (Web)¶

On the web, login(...) redirects the user to Okta's hosted login page. Once the user authenticates, Okta redirects them back to your app. Call handleRedirectCallback() when the page loads to finish the token exchange:

import { Oauth } from '@capawesome-team/capacitor-oauth';
import { Capacitor } from '@capacitor/core';

const handleRedirectCallback = async () => {
  if (Capacitor.getPlatform() !== 'web') {
    return;
  }
  const url = new URL(window.location.href);
  if (!url.searchParams.has('code')) {
    return;
  }
  const result = await Oauth.handleRedirectCallback();
  console.log('Access token:', result.accessToken);
};

handleRedirectCallback();

On Android and iOS, the redirect is handled natively, so this step only applies to the web.

Refreshing the Access Token¶

Access tokens are short-lived by design. Use the refreshToken(...) method to obtain a fresh access token without prompting the user to sign in again:

import { Oauth } from '@capawesome-team/capacitor-oauth';

const refreshToken = async () => {
  const result = await Oauth.refreshToken({
    issuerUrl: 'https://{okta-domain}/oauth2/default',
    clientId: '{client-id}',
    refreshToken: 'YOUR_REFRESH_TOKEN',
  });
  console.log('New access token:', result.accessToken);
};

Decoding the ID Token¶

Extract user profile claims from the ID token with the decodeIdToken(...) method:

import { Oauth } from '@capawesome-team/capacitor-oauth';

const decodeIdToken = async () => {
  const result = await Oauth.decodeIdToken({
    token: 'YOUR_ID_TOKEN',
  });
  console.log('Name:', result.payload.name);
  console.log('Email:', result.payload.email);
};

The token is decoded locally on the device. If you need server-side verification, validate the JWT on your backend instead.

Signing Out¶

Terminate the session by calling the logout(...) method:

import { Oauth } from '@capawesome-team/capacitor-oauth';

const logout = async () => {
  await Oauth.logout({
    issuerUrl: 'https://{okta-domain}/oauth2/default',
    idToken: 'YOUR_ID_TOKEN',
    postLogoutRedirectUrl: 'com.example.app://oauth/logout',
  });
};

Fetching the User Profile¶

You can also retrieve the authenticated user's profile directly from Okta's /userinfo endpoint using the access token:

import { Oauth } from '@capawesome-team/capacitor-oauth';

const login = async () => {
  const result = await Oauth.login({
    issuerUrl: 'https://{okta-domain}/oauth2/default',
    clientId: '{client-id}',
    redirectUrl: 'com.example.app://oauth/callback',
    scopes: ['openid', 'profile', 'email', 'offline_access'],
  });

  const response = await fetch(
    'https://{okta-domain}/oauth2/default/v1/userinfo',
    {
      headers: {
        Authorization: `Bearer ${result.accessToken}`,
      },
    },
  );
  const user = await response.json();
  console.log('Name:', user.name);
  console.log('Email:', user.email);
};

Try Capawesome Cloud¶

If you're building Capacitor apps, Capawesome Cloud can help you ship faster with cloud-based native builds, over-the-air updates, and more.

Try Capawesome Cloud Free

Conclusion¶

In this guide, you learned how to integrate Okta authentication into a Capacitor app using the OAuth plugin. We covered creating an Okta application, configuring redirect URIs, signing users in and out, refreshing tokens, and fetching profile data. The plugin handles the OIDC and PKCE details under the hood, so you can focus on your app.

For more details, check out the full API Reference for all available methods and options. You might also find the How to Sign In with Azure Entra ID Using Capacitor guide helpful if you need to support multiple identity providers. If you have questions or run into issues, feel free to create an issue on GitHub or join the Capawesome Discord server.

To stay up to date with the latest news, subscribe to the Capawesome newsletter.