Prerequisites

Before you start integrating Oten IDP into your application, make sure you have everything you need.

Important: Authorization requirements depend on your client type:

• Confidential Clients (Server-side): JAR (JWT-Secured Authorization Request) is REQUIRED

• Public Clients (SPAs/Mobile): PKCE is REQUIRED, JAR is FORBIDDEN

Legacy Application Support: If your confidential client application cannot implement JAR due to technical constraints, contact [email protected] to discuss alternative solutions.

📖 New to Oten IDP? Start with the Integration Flow Overview to understand the complete process.

🎯 What You'll Need

1. Oten Account Access

• Access to Oten Developer Portal

• Permissions to create new applications

• Understanding of your organization's SSO policies

Or easily contact support to get your credentials.

2. Development Environment

• Development environment set up

• Access to your application's codebase

• Ability to deploy and test changes

• HTTPS enabled (required for production)

3. JAR (JWT-Secured Authorization Request) Setup

For Confidential Clients (Server-side applications):

• Ed25519 key pair generation capability

• JWT library for your programming language

• JWKS endpoint hosting capability

• Understanding of JWT signing process

For Public Clients (SPAs/Mobile apps):

• JAR may not be required (see PKCE-only flow)

• Contact support to configure public client without JAR requirement

4. Technical Knowledge

• Basic understanding of web applications

• Familiarity with HTTP requests and responses

• Understanding of JSON and URLs

• Knowledge of JWT (JSON Web Tokens)

• Knowledge of your chosen programming language

5. Public Client Requirements (SPAs & Mobile Apps)

• PKCE Implementation: Required for all public clients

• Secure random number generation capability

• Session/secure storage for temporary values

• Understanding of authorization code flow

📖 Public Client? See the comprehensive PKCE Implementation Guide for SPAs and native mobile applications.

🔒 JAR Requirement

JAR for Different Client Types

Confidential Clients (Server-side applications):

• JAR is required for enhanced security

Public Clients (SPAs/Mobile apps):

• JAR may not be required if PKCE is properly implemented

• Contact support to configure public client settings

Why JAR is Recommended

For confidential clients, JAR provides enhanced security:

• Request Integrity: Authorization parameters cannot be tampered with

• Confidentiality: Sensitive parameters are protected

• Authentication: Requests are cryptographically signed

• Replay Protection: Using JWT standard claims (jti, exp)

JAR Implementation Requirements

// ❌ This will NOT work with Oten IDP
const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectURI}&response_type=code&scope=openid profile email&state=${state}`;

// ✅ This is the ONLY way that works with Oten IDP
const requestJWT = createSignedJWT({
  client_id: clientId,
  redirect_uri: redirectURI,
  response_type: 'code',
  scope: 'openid profile email',
  state: state,
  nonce: nonce,
  prompt: 'none',
  max_age: 1000
});

const authURL = `https://account.oten.com/v1/oauth/authorize?client_id=${clientId}&request=${requestJWT}`;

JAR Signing Methods

Oten IDP supports only two signing methods for JAR:

Method 1: HS256 (Client Secret) - Simpler

Uses your client secret to sign JAR requests.

Pros:

• ✅ Simple setup - no key generation needed

• ✅ Uses existing client secret

• ✅ Good for development and internal apps

Cons:

• ❌ Shared secret (less secure)

• ❌ Client secret must be protected

Method 2: EdDSA (Ed25519 Key Pair) - More Secure

Uses Ed25519 key pair for signing JAR requests.

Pros:

• ✅ Very secure - no shared secrets

• ✅ Industry standard for high security

• ✅ Recommended for production

Cons:

• ❌ More complex setup

• ❌ Key management required

Generate Ed25519 Key Pair for EdDSA

Using Node.js

const crypto = require('crypto');
const fs = require('fs');

// Generate Ed25519 key pair (for EdDSA signing)
const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
  publicKeyEncoding: {
    type: 'spki',
    format: 'pem'
  },
  privateKeyEncoding: {
    type: 'pkcs8',
    format: 'pem'
  }
});

// Save keys securely
fs.writeFileSync('jar-private-key.pem', privateKey);
fs.writeFileSync('jar-public-key.pem', publicKey);

console.log('Ed25519 JAR keys generated successfully!');
console.log('Register the public key with Oten IDP');

Using OpenSSL (Command Line)

# Generate Ed25519 private key
openssl genpkey -algorithm Ed25519 -out jar-private-key.pem

# Extract public key
openssl pkey -in jar-private-key.pem -pubout -out jar-public-key.pem

# View the public key (for registration)
openssl pkey -in jar-public-key.pem -pubin -text -noout

Using Python

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ed25519

# Generate Ed25519 private key
private_key = ed25519.Ed25519PrivateKey.generate()

# Get public key
public_key = private_key.public_key()

# Serialize private key
private_pem = private_key.private_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PrivateFormat.PKCS8,
    encryption_algorithm=serialization.NoEncryption()
)

# Serialize public key
public_pem = public_key.public_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PublicFormat.SubjectPublicKeyInfo
)

# Save keys
with open('jar-private-key.pem', 'wb') as f:
    f.write(private_pem)

with open('jar-public-key.pem', 'wb') as f:
    f.write(public_pem)

print("Ed25519 JAR keys generated successfully!")
print("Register the public key with Oten IDP")

🌐 JWKS Endpoint (Only for EdDSA)

Note: JWKS endpoint is only required for EdDSA signing. HS256 uses client secret and doesn't need JWKS.

For EdDSA (Ed25519) - JWKS Required

const crypto = require('crypto');
const fs = require('fs');

function createJWKS() {
  const publicKeyPem = fs.readFileSync('jar-public-key.pem', 'utf8');
  const publicKey = crypto.createPublicKey(publicKeyPem);

  // Convert Ed25519 public key to JWK format
  const jwk = publicKey.export({ format: 'jwk' });

  return {
    keys: [{
      ...jwk,
      kid: 'jar-key-1', // Key ID - must be unique
      use: 'sig',       // Signature use
      alg: 'EdDSA'      // Algorithm for Ed25519
    }]
  };
}

// Host this at /.well-known/jwks.json
app.get('/.well-known/jwks.json', (req, res) => {
  res.json(createJWKS());
});

Example JWKS Response for EdDSA

{
  "keys": [
    {
      "kty": "OKP",
      "use": "sig",
      "kid": "jar-key-1",
      "alg": "EdDSA",
      "crv": "Ed25519",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
    }
  ]
}

For HS256 (Client Secret) - No JWKS Needed

When using HS256 with client secret, you don't need a JWKS endpoint because:

• Oten already knows your client secret

• HS256 uses symmetric signing (same secret for sign and verify)

• No public key distribution needed

🏢 Register Your Application

🆘 IMPORTANT: Now, for easy setup, contact support to register your application because the developer portal is not ready yet.

Step 1: Access Developer Portal

1. Go to Oten Admin Portal

2. Log in with your Oten credentials

3. Navigate to "Applications" section

Step 2: Create New Application

1. Click "Create New Application"

2. Fill in application details:

   • Application Name: Your app's display name

   • Description: Brief description of your application

   • Application Type: Web Application, SPA, or Mobile

   • Redirect URIs: Where users return after login

   • JWKS URI: Your JWKS endpoint URL (e.g., https://yourapp.com/.well-known/jwks.json)

Step 3: Configure JAR Settings

{
  "name": "My Application",
  "type": "web_application",
  "redirect_uris": [
    "https://myapp.com/callback",
    "https://localhost:3000/callback"
  ],
  "jwks_uri": "https://myapp.com/.well-known/jwks.json",
  "request_object_signing_alg": "RS256",
  "require_signed_request_object": true,
  "scopes": ["openid", "profile", "email"]
}

Step 4: Save Credentials

After creating the application, save these important values:

• Client ID: Public identifier for your application

• JWKS URI: Your public key endpoint (must be accessible)

• Endpoints: Authorization and token URLs

Understanding Your Credentials

Client ID

Example: abc123-def456-ghi789

• Public identifier for your application

• Safe to include in client-side code

• Used in JAR and token requests

JWKS URI

Example: https://yourapp.com/.well-known/jwks.json

• Public endpoint hosting your signing keys

• Must be HTTPS in production

• Must return valid JWKS format

Endpoints

You'll need these Oten endpoints:

Authorization URL: https://account.oten.com/v1/oauth/authorize
Token URL: https://account.oten.com/v1/oauth/token
UserInfo URL: https://account.oten.com/v1/oauth/userinfo
JWKS URL: https://account.oten.com/.well-known/jwks.json

📚 Choose JWT Library

Select a JWT library that supports RS256 signing:

JavaScript/Node.js

npm install jsonwebtoken
# or
npm install jose

Python

pip install pyjwt[crypto]
# or
pip install python-jose[cryptography]

Java

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.11.5</version>
</dependency>

C#/.NET

dotnet add package System.IdentityModel.Tokens.Jwt

Go

go get github.com/golang-jwt/jwt/v5

Development Environment Setup

Environment Variables

Create a .env file (never commit to version control):

# Oten OAuth Configuration
OTEN_CLIENT_ID=your_client_id_here
OTEN_REDIRECT_URI=https://localhost:3000/callback

# JAR Configuration
JAR_PRIVATE_KEY_PATH=./jar-private-key.pem
JAR_KEY_ID=jar-key-1
JWKS_URI=https://localhost:3000/.well-known/jwks.json

# Oten Endpoints
OTEN_AUTH_URL=https://account.oten.com/v1/oauth/authorize
OTEN_TOKEN_URL=https://account.oten.com/v1/oauth/token

Testing Checklist

Before proceeding, verify:

• Application registered in Oten with JWKS URI

• RSA key pair generated and stored securely

• JWKS endpoint accessible and returning valid format

• JWT library installed and configured

• HTTPS working (for production)

• Environment variables set up

Getting Help

Documentation

• JWT RFC 7519

• JAR RFC 9101

• JWKS RFC 7517

Support Channels

• Email: [email protected]

• Documentation: docs.oten.com (Coming Soon)

• Status Page: status.oten.com (Coming Soon)

---

Ready to start coding? Let's begin with Step 1: Choose OAuth Library