> For the complete documentation index, see [llms.txt](https://oten.gitbook.io/identity-support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://oten.gitbook.io/identity-support/integration/prerequisites.md).

# 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](broken://pages/iMMrTD1lQOMbxxvheKAz) 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](https://gitlab.silvertiger.tech/documents/idp/-/blob/main/developer-guide/pkce-implementation-guide.md) 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

```javascript
// ❌ 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

```javascript
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)

```bash
# 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

```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

```javascript
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

```json
{
  "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](https://admin.oten.com)
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

```json
{
  "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

```bash
npm install jsonwebtoken
# or
npm install jose
```

### Python

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

### Java

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

### C#/.NET

```bash
dotnet add package System.IdentityModel.Tokens.Jwt
```

### Go

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

## Development Environment Setup

### Environment Variables

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

```bash
# 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](https://tools.ietf.org/html/rfc7519)
* [JAR RFC 9101](https://tools.ietf.org/html/rfc9101)
* [JWKS RFC 7517](https://tools.ietf.org/html/rfc7517)

### Support Channels

* **Email**: <support@oten.live>
* **Documentation**: <https://oten.gitbook.io/idp-support/>&#x20;
* **Status Page**: [status.oten.com](https://status.oten.com) *(Coming Soon)*

***

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