Inube iAuth React

React library for integrating Inube applications with the iAuth login flow.

Features

• Redirect login and logout against iAuth.
• Internal endpoint resolution by environment.
• Automatic PKCE generation with SHA-256 challenge encoded in hexadecimal for compatibility with the current iAuth backend.
• Automatic state generation and callback validation.
• Token exchange against the iAuth persistence service.
• Client-side session timeout with configurable activity reset triggers.
• Authentication state, loading state, error handling and idToken access through useIAuth.

Installation

npm install --save @inube/iauth-react

Breaking Changes In This Major

• iAuthUrl was removed from IAuthProvider.
• serviceUrl was removed from IAuthProvider.
• codeVerifier was removed from IAuthProvider.
• codeChallenge was removed from IAuthProvider.
• state was removed from IAuthProvider.
• environment is now required and selects the internal iAuth endpoints.

Provider Setup

import ReactDOM from "react-dom/client";
import { IAuthProvider } from "@inube/iauth-react";

const originatorId = import.meta.env.VITE_ORIGINATOR_ID as string;
const callbackUrl = import.meta.env.VITE_AUTH_CALLBACK_URL as string;
const callbackUrlRequest = import.meta.env.VITE_AUTH_CALLBACK_URL_REQUEST as string;
const applicationName = import.meta.env.VITE_APPLICATION_NAME as string;
const originatorCode = import.meta.env.VITE_ORIGINATOR_CODE as string;
const environment =
  (import.meta.env.VITE_IAUTH_ENVIRONMENT as
    | "development"
    | "production"
    | undefined) ?? "development";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <IAuthProvider
    originatorId={originatorId}
    callbackUrl={callbackUrl}
    callbackUrlRequest={callbackUrlRequest}
    environment={environment}
    applicationName={applicationName}
    originatorCode={originatorCode}
  >
    <App />
  </IAuthProvider>
);

Provider Props

• originatorId: identifier of the originator in iAuth.
• callbackUrl: URL that receives the login or logout callback.
• callbackUrlRequest: request callback URL required by iAuth auxiliary flows.
• environment: one of development or production.
• applicationName: optional application label shown during the flow.
• originatorCode: value forwarded in the token exchange headers.
• registerUrl: optional registration URL forwarded to iAuth.
• externalFlow: optional flag forwarded to iAuth.
• withSignOutTimeout: enables client-side inactivity logout.
• signOutTime: inactivity timeout in milliseconds.
• redirectUrlOnTimeout: post-timeout redirect URL; defaults to callbackUrl.
• resetSignOutMouseMove: resets timeout on mouse movement.
• resetSignOutKeyDown: resets timeout on keyboard input.
• resetSignOutMouseDown: resets timeout on mouse click.
• resetSignOutScroll: resets timeout on scroll.
• resetSignOutTouchStart: resets timeout on touch interaction.
• resetSignOutChangePage: resets timeout on route or history changes.

useIAuth

const {
  user,
  setUser,
  isAuthenticated,
  isLoading,
  error,
  clearError,
  loginWithRedirect,
  logout,
  getAccessTokenSilently,
} = useIAuth();

• loginWithRedirect(): generates PKCE and state, stores the transient values in sessionStorage, builds the iAuth URL and redirects the browser.
• logout(options?): clears the local auth state and redirects to the iAuth logout endpoint.
• getAccessTokenSilently(): resolves with the backend idToken after the callback code has been exchanged.

Storage Strategy

• PKCE codeVerifier and OAuth state are stored only in sessionStorage during the redirect flow.
• The current backend expects codeChallenge = SHA-256(codeVerifier) encoded as hexadecimal, not base64URL.
• Both transient values are cleared after a successful token exchange, on callback errors, and on logout.
• The timeout feature is client-side only; it does not revoke tokens on the backend.

Internal Environments

The provider resolves iAuth endpoints internally according to the selected environment.

• development: local iAuth UI and local persistence process service.
• production: external iAuth UI and external persistence process service.

Session Timeout Example

<IAuthProvider
  originatorId={originatorId}
  callbackUrl={callbackUrl}
  callbackUrlRequest={callbackUrlRequest}
  environment="production"
  applicationName={applicationName}
  originatorCode={originatorCode}
  withSignOutTimeout
  signOutTime={15 * 60 * 1000}
  redirectUrlOnTimeout={`${window.location.origin}/login`}
  resetSignOutMouseMove
  resetSignOutKeyDown
  resetSignOutMouseDown
  resetSignOutScroll
  resetSignOutTouchStart
  resetSignOutChangePage
>
  <App />
</IAuthProvider>

Recommended Environment Variables

VITE_ORIGINATOR_ID=your-originator-id
VITE_AUTH_CALLBACK_URL=http://localhost:5173
VITE_AUTH_CALLBACK_URL_REQUEST=http://localhost:5173
VITE_IAUTH_ENVIRONMENT=development
VITE_APPLICATION_NAME=YourAppName
VITE_ORIGINATOR_CODE=YourOriginatorCode

Authentication Flow

1. The consumer mounts IAuthProvider with callback URLs and an environment.
2. loginWithRedirect() generates PKCE and state internally and stores the transient values in sessionStorage.
3. The browser is redirected to the environment-specific iAuth login endpoint.
4. iAuth redirects back with ac and state.
5. The library validates state, exchanges ac using the stored codeVerifier, and decodes the returned idToken.
6. The transient PKCE/state values are cleared and the authenticated context is exposed through useIAuth.
7. Persistent Storage: Authentication data is stored in localStorage for future sessions

Error Handling

The library provides comprehensive error handling:

function App() {
  const { error, clearError, isAuthenticated } = useIAuth();

  if (error) {
    return (
      <div>
        <h2>Authentication Error</h2>
        <p>{error.message}</p>
        <button onClick={clearError}>Try Again</button>
      </div>
    );
  }
}

URL Parameters

The library automatically handles these URL parameters:

• ac - Access code returned by iAuth after successful authentication
• error - Error code if authentication failed
• error_description - Detailed error description

These parameters are automatically cleaned from the URL after processing.

Local Storage

The library stores the following data in localStorage:

• auth_token - Access token for API calls
• auth_user - Serialized user information

Data is automatically cleared on logout or authentication errors.

API Integration

The library integrates with the iAuth persistence service:

• Service URL: https://iauth.persistence.process.inube.dev/iauth-persistence-process-service/api
• Endpoint: /user-accounts
• Authentication: Basic auth using client credentials
• Timeout: 5 seconds for API calls

Security Features

• Secure Storage: Authentication data stored in localStorage
• Automatic Cleanup: Tokens are cleared on logout or error
• Error Recovery: Invalid stored data is automatically cleaned
• URL Cleanup: Authentication parameters are removed from URL after processing

Development

The components are developed using:

• TypeScript for type safety
• React Hooks for state management
• JWT handling for token processing
• iAuth API integration for user data retrieval

Code is committed using Conventional Commits and releases are managed using auto by Intuit.

Requirements

• React >= 16.8.0
• TypeScript (for TypeScript projects)
• Valid iAuth service credentials

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Issues

If you encounter any issues while using the library, please report them as issues here.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For questions and support, please visit our documentation or create an issue in the repository.