Learn how to integrate iuv.one authentication into your application using OpenID Connect (OIDC). This guide covers everything from basic setup to advanced configurations.
iuv.one is an OpenID Connect (OIDC) Provider that enables single sign-on (SSO) across the iuv ecosystem and third-party applications. It implements the OAuth 2.0 Authorization Code flow with PKCE support for enhanced security.
PKCE required for public clients, token rotation, and secure token storage.
Full OpenID Connect Core 1.0 compliance with discovery support.
Works with any OIDC-compatible library or framework.
First, create an OAuth application in the iuv.one dashboard. You'll receive a client_id and client_secret.
Add your application's callback URL (e.g., https://yourapp.com/auth/callback) to the allowed redirect URIs.
Use the authorization endpoint to initiate login:
https://iuv.one/oauth/authorize?
response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https://yourapp.com/auth/callback
&scope=openid profile email
&state=RANDOM_STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256After the user authorizes, exchange the code for tokens:
curl -X POST https://iuv.one/api/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTHORIZATION_CODE" \
-d "redirect_uri=https://yourapp.com/auth/callback" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "code_verifier=CODE_VERIFIER"iuv.one provides an OpenID Connect discovery document at /.well-known/openid-configuration. Most OIDC libraries can auto-configure using this URL.
{
"issuer": "https://iuv.one",
"authorization_endpoint": "https://iuv.one/oauth/authorize",
"token_endpoint": "https://iuv.one/api/oauth/token",
"userinfo_endpoint": "https://iuv.one/api/oauth/userinfo",
"jwks_uri": "https://iuv.one/api/oauth/jwks",
"revocation_endpoint": "https://iuv.one/api/oauth/revoke",
"response_types_supported": ["code"],
"grant_types_supported": ["authorization_code", "refresh_token"],
"subject_types_supported": ["public"],
"id_token_signing_alg_values_supported": ["RS256"],
"scopes_supported": ["openid", "profile", "email", "offline_access"],
"token_endpoint_auth_methods_supported": [
"client_secret_basic",
"client_secret_post"
],
"code_challenge_methods_supported": ["S256"]
}For Next.js applications, we recommend using next-auth (Auth.js) with the generic OIDC provider:
// app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth";
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [
{
id: "iuv",
name: "iuv.one",
type: "oidc",
issuer: "https://iuv.one",
clientId: process.env.IUV_CLIENT_ID,
clientSecret: process.env.IUV_CLIENT_SECRET,
},
],
});
export const { GET, POST } = handlers;Then use the sign in function in your components:
// components/sign-in-button.tsx
import { signIn } from "@/app/api/auth/[...nextauth]/route";
export function SignInButton() {
return (
<form action={async () => {
"use server";
await signIn("iuv");
}}>
<button type="submit">Sign in with iuv.one</button>
</form>
);
}For React SPAs, you can use oidc-client-ts or react-oidc-context:
// src/auth/config.ts
import { UserManager, WebStorageStateStore } from "oidc-client-ts";
export const userManager = new UserManager({
authority: "https://iuv.one",
client_id: "YOUR_CLIENT_ID",
redirect_uri: "https://yourapp.com/auth/callback",
response_type: "code",
scope: "openid profile email",
userStore: new WebStorageStateStore({ store: window.localStorage }),
});
// Login
export const login = () => userManager.signinRedirect();
// Handle callback
export const handleCallback = () => userManager.signinRedirectCallback();
// Get user
export const getUser = () => userManager.getUser();
// Logout
export const logout = () => userManager.signoutRedirect();With react-oidc-context:
// src/App.tsx
import { AuthProvider } from "react-oidc-context";
const oidcConfig = {
authority: "https://iuv.one",
client_id: "YOUR_CLIENT_ID",
redirect_uri: "https://yourapp.com/auth/callback",
scope: "openid profile email",
};
function App() {
return (
<AuthProvider {...oidcConfig}>
<YourApp />
</AuthProvider>
);
}
// In a component
import { useAuth } from "react-oidc-context";
function Profile() {
const auth = useAuth();
if (auth.isLoading) return <div>Loading...</div>;
if (auth.error) return <div>Error: {auth.error.message}</div>;
if (auth.isAuthenticated) {
return (
<div>
<p>Hello {auth.user?.profile.name}</p>
<button onClick={() => auth.removeUser()}>Sign out</button>
</div>
);
}
return <button onClick={() => auth.signinRedirect()}>Sign in</button>;
}| Endpoint | URL | Description |
|---|---|---|
| Discovery | /.well-known/openid-configuration | OIDC discovery document |
| Authorize | /oauth/authorize | Authorization page |
| Token | /api/oauth/token | Token endpoint |
| UserInfo | /api/oauth/userinfo | User info endpoint |
| JWKS | /api/oauth/jwks | JSON Web Key Set |
| Revoke | /api/oauth/revoke | Token revocation |
For detailed API documentation, see the API Reference.
| Scope | Claims | Description |
|---|---|---|
openid | sub, iss, aud, exp, iat | Required for OIDC. Returns an ID token. |
profile | name, picture | Basic profile information |
email | email, email_verified | User's email address |
offline_access | - | Returns a refresh token for offline access |
If you have questions or run into issues, check out these resources: