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 support@oten.dev 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

Go to Oten Admin Portal
Log in with your Oten credentials
Navigate to "Applications" section

Step 2: Create New Application

Click "Create New Application"
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

Support Channels

Email: support@oten.live
Documentation: https://oten.gitbook.io/idp-support/
Status Page: status.oten.com (Coming Soon)

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

PreviousIntegration flow overview NextDiscovery Configuration

Last updated 3 months ago