# OpenID Connect flows with Humand as Identity Provider (PoC)

This article is a draft diagram that shows the possible OpenID Connect flow integrated into Humand.

Notes: https://chatgpt.com/share/67dc10a7-8e98-800d-b8df-eec56c2d37e9


## General process overview
```mermaid
sequenceDiagram
  actor User
  participant Humand as Humand
  participant Ext as External App

  Note over User,Humand: User already logged in to Humand
  User->>Humand: Click link to open Client App
  Humand->>Ext: Redirect to client with Authorization request (prompt=none)
  Ext->>Humand: Redirect to /authorize endpoint with prompt=none
  Humand-->>Humand: Verify session, generate auth code
  Humand->>Ext: Redirect to callback URL with auth_code
  Ext->>Humand: Exchange auth_code for ID token (POST /token)
  Humand-->>Ext: Return ID token (JWT)
  Ext-->>Ext: Validate token & authenticate user
  Ext->>User: Show authenticated session
```

## New endpoints for OAuth / OpenId Connect flows

### Authorization request
```http request
GET /api/v1/auth/oidc/authorize/:serviceProviderId?
    client_id={client_id}&
    response_type=code&
    redirect_uri={client_redirect_uri}&
    scope=openid profile email&
    state={state}
Authorization: Bearer <user bearer token>

HTTP/2 302 Found
Content-Type: application/json
Location: {client_redirect_uri}?code={authorization_code}&state={state}
```

### Request to the service provider (client app)
```http request
GET {client_redirect_uri}?code={authorization_code}&state={state}
```

### Token exchange (made by the client app to Humand)
```http request
POST /api/v1/auth/oidc/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&
client_secret={client_secret}&
grant_type=authorization_code&
code={authorization_code}&
redirect_uri={client_redirect_uri}

HTTP/2 200 OK
Content-Type: application/json
{
  "access_token": "<access_token>",
  "id_token": "<id_token>",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

## Optional endpoints for OIDC discovery (for protocol completion)
```http request
GET /api/v1/auth/oidc/.well-known/jwks.json
```

```http request
GET /api/v1/auth/oidc/.well-known/openid-configuration
```

# Additional considerations for implementation
- Decide what user info to add to the JWT token.
- Decide if we are going to provide refresh tokens.
- We need to store the possible service providers (clients) for the instance in the Humand database.
- We need to generate and keep the client_id and client_secret for each service provider.
- We need to think further the interactions between our front and api.
- We need to decide if, for complete implementation, we provide the workflow for SSO with Humand using OIDC, which involves more than what's required for 
  Humand initiated logins to other apps.
- We need to decide if we want to implement the OIDC discovery endpoints for protocol completion (strongly recommented that we do).
-