Product Onboarding to Utilize Cross App SSO

This document outlines the steps required for a product to onboard and utilize the Cross Application Single Sign-On (SSO) feature provided by Harmony Auth. Cross App SSO allows users to seamlessly authenticate across multiple applications within the same ecosystem without needing to log in separately for each application.

Onboarding Steps

1. Create Cognito User Pool App Client

This is needed for system to system (s2s) authentication from Harmony Auth to your product so Harmony Auth can invoke your product's /authorize endpoint. Provide Platform Services with the client credentials so we can generate a token before invoking your product's /authorize endpoint.

2. Implement /authorize endpoint

This endpoint will be called by Harmony Auth to authorize the authenticated user for your specific product. Your product must implement an /authorize endpoint with the following structure:

Endpoint Specification

• Method: POST
• Headers:
  • Content-Type: application/x-www-form-urlencoded
  • Authorization: Bearer <access_token>

Request Body

The request body should be form URL-encoded and contain the fields defined in ProductSpecificAuthorizeRequest

Response Format

Your endpoint should return a JSON response containing the fields defined in ProductSpecificAuthorizeResponse:

Example Request

POST /authorize
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <access_token>

userId=user123&userEmail=user123@districtDomain.com&tenantId=tenant123
Copy

Example Response

{
	"isAuthorized": true,
	"customClaims": {
		"idToken": {
			"role": ["admin", "user"],
			"department": ["sales"]
		},
		"accessToken": {
			"permissions": ["read", "write"]
		}
	}
}
Copy

3. Provide Endpoint Information to Platform Services

Share the following details with Platform Services to complete the onboarding process:

• The URL of your /authorize endpoint
• The Cognito User Pool App Client ID and Secret created in step 1

4. Testing and Validation

Once the above steps are completed, Platform Services will test the integration to ensure that:

• The /authorize endpoint is reachable and responds correctly
• The token exchange and authorization flow work as expected
• The response format matches the expected ProductSpecificAuthorizeResponse interface