# 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 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 io.jsonwebtoken jjwt-api 0.11.5 ``` ### 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**: * **Documentation**: * **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)* --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://oten.gitbook.io/identity-support/integration/prerequisites.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.