# SSO Integration

Single Sign-On integration between Monetarie PIX and external identity providers, including the Monetarie Backoffice SSO hub.

## Prerequisites

- Understanding of JWT token format and validation
- Access to the identity provider's signing secret
- Network connectivity between services

## SSO Architecture

```mermaid
graph LR
    USER[User] --> SSO[Monetarie Backoffice<br/>SSO Hub]
    SSO -->|JWT token| PIX[Monetarie PIX]
    CORE[Core Banking] -->|Guardian JWT| PIX
```

## Token Types

### Core Banking Guardian Token

| Field | Value | Requirement |
|-------|-------|-------------|
| `iss` | `"monetarie"` | Accepted without target_system check |
| `sub` | User ID | Required |
| `exp` | Expiration timestamp | Required |
| Algorithm | HS256 | Signed with GUARDIAN_SECRET_KEY |

### SSO Token

| Field | Value | Requirement |
|-------|-------|-------------|
| `iss` | `"monetarie-sso"` | Must include target_system |
| `target_system` | `"pix"` | Required for SSO tokens |
| `sub` | User ID | Required |
| `exp` | Expiration timestamp | Required |
| Algorithm | HS256 | Signed with shared secret |

## JWT Secret Configuration

The secret fallback chain for token verification:

```
JWT_SECRET  -->  GUARDIAN_SECRET_KEY  -->  SECRET_KEY_BASE
```

In Kubernetes:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: monetarie-shared-jwt-secret
  namespace: pix
type: Opaque
stringData:
  jwt-secret: "same-value-as-core-GUARDIAN_SECRET_KEY"
```

## Auth Modules

### JWTAuth (Settlement Service)

`Shared.Auth.JwtAuth` validates JWT tokens:

1. Extract token from `pix_session` HttpOnly cookie
2. Verify signature against JWT secret chain
3. Check token not blacklisted (Redis)
4. Set `conn.assigns.current_user`

### SsoAuth (Settlement Service)

`Shared.Auth.SsoAuth` handles SSO tokens:

1. Extract token from `Authorization: Bearer` header
2. Verify `iss` field:
   - `"monetarie"` (Core Guardian): accepted, skip target_system check
   - `"monetarie-sso"`: require `target_system: "pix"`
3. Secret fallback: JWT_SECRET -> GUARDIAN_SECRET_KEY -> SECRET_KEY_BASE

### Authenticate (Dict Service)

`DictServiceWeb.Plugs.Authenticate` validates tokens for Dict endpoints:

1. Check HttpOnly cookie or Authorization header
2. Verify against JWT secret chain
3. Check token blacklist

## RBAC with SSO

Core Banking Guardian tokens bypass RBAC checks (SSO passthrough). This allows Core Banking to make API calls without needing PIX-specific role assignments.

For SSO tokens, RBAC is enforced normally via `RequirePermission` plug.

## Local Development

```bash
# Use Core's dev secret for cross-service testing
export JWT_SECRET="dev-only-secret-key-not-for-production"
```

## Token Blacklisting

On logout from any auth module, the token is blacklisted in Redis:

```
SET blacklist:{jti} 1 EX {remaining_ttl}
```

This is checked in both `JWTAuth` and `Authenticate` plugs.

## Expected Outcome

After configuring SSO:

- Core Banking Guardian tokens accepted by PIX without target_system
- SSO tokens validated with target_system check
- JWT secret shared between Core and PIX
- Token blacklist active on logout across all auth modules