User Journey Guide

This document outlines the complete journey for Administrators and End-Users interacting with the Identity Server. It covers organization onboarding, user management, and the Single Sign-On (SSO) experience.

Part 1: Administrator Journey

Prerequisites

• System Admin Token: Management API requests require a standard JWT Bearer token (Authorization: Bearer <admin-jwt-token>) obtained by calling the login endpoint.
• Base URL: https://ids.fabrixly.com

Step 1: Onboarding an Organization

Actor: System Administrator Goal: Create a new tenant (Organization) in the system.

1. Obtain System Admin JWT:
   • Outcome: Copy the token from the response JSON and use it as <admin-jwt-token>.
2. Create Organization:
   • Endpoint: POST /api/organizations
   • Headers: Authorization: Bearer <admin-jwt-token>
   • Outcome: Returns the created Organization object, including its id (e.g., org-uuid).

cURL:

curl -X POST https://ids.fabrixly.com/api/organizations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{"name": "Acme Corp", "domain": "acme.com"}'

Payload:

{
  "name": "Acme Corp",
  "domain": "acme.com"
}

Action: Log in using System Administrator credentials.

curl -X POST https://ids.fabrixly.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "your-admin-password"}'

Step 2: Onboarding an Organization Administrator

Actor: System Administrator Goal: Create the first administrator for the new organization.

1. Create Org Admin User:
   • Endpoint: POST /api/users
   • Headers: Authorization: Bearer <admin-jwt-token> (System Admin can create users anywhere)
   • Outcome: Returns the created User object, including id (e.g., org-admin-uuid).

cURL:

curl -X POST https://ids.fabrixly.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{
    "email": "admin@acme.com",
    "password": "securePassword123",
    "firstName": "Alice",
    "lastName": "Admin",
    "organizationId": "org-uuid",
    "roleNames": ["ORG_ADMIN"]
  }'

Payload:

{
  "email": "admin@acme.com",
  "password": "securePassword123",
  "firstName": "Alice",
  "lastName": "Admin",
  "organizationId": "org-uuid",
  "roleNames": ["ORG_ADMIN"]
}

Step 3: Setting up Roles and Teams

Actor: Organization Administrator (org-admin-uuid) Goal: Define structure for the organization.

1. Create a Team:
   • Endpoint: POST /api/teams
2. Create a Role (if custom roles are needed beyond ORG_ADMIN/MEMBER):
   • Endpoint: POST /api/roles

cURL:

curl -X POST https://ids.fabrixly.com/api/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{"name": "DEVELOPER", "organizationId": "org-uuid"}'

cURL:

curl -X POST https://ids.fabrixly.com/api/teams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{"name": "Engineering", "organizationId": "org-uuid"}'

Step 4: Onboarding End-Users

Actor: Organization Administrator Goal: Add regular employees to the organization.

1. Create User:
   • Endpoint: POST /api/users

cURL:

curl -X POST https://ids.fabrixly.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{
    "email": "bob@acme.com",
    "password": "password123",
    "firstName": "Bob",
    "lastName": "Builder",
    "organizationId": "org-uuid",
    "roleNames": ["DEVELOPER"],
    "teamNames": ["Engineering"]
  }'

Step 5: Registering an OIDC Client (Application)

Actor: Organization Administrator Goal: Connect an application (e.g., "Acme Dashboard") to the Identity Server.

1. Register Client:
   • Endpoint: POST /api/clients
   • Outcome: Returns client_id and client_secret. Save these!

cURL:

curl -X POST https://ids.fabrixly.com/api/clients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt-token>" \
  -d '{
    "client_name": "Acme Dashboard",
    "redirect_uris": ["https://ids.fabrixly.com/callback"],
    "requires_consent": false
  }'

Payload:

{
  "client_name": "Acme Dashboard",
  "redirect_uris": ["https://ids.fabrixly.com/callback"],
  "requires_consent": false
}

Part 2: End-User Journey (SSO Flow)

Scenario: Logging into "Acme Dashboard"

Actor: Bob (bob@acme.com) Goal: Access the dashboard using his Acme Corp credentials.

Step 1: Initiate Login

1. User Action: Bob visits the Acme Dashboard (e.g., https://ids.fabrixly.com).
2. User Action: Clicks the "Login with SSO" button.
3. System Action: The Dashboard redirects Bob's browser to the Identity Server's authorization endpoint.
   • URL: https://ids.fabrixly.com/auth?client_id=...&response_type=code&scope=openid...

Step 2: Authentication (Login Page)

1. Navigation: Bob is now on the Identity Server's Login Page (https://ids.fabrixly.com/interaction/.../login).
2. User Action: Bob enters his email (bob@acme.com) and password (password123).
3. User Action: Clicks "Sign In".
   • Alternative: If he doesn't have an account and registration is enabled, he could click "Create an account" here.

Step 3: Consent (Optional)

• Note: If the client was registered with requires_consent: false (as done in Step 5 above), this step is skipped.

1. Navigation: If consent is required, Bob sees the Consent Page.
   • "Acme Dashboard wants to access your profile."
2. User Action: Bob clicks "Allow".

Step 4: Redirect & Token Exchange

1. System Action: The Identity Server redirects Bob back to the Dashboard's redirect_uri (https://ids.fabrixly.com/callback) with an authorization code.
2. System Action: The Dashboard backend automatically exchanges this code for an Access Token and ID Token by calling the Identity Server's /token endpoint.
3. System Action: The Dashboard verifies the ID Token.

Step 5: Access Granted

1. Navigation: Bob is redirected to the Dashboard's Home/Profile Page.
2. Outcome: Bob sees "Welcome, Bob!" and his profile details (fetched from the Identity Server).
3. Session: Bob is now logged in. If he visits another app using the same Identity Server, he won't need to enter his password again (SSO).