Overview

This backend demonstrates how a third-party application can:

1. Exchange an authorization code for access and refresh tokens.

2. Validate and use access tokens to call protected resources using OAuth2 Introspection.

It serves as a reference implementation for integrating Single Sign-On (SSO) or OAuth2-based authentication with any third-party service.

Folder Structure Overview

Backend/
├── Controllers/
│   ├── TokenController.cs              # Exchanges authorization code for tokens
│   └── ProtectedResourceController.cs  # Example protected API endpoint (requires valid access token)
│
├── Models/
│   ├── TokenErrorResponse.cs           # Represents error response from token endpoint
│   ├── TokenRequest.cs                 # Request model for token exchange
│   └── TokenResponse.cs                # Response model for token exchange
│
├── Utilities/
│   └── SecretManagerHelper.cs          # Fetches client credentials securely from AWS Secrets Manager
│
├── appsettings.json                    
├── appsettings.Development.json        # Dev-specific settings
├── appsettings.sandbox.json            # Sandbox/testing environment config
├── Backend.http                        
└── Program.cs                          # Application entry point and pipeline setup

Authentication Flow

1️. Frontend → Authorization Server

The frontend application redirects users to the SSO server for login.

2️. Authorization Server → Frontend Callback

After successful login, the server redirects back with:

https://localhost:4200/validate?code={authorization_code}&state={optional_state}

3️. Frontend → TokenController

The frontend sends this code to your backend’s api/token endpoint:

POST /api/token
Content-Type: application/json

{
  "grantType": "authorization_code",
  "code": "abc123",
  "redirectUri": "https://yourapp.com/callback"
}

4. Backend → Authorization Server

The backend securely exchanges the code for tokens using:

Client ID

Client Secret

Redirect URI

5. Response

If successful, returns:

{
  "access_token": "xyz",
  "expires_in": 3600,
  "refresh_token": "r123"
}

Token Validation (OAuth2 Introspection)

The backend uses OAuth2 Introspection middleware to validate tokens automatically.

When a request hits a protected endpoint (e.g., [Authorize]), the middleware:

1. Sends the token to the introspection endpoint of your Auth Server.

2. Verifies if the token is valid, active, and not expired.

3. Rejects invalid tokens with HTTP 401 Unauthorized.

Configured inProgram.cs:

builder.Services.AddAuthentication(OAuth2IntrospectionDefaults.AuthenticationScheme)
    .AddOAuth2Introspection(options =>
    {
        options.Authority = builder.Configuration["AuthServer"];
        options.ClientId = clientId;
        options.ClientSecret = clientSecret;
    });

Token API (/api/token)

The Token API exchanges an authorization code (or refresh token) for an access token and refresh token.
It acts as a secure bridge between your myzPAX Authorization Server and the third-party sample integration app.

Request Body

{
  "grantType": "authorization_code",
  "code": "abcd1234",
  "redirectUri": "https://localhost:4200/validate",
  "refreshToken": null
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "expires_in": 3600,
  "refresh_token": "def456ghi...",
  "token_type": "Bearer"
}

Fields