UnityID - Spring Boot Identity Provider

A comprehensive Spring Boot-based Identity Provider (IdP) that supports email/password authentication with mandatory email verification and LinkedIn OAuth integration. The system issues JWT access tokens and refresh tokens signed with a private key.

Live Demo

Unity Auth Widget - Interactive Demo

Experience the UnityID authentication system with our interactive widget demo:

• Unity Auth Widget Demo: Complete authentication integration showcase
  • Live Demo: https://storage.googleapis.com/unity-auth-widget/index.html
  • Widget CSS: https://storage.googleapis.com/unity-auth-widget/unity-auth-widget.css
  • Widget JS: https://storage.googleapis.com/unity-auth-widget/unity-auth-widget.js
  • Features: Email/password registration, LinkedIn OAuth, JWT token management, real-time status updates

Quick Start with Demo

1. Run the UnityID Backend:

   mvn spring-boot:run

2. Try the Interactive Widget Demo:

   • Open: https://storage.googleapis.com/unity-auth-widget/index.html
   • Test email/password registration and login
   • Try LinkedIn OAuth integration
   • See real-time authentication status updates

3. Access the Applications:

   • Unity Auth Widget Demo: https://storage.googleapis.com/unity-auth-widget/index.html (Primary Demo)
   • UnityID Backend API: http://localhost:8080

The Unity Auth Widget demo provides the quickest way to experience UnityID's authentication capabilities with an interactive, real-time interface that showcases all authentication methods and token management.

Features

Authentication Methods

• Email + Password: Traditional authentication with mandatory email verification
• LinkedIn OAuth: Social login integration with LinkedIn
• JWT Tokens: Secure access and refresh token system
• Email Verification: Mandatory email verification for local registrations

Security Features

• JWT access tokens signed with RSA-256 (asymmetric key cryptography)
• JWT refresh tokens signed with HMAC-SHA256 (symmetric key cryptography)
• Public key distribution via JWKS endpoint for token verification
• Refresh token rotation for enhanced security
• Password encryption using BCrypt
• CORS support for frontend integration
• Role-based access control (USER, ADMIN)

API Endpoints

Authentication Endpoints

Register New User

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Verify Email

GET /api/auth/verify-email?token=<verification-token>

Resend Verification Email

POST /api/auth/resend-verification?email=user@example.com

Refresh Token

POST /api/auth/refresh
Content-Type: application/json

{
  "refreshToken": "<refresh-token>"
}

Logout

POST /api/auth/logout
Content-Type: application/json

{
  "refreshToken": "<refresh-token>"
}

Validate Token

GET /api/auth/validate-token
Authorization: Bearer <access-token>

JSON Web Key Set (JWKS)

GET /.well-known/jwks.json

Alternative endpoint:

GET /api/auth/jwks

Returns the public keys used to verify JWT tokens. This endpoint is used by external applications to validate tokens issued by UnityID.

User Endpoints

Get Current User Profile

GET /api/user/me
Authorization: Bearer <access-token>

Get User Profile (Admin Only)

GET /api/user/profile/{userId}
Authorization: Bearer <access-token>

OAuth2 Endpoints

LinkedIn Login

GET /oauth2/authorization/linkedin

Configuration

Environment Variables

The application uses environment variables for configuration. Copy .env.example to .env and update the values:

cp .env.example .env

Required Environment Variables

Application Configuration:

• APP_NAME: Application name (default: UnityID)
• SERVER_PORT: Server port (default: 5900)

Database Configuration:

• DATABASE_URL: Database connection URL
• DATABASE_USERNAME: Database username
• DATABASE_PASSWORD: Database password

JWT Configuration:

• JWT_SECRET: Secret key for JWT signing (use a strong, random key in production)
• JWT_ACCESS_TOKEN_EXPIRATION: Access token expiration time in milliseconds
• JWT_REFRESH_TOKEN_EXPIRATION: Refresh token expiration time in milliseconds

Email Configuration:

• EMAIL_HOST: SMTP server host
• EMAIL_PORT: SMTP server port
• EMAIL_USERNAME: Email username
• EMAIL_PASSWORD: Email password (use app password for Gmail)
• EMAIL_FROM: From email address
• EMAIL_VERIFICATION_URL: Email verification URL

LinkedIn OAuth Configuration:

• LINKEDIN_CLIENT_ID: LinkedIn OAuth client ID
• LINKEDIN_CLIENT_SECRET: LinkedIn OAuth client secret
• LINKEDIN_REDIRECT_URI: OAuth redirect URI

Application URLs:

• FRONTEND_URL: Frontend application URL

Logging Configuration:

• LOG_LEVEL_APP: Application log level
• LOG_LEVEL_SECURITY: Security log level
• LOG_LEVEL_OAUTH2: OAuth2 log level

For a complete list of all available environment variables, see the .env.example file.

Application Properties

Key configuration properties in application.properties:

# JWT Configuration
app.jwt.secret=mySecretKey123456789012345678901234567890123456789012345678901234567890
app.jwt.access-token-expiration=900000    # 15 minutes
app.jwt.refresh-token-expiration=86400000 # 24 hours

# Email Configuration
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=${EMAIL_USERNAME}
spring.mail.password=${EMAIL_PASSWORD}

# LinkedIn OAuth Configuration
spring.security.oauth2.client.registration.linkedin.client-id=${LINKEDIN_CLIENT_ID}
spring.security.oauth2.client.registration.linkedin.client-secret=${LINKEDIN_CLIENT_SECRET}

Running the Application

Prerequisites

• Java 24 or higher
• Maven 3.6+
• Gmail account with App Password (for email verification)
• LinkedIn Developer Account (for OAuth)

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd UnityID

2. Configure environment variables

   # Copy the example environment file
   cp .env.example .env
   
   # Edit the .env file with your actual values
   # Or export them directly:
   export EMAIL_USERNAME=your-email@gmail.com
   export EMAIL_PASSWORD=your-app-password
   export LINKEDIN_CLIENT_ID=your-linkedin-client-id
   export LINKEDIN_CLIENT_SECRET=your-linkedin-client-secret
   export JWT_SECRET=your-super-secret-jwt-key-here

3. Run the application

   mvn spring-boot:run

4. Access the application

   • Unity Auth Widget Demo: https://storage.googleapis.com/unity-auth-widget/index.html
   • API: http://localhost:8080
   • H2 Console: http://localhost:8080/h2-console
     • JDBC URL: jdbc:h2:mem:unityid
     • Username: sa
     • Password: password

Production Deployment

For production deployment, consider:

1. Database: Replace H2 with a production database (PostgreSQL, MySQL)
2. JWT Secret: Use a strong, randomly generated secret
3. HTTPS: Enable SSL/TLS encryption
4. Environment Variables: Use secure secret management
5. Logging: Configure appropriate logging levels

Token Structure

Access Token Claims

{
  "sub": "user@example.com",
  "userId": 1,
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "emailVerified": true,
  "provider": "LOCAL",
  "roles": ["ROLE_USER"],
  "iat": 1640995200,
  "exp": 1640996100
}

Refresh Token Claims

{
  "sub": "user@example.com",
  "userId": 1,
  "type": "refresh",
  "iat": 1640995200,
  "exp": 1641081600
}

Error Responses

All API endpoints return standardized error responses:

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message",
  "data": null
}

Security Considerations

1. Token Storage: Store tokens securely on the client side
2. HTTPS: Always use HTTPS in production
3. Token Expiration: Access tokens expire in 15 minutes by default
4. Refresh Token Rotation: Refresh tokens are rotated on each use
5. Email Verification: Email verification is mandatory for local registrations
6. Password Policy: Implement strong password requirements

Development

Project Structure

src/main/java/com/IA/UnityID/
├── config/          # Configuration classes
├── controller/      # REST controllers
├── dto/            # Data Transfer Objects
├── entity/         # JPA entities
├── exception/      # Exception handlers
├── repository/     # Data repositories
├── security/       # Security components
└── service/        # Business logic services

Adding New OAuth Providers

To add a new OAuth provider:

1. Create a new OAuth2UserInfo implementation
2. Update OAuth2UserInfoFactory
3. Add provider configuration in application.properties
4. Update the AuthProvider enum in the User entity

Testing

Run the test suite:

mvn test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License.