Integrating Applications with GuardAxion SSO Portal

Overview

This guide walks you through integrating your applications with the SSO Portal using OAuth 2.0 and OpenID Connect.

Prerequisites

Admin access to SSO Portal
Application with OAuth 2.0 support
Basic understanding of OAuth flows

Step 1: Create Application in SSO Portal

Navigate to Application Management

Log in to SSO Portal as administrator
Click Admin in top navigation
Select Applications

Add New Application

Click Add Application button
Fill in application details:
- Name: Your application name
- Description: Purpose of the application
- Redirect URI: Your app's callback URL (e.g., https://myapp.com/callback)
- Logout URI: Post-logout redirect URL (optional)
Click Create Application

Note Your Credentials

After creation, you'll receive:

Client ID: Public application identifier
App Secret: Secret key for token validation
JWT Secret: Used for SSO token signing

Important: Store these securely! The App Secret is shown only once.

Step 2: Configure Your Application

OAuth 2.0 Endpoints

Authorization: https://sso.platformaxion.com/oauth/authorize
Token: https://sso.platformaxion.com/oauth/token
UserInfo: https://sso.platformaxion.com/oauth/userinfo

Integration Options

Option 1: Direct OAuth Integration

Authorization Request:

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=openid profile email&
  state=RANDOM_STATE

Token Exchange:

curl -X POST https://sso.platformaxion.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_here",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Option 2: Using SSO Client Library

PHP Example:

require 'sso-client-library/sso-client.php';

$sso = new SSOClient([
    'client_id' => 'your_client_id',
    'app_secret' => 'your_app_secret',
    'sso_url' => 'https://sso.platformaxion.com',
    'redirect_uri' => 'https://yourapp.com/callback'
]);

// Start authentication
if (!$sso->isAuthenticated()) {
    $sso->authenticate();
}

// Get user info
$user = $sso->getUserInfo();

Step 3: Implement SSO Token Validation

Validate JWT Tokens

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$token = $_GET['sso_token'] ?? '';
$appSecret = 'YOUR_APP_SECRET'; // From SSO Portal

try {
    $decoded = JWT::decode($token, new Key($appSecret, 'HS256'));
    
    // Access user data
    $userId = $decoded->sub;
    $email = $decoded->email;
    $name = $decoded->name;
    $tenant = $decoded->tenant;
    
    // Create session
    $_SESSION['user_id'] = $userId;
    $_SESSION['email'] = $email;
    
} catch (Exception $e) {
    // Token invalid
    header('Location: https://sso.platformaxion.com/login.php');
}

Step 4: Test Integration

Testing Checklist

[ ] Click "Launch" from SSO Portal dashboard
[ ] Verify redirect to your application
[ ] Confirm user logged in automatically
[ ] Check user data received correctly
[ ] Test logout flow
[ ] Verify token refresh works

Common Issues

Error: "Invalid redirect_uri"

Ensure redirect URI in your app matches exactly what's configured in SSO Portal
Include protocol (https://) and full path

Error: "Invalid client credentials"

Verify Client ID and Client Secret are correct
Check for extra spaces or hidden characters

Error: "Token validation failed"

Use the App Secret (not JWT Secret) for validation
Ensure HS256 algorithm is used
Check token hasn't expired

Step 5: Export Integration Config

Download Configuration

In Applications list, click View on your app
Click Export Integration Config
Save JSON file with all configuration

JSON Configuration Format

{
  "application_name": "My App",
  "client_id": "app_123abc",
  "app_secret": "secret_here",
  "endpoints": {
    "authorize": "https://sso.platformaxion.com/oauth/authorize",
    "token": "https://sso.platformaxion.com/oauth/token",
    "userinfo": "https://sso.platformaxion.com/oauth/userinfo"
  },
  "redirect_uri": "https://myapp.com/callback"
}

Production Deployment

Security Best Practices

Always use HTTPS in production
Store secrets in environment variables
Implement CSRF protection
Validate state parameter
Use short-lived access tokens
Implement token refresh
Enable MFA requirements

Performance Tips

Cache user info appropriately
Implement session management
Use refresh tokens instead of re-authenticating
Monitor authentication failures

Support

If you need help integrating:

Review the SSO Client Library examples
Check audit logs for failed authentication attempts
Contact your SSO Portal administrator
Submit a support ticket with integration details

How to Integrate Applications with SSO