Quick Start

This guide walks you through integrating Auris authentication into your application from scratch. By the end, you will have a working login flow that redirects users to the Auris-hosted login page, handles the callback, and displays the authenticated user’s information.

Estimated time: 5–10 minutes.

Prerequisites

Node.js 20+ (for JavaScript, React, and Next.js integrations)
PHP 7.4+ with Composer (for PHP integrations)
An Auris account — sign up at your Auris Console URL
An existing application project you want to add authentication to

Step 1: Create an Application in the Console

Before installing any SDK, register your application with Auris so it receives a Client ID.

Log in to the Auris Console.
Navigate to Applications in the sidebar.
Click Create Application.
Select the application type:
- WEB — for browser-based apps (React, Next.js, Vue, Angular, server-rendered)
- MOBILE — for native iOS or Android apps
- M2M — for server-to-server or CLI tool integrations (no user login)
Enter a display name for your application (e.g., My App - Development).
Add your Redirect URI — the URL Auris will redirect to after a successful login:
- Local development: http://localhost:3000/callback
- Production: https://yourdomain.com/callback
Click Create.

After creation, copy your Client ID from the application detail page. You will need it in the next steps.

Never expose your Client Secret in browser-side JavaScript. For WEB and MOBILE application types, Auris uses PKCE (Proof Key for Code Exchange) and does not require a client secret. Client secrets are only used for M2M (client_credentials) applications running server-side.

Step 2: Install the SDK

Choose the SDK that matches your stack. All packages are published to npm (JavaScript/TypeScript) or Packagist (PHP).

Next.js


npm install @auris/nextjs @auris/react @auris/js

React


npm install @auris/react @auris/js

JavaScript


npm install @auris/js

PHP


composer require auris/sdk

@auris/nextjs re-exports everything from @auris/react and @auris/js, so you only need one import path in a Next.js project.

Step 3: Configure Auris

Initialize the Auris client with your tenant domain and application Client ID.

Next.js

Add AurisProvider to your root layout.tsx. The provider handles token storage, refresh, and the auth state context for all child components.


// app/layout.tsx
import { AurisProvider } from '@auris/nextjs'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <AurisProvider
          domain="https://auth.yourdomain.com"
          clientId="YOUR_CLIENT_ID"
          redirectUri="http://localhost:3000/callback"
        >
          {children}
        </AurisProvider>
      </body>
    </html>
  )
}

Then add the Auris middleware to protect routes. Create or update middleware.ts at the project root:


// middleware.ts
import { aurisMiddleware } from '@auris/nextjs/middleware'
 
export default aurisMiddleware({
  domain: process.env.AURIS_DOMAIN!,
  clientId: process.env.AURIS_CLIENT_ID!,
  // Routes that require authentication
  protectedPaths: ['/dashboard', '/settings', '/profile'],
  // Routes that skip auth checks entirely (OAuth callback must be public)
  publicPaths: ['/callback', '/login', '/'],
})
 
export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

React

Wrap your application root with AurisProvider:


// src/main.tsx (or src/index.tsx)
import React from 'react'
import ReactDOM from 'react-dom/client'
import { AurisProvider } from '@auris/react'
import App from './App'
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <AurisProvider
      domain="https://auth.yourdomain.com"
      clientId="YOUR_CLIENT_ID"
      redirectUri="http://localhost:3000/callback"
    >
      <App />
    </AurisProvider>
  </React.StrictMode>
)

JavaScript

Create an AurisClient instance. Keep it as a singleton — create it once and export it.


// lib/auris.ts
import { AurisClient } from '@auris/js'
 
export const auris = new AurisClient({
  domain: 'https://auth.yourdomain.com',
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'http://localhost:3000/callback',
})

PHP


<?php
// config/auris.php (or include at app bootstrap)
require_once __DIR__ . '/vendor/autoload.php';
 
use Auris\AurisClient;
use Auris\AurisConfig;
 
$config = new AurisConfig(
    domain: 'https://auth.yourdomain.com',
    clientId: 'YOUR_CLIENT_ID',
    redirectUri: 'http://localhost:8000/callback.php',
    clientSecret: null, // not needed for WEB/PKCE apps
);
 
$auris = new AurisClient($config);

Replace https://auth.yourdomain.com with your actual Auris tenant URL and YOUR_CLIENT_ID with the Client ID from Step 1.

Trigger the login flow by redirecting the user to the Auris-hosted login page.

Next.js


// components/LoginButton.tsx
'use client'
 
import { useAuris } from '@auris/nextjs'
 
export function LoginButton() {
  const { loginWithRedirect } = useAuris()
 
  return (
    <button onClick={() => loginWithRedirect()}>
      Log in
    </button>
  )
}

To log the user in and redirect them to a specific page after authentication:


loginWithRedirect({ returnTo: '/dashboard' })

React


// components/LoginButton.tsx
import { useAuris } from '@auris/react'
 
export function LoginButton() {
  const { loginWithRedirect } = useAuris()
 
  return (
    <button onClick={() => loginWithRedirect()}>
      Log in
    </button>
  )
}

JavaScript


// Initiate login — this redirects the browser to the Auris login page
import { auris } from './lib/auris'
 
document.getElementById('login-button')?.addEventListener('click', async () => {
  await auris.loginWithRedirect()
})

PHP


<?php
// login.php
require_once 'config/auris.php';
 
// Redirects the browser to the Auris hosted login page
$auris->loginWithRedirect();

Or get the URL to render as an anchor tag:


$loginUrl = $auris->getLoginUrl();
echo '<a href="' . htmlspecialchars($loginUrl) . '">Log in</a>';

Step 5: Handle the Callback

After the user authenticates, Auris redirects them back to your redirectUri with an authorization code. Your application must exchange this code for tokens.

Next.js

Create a callback page at the route matching your redirectUri. The @auris/nextjs SDK handles the code exchange automatically when it detects the code parameter in the URL.


// app/callback/page.tsx
'use client'
 
import { useEffect } from 'react'
import { useRouter } from 'next/navigation'
import { useAuris } from '@auris/nextjs'
 
export default function CallbackPage() {
  const { handleRedirectCallback, isLoading } = useAuris()
  const router = useRouter()
 
  useEffect(() => {
    handleRedirectCallback().then(() => {
      // Store intended destination in sessionStorage before loginWithRedirect() if needed
      router.replace('/dashboard')
    })
  }, [])
 
  if (isLoading) {
    return <p>Completing login...</p>
  }
 
  return null
}

React


// src/pages/Callback.tsx
import { useEffect } from 'react'
import { useNavigate } from 'react-router-dom'
import { useAuris } from '@auris/react'
 
export function CallbackPage() {
  const { handleRedirectCallback, isLoading } = useAuris()
  const navigate = useNavigate()
 
  useEffect(() => {
    handleRedirectCallback().then(() => {
      // Store intended destination in sessionStorage before loginWithRedirect() if needed
      navigate('/dashboard', { replace: true })
    })
  }, [])
 
  if (isLoading) {
    return <p>Completing login...</p>
  }
 
  return null
}

JavaScript


// callback.ts — run this script on your callback page
import { auris } from './lib/auris'
 
async function handleCallback() {
  await auris.handleRedirectCallback()
  // Store intended destination in sessionStorage before loginWithRedirect() if needed
  window.location.replace('/dashboard')
}
 
handleCallback()

PHP


<?php
// callback.php
require_once 'config/auris.php';
 
// Exchange the authorization code for tokens
// The SDK reads the 'code' and 'state' parameters from $_GET automatically
$tokenResult = $auris->handleCallback();
 
if ($tokenResult->isSuccess()) {
    // Store the token in the session
    session_start();
    $_SESSION['auris_access_token'] = $tokenResult->accessToken;
    $_SESSION['auris_refresh_token'] = $tokenResult->refreshToken;
 
    // Redirect to the app
    header('Location: /dashboard.php');
    exit;
} else {
    // Handle auth failure
    echo 'Authentication failed: ' . htmlspecialchars($tokenResult->error);
}

Step 6: Display User Information

Once authenticated, retrieve and display the current user’s profile.

Next.js


// app/dashboard/page.tsx
'use client'
 
import { useUser, useAuris } from '@auris/nextjs'
 
export default function DashboardPage() {
  const { user, isLoading } = useUser()
  const { isAuthenticated } = useAuris()
 
  if (isLoading) {
    return <p>Loading...</p>
  }
 
  if (!isAuthenticated) {
    return <p>You are not logged in.</p>
  }
 
  return (
    <div>
      <h1>Welcome, {user?.firstName ?? user?.email}</h1>
      <p>Email: {user?.email}</p>
      <p>Roles: {user?.roles?.join(', ')}</p>
    </div>
  )
}

For server components, use getSession instead:


// app/dashboard/page.tsx (server component)
import { getSession } from '@auris/nextjs/server'
 
export default async function DashboardPage() {
  const session = await getSession({
    domain: process.env.AURIS_DOMAIN!,
    clientId: process.env.AURIS_CLIENT_ID!,
  })
 
  if (!session) {
    // Redirect to login if the middleware is not handling this route
    redirect('/login')
  }
 
  return (
    <div>
      <h1>Welcome, {session.user.firstName}</h1>
    </div>
  )
}

React


// src/components/UserProfile.tsx
import { useUser, useAuris } from '@auris/react'
 
export function UserProfile() {
  const { user, isLoading } = useUser()
  const { isAuthenticated } = useAuris()
 
  if (isLoading) {
    return <p>Loading...</p>
  }
 
  if (!isAuthenticated || !user) {
    return <p>You are not logged in.</p>
  }
 
  return (
    <div>
      <h1>Welcome, {user.firstName ?? user.email}</h1>
      <p>Email: {user.email}</p>
      <p>Roles: {user.roles?.join(', ')}</p>
    </div>
  )
}

JavaScript


// dashboard.ts
import { auris } from './lib/auris'
 
async function renderDashboard() {
  const user = await auris.getUser()
 
  if (!user) {
    // Not authenticated — redirect to login
    await auris.loginWithRedirect()
    return
  }
 
  document.getElementById('user-name')!.textContent =
    user.firstName ?? user.email ?? 'User'
  document.getElementById('user-email')!.textContent = user.email ?? ''
}
 
renderDashboard()

PHP


<?php
// dashboard.php
session_start();
require_once 'config/auris.php';
 
if (empty($_SESSION['auris_access_token'])) {
    header('Location: /login.php');
    exit;
}
 
// Decode the access token to get user info
$user = $auris->getUser($_SESSION['auris_access_token']);
 
if (!$user) {
    // Token expired — attempt refresh
    $refreshed = $auris->refreshToken($_SESSION['auris_refresh_token']);
    if ($refreshed->isSuccess()) {
        $_SESSION['auris_access_token'] = $refreshed->accessToken;
        $user = $auris->getUser($refreshed->accessToken);
    } else {
        header('Location: /login.php');
        exit;
    }
}
?>
<h1>Welcome, <?= htmlspecialchars($user->firstName ?? $user->email) ?></h1>
<p>Email: <?= htmlspecialchars($user->email) ?></p>

Step 7: Add a Logout Button

Next.js


'use client'
 
import { useAuris } from '@auris/nextjs'
 
export function LogoutButton() {
  const { logout } = useAuris()
 
  return (
    <button onClick={() => logout()}>
      {/* Handle post-logout redirect in your router */}
      Log out
    </button>
  )
}

React


import { useAuris } from '@auris/react'
 
export function LogoutButton() {
  const { logout } = useAuris()
 
  return (
    <button onClick={() => logout()}>
      {/* Handle post-logout redirect in your router */}
      Log out
    </button>
  )
}

JavaScript


import { auris } from './lib/auris'
 
document.getElementById('logout-button')?.addEventListener('click', () => {
  // Handle post-logout redirect in your router
  auris.logout()
})

PHP


<?php
// logout.php
session_start();
require_once 'config/auris.php';
 
// Revoke the token server-side
if (!empty($_SESSION['auris_access_token'])) {
    $auris->revokeToken($_SESSION['auris_access_token']);
}
 
// Clear the local session
session_destroy();
 
// Redirect to Auris logout endpoint (clears the Keycloak session)
$logoutUrl = $auris->getLogoutUrl(returnTo: 'http://localhost:8000');
header('Location: ' . $logoutUrl);
exit;

Environment Variables

Store your Auris configuration in environment variables, not in source code. You need two sets of variables: one for client-side (browser) use and one for server-side use.


# .env.local
 
# Client-side: used by AurisProvider in the browser bundle
NEXT_PUBLIC_AURIS_DOMAIN=https://auth.yourdomain.com
NEXT_PUBLIC_AURIS_CLIENT_ID=your_client_id_here
 
# Server-side: used by aurisMiddleware() and getSession() — never exposed to the browser
AURIS_DOMAIN=https://auth.yourdomain.com
AURIS_CLIENT_ID=your_client_id_here
 
# For server-side M2M clients only (never expose this in the browser)
AURIS_CLIENT_SECRET=your_client_secret_here
 
# For JWT verification without a network call (optional, recommended for performance)
AURIS_JWKS_URL=https://auth.yourdomain.com/.well-known/jwks.json

Then use them in your provider setup:


<AurisProvider
  domain={process.env.NEXT_PUBLIC_AURIS_DOMAIN!}
  clientId={process.env.NEXT_PUBLIC_AURIS_CLIENT_ID!}
  redirectUri={`${process.env.NEXT_PUBLIC_APP_URL}/callback`}
>

And in server-side code (middleware, getSession):


// middleware.ts — uses AURIS_DOMAIN / AURIS_CLIENT_ID (no NEXT_PUBLIC_ prefix)
aurisMiddleware({ domain: process.env.AURIS_DOMAIN!, clientId: process.env.AURIS_CLIENT_ID!, ... })
 
// Server component — same server-side vars
getSession({ domain: process.env.AURIS_DOMAIN!, clientId: process.env.AURIS_CLIENT_ID! })

Environment variables prefixed with NEXT_PUBLIC_ are embedded in the browser bundle and are public. Only the domain and clientId should be public. Never expose AURIS_CLIENT_SECRET with a NEXT_PUBLIC_ prefix. The unprefixed AURIS_DOMAIN and AURIS_CLIENT_ID are server-only and are never sent to the browser.

Next Steps

Now that you have a basic login flow working, explore the features most relevant to your application:

Authentication methods

Authorization

User management

SDKs and API

Quick Start

Prerequisites

Step 1: Create an Application in the Console

Step 2: Install the SDK

Next.js

React

JavaScript

PHP

Step 3: Configure Auris

Next.js

React

JavaScript

PHP

Step 4: Add a Login Button

Next.js

React

JavaScript

PHP

Step 5: Handle the Callback

Next.js

React

JavaScript

PHP

Step 6: Display User Information

Next.js

React

JavaScript

PHP

Step 7: Add a Logout Button

Next.js

React

JavaScript

PHP

Environment Variables

Next Steps