# OCPP Authentication Configuration Guide

For CPO/CSMS operators configuring charger authentication behavior.

---

## Note on Product-Specific Settings

This guide covers standard OCPP 1.6 configuration settings. When troubleshooting RFID authorization use cases, also consider vendor-specific settings such as [FreeVendMode](ocpp-metervalues.md) that may affect authorization behavior.

---

## Common Configuration Settings affecting authorization

| Setting | Purpose |
|---|---|
| **LocalAuthorizeOffline** | Can the charger authenticate users locally when offline? (default: `true`) |
| **LocalAuthListEnabled** | Should the charger maintain a local list of approved users? (default: `true`|
| **AuthorizationCacheEnabled** | Should the charger remember server responses? (default: `false`) |
| **LocalPreAuthorize** | Should the charger start charging immediately if user is in local cache? (default: `false`) |
| **ConnectionTimeOut** | How long to wait for EV driver to physically plug cable after authorization? (default: 300 seconds) |
| **AuthorizationTimeout** | How long to wait for CSMS response when a UID is sent for authorization? (default: 20 seconds) |
| **AllowOfflineTxForUnknownId** | When offline, allow any RFID token to be used to start charging (default: `false`)|

---

## Authentication Priority

When a charger authenticates a user, it checks sources in this order:

**NOTE:** Any use of `Cst_FreeVendActive = True` will override all below and allow all users to charge without authentication.

```{figure} images/Auth-Flow.png
:align: center
:name: auth_flow

Image 1: Authorization Flow
```





**Key rule:** If a user is on the Local List, the charger never stores them separately in cache. Local List is always checked first.

---

## Detailed Parameter Descriptions

### ConnectionTimeOut (Default: 300 seconds)
**When it matters:** During the authorization flow, after a user's RFID card is tapped and authorization succeeds.

**What happens:** 
1. User taps RFID card → Authorization request sent to CSMS
2. CSMS approves → Charger enters "Preparing" state and starts counting down
3. **ConnectionTimeOut timer starts (300 seconds = 5 minutes)**
4. Driver must physically plug the cable into the car within this window
5. If cable not connected within 300 seconds → Charger automatically cancels the transaction and returns to "Available"

**Why it exists:** Prevents chargers from staying in "Preparing" state indefinitely while waiting for drivers who change their minds or walk away.

**Practical impact:** If you reduce this to 60 seconds, drivers have only 1 minute to plug in after tapping their card. If you increase to 600 seconds, they have 10 minutes.

---

### AuthorizationTimeout (Default: 20 seconds)
**When it matters:** When the charger sends a UID to the CSMS for authorization.

**What happens:**
1. User taps RFID card (presenting a UID)
2. Charger sends `Authorize.req` message with the UID to your CSMS
3. **AuthorizationTimeout countdown begins (default: 20 seconds)**
4. Charger waits for CSMS response: Accept or Reject
5. If no response arrives within timeout → Charger treats it as an **offline condition**

**If timeout occurs:**
- Charger applies `LocalAuthorizeOffline` logic (if enabled)
- May consult Local List or Cache
- If no offline source available → Denies charging

**Practical impact:** 
- Set too short (e.g., 5 seconds): Network hiccups cause authorization failures
- Set too long (e.g., 60 seconds): Poor UX; users wait a minute for response
- 20 seconds is typical balance for most networks

---

## Offline Charger Behavior

What happens when the charger loses internet connection?

```{figure} images/OfflineMode.png
:align: center
:name: offline_mode

Image 1: Offline Authorization Flow
```

---

## Online Charger Behavior

What happens when the charger is online?

### Standard Mode (LocalPreAuthorize = False)


```{figure} images/PreAuthOff.png
:align: center
:name: remote_mode

Image 2: Remote Authorization Flow
```

**Effect:** Every authentication goes to your central system. Every decision is current.

### Fast Track Mode (LocalPreAuthorize = True)


```{figure} images/PreAuthOn.png
:align: center
:name: local_mode

Image 3: Local + Remote Authorization Flow
```

**Effect:** Known users get instant response (fast UX), but system verifies with server. If server disagrees later, charging stops.

---

## Decision Table: When Does Charging Start?

### Charger is OFFLINE

| LocalAuthorizeOffline | List Enabled | Cache Enabled | Result |
|---|---|---|---|
| OFF | - | - | ❌ No charging |
| ON | OFF | OFF | ❌ No charging |
| ON | ON | OFF | ✅ Charging if on List |
| ON | OFF | ON | ✅ Charging if seen before |
| ON | ON | ON | ✅ Charging if on List OR seen before |

### Charger is ONLINE

| LocalPreAuthorize | Result |
|---|---|
| OFF | Server decides for every user |
| ON | Known cached users start immediately; server verifies in background |

---

## Practical Scenarios

### Scenario 1: Always Online, Full Server Control
**Use if:** Charger always has internet, you want real-time control

```yaml
LocalAuthorizeOffline: OFF
LocalAuthListEnabled: OFF
AuthorizationCacheEnabled: OFF
LocalPreAuthorize: OFF
```

**Behavior:** Every user queried to server in real-time. No offline fallback.

---

### Scenario 2: Offline-Ready with Fixed User List
**Use if:** Charger may go offline, you have a fixed set of approved users

```yaml
LocalAuthorizeOffline: ON
LocalAuthListEnabled: ON
AuthorizationCacheEnabled: OFF
LocalPreAuthorize: OFF
```

**Behavior:**
- Offline: Only users on your approved list can charge
- Online: Server validates, but your list takes priority for conflicts
- Cache not used

---

### Scenario 3: Fast-Track for Frequent Users
**Use if:** High-traffic location, want instant response for regular users

```yaml
LocalAuthorizeOffline: ON
LocalAuthListEnabled: ON
AuthorizationCacheEnabled: ON
LocalPreAuthorize: ON
```

**Behavior:**
- Offline: Uses both approved list and previous users
- Online: Frequent users charge instantly (from cache), new users go to server
- System learns over time

---

### Scenario 4: Graceful Offline, Open Network
**Use if:** Can charge unknown users offline (verify when back online)

```yaml
LocalAuthorizeOffline: ON
LocalAuthListEnabled: OFF
AuthorizationCacheEnabled: ON
LocalPreAuthorize: OFF
```

**Behavior:**
- Offline: Anyone can charge (optimistic)
- Online: Validates everyone. You decide what to do if server says someone shouldn't have charged

---

## Special Cases

### What if Local List and Server Disagree?

If a user is **approved locally** but **server rejects** them:
- Charger reports the conflict to your system
- Action depends on your policy (typically: charger pauses charging, flags for review)

### Unknown Users Offline

Option A: **`AllowOfflineTxForUnknownId = False`** (Safe mode)
- Only known users can charge offline

Option B: **`AllowOfflineTxForUnknownId = True`** (Optimistic mode)
- Unknown users can charge offline
- When back online, server validates
- If validation fails, you choose:
  - **Hard stop:** Immediately stop charging
  - **Soft stop:** Limit their energy (e.g., max 1 kWh)

---

## Troubleshooting

| Issue | Check |
|---|---|
| Users rejected offline despite being approved | Is `LocalAuthorizeOffline = True`? Is at least one source enabled? |
| Seems too slow to authenticate | Try `LocalPreAuthorize = True` to cache known users |
| Same user approved locally but rejected by server | Check if Local List needs updating from server |
| Charger has been offline too long, cache entries stale | Monitor for old cache entries; periodic sync needed |

---

## Summary

- **Offline:** Needs `LocalAuthorizeOffline = True` + at least one source (List or Cache)
- **Online Standard:** Server validates each user
- **Online Fast-Track:** Cache pre-approves known users, server confirms in background
- **Local List:** Your fixed approved users, highest priority
- **Cache:** Charger's memory of previous approvals, fallback for offline
- **Conflicts:** When Local List and server disagree, charger ask server for confirmation