401 Unauthorized — SIP Registration Failure
Triệu chứng
- SIP phone or softphone displays "Registration Failed", "401 Unauthorized", or "Authentication Error" in the status bar
- The device cannot make or receive calls because registration is required before the SIP server will route calls to the endpoint
- SIP trace shows: REGISTER → 401 (with WWW-Authenticate challenge) → REGISTER with credentials → 401 again (credentials rejected)
- Re-entering the same credentials does not resolve the issue — the second authenticated REGISTER also receives 401
- Log on the Asterisk/FreeSWITCH server shows: `Registration from <sip:user@domain> failed for 'x.x.x.x' - Wrong password`
- The device cannot make or receive calls because registration is required before the SIP server will route calls to the endpoint
- SIP trace shows: REGISTER → 401 (with WWW-Authenticate challenge) → REGISTER with credentials → 401 again (credentials rejected)
- Re-entering the same credentials does not resolve the issue — the second authenticated REGISTER also receives 401
- Log on the Asterisk/FreeSWITCH server shows: `Registration from <sip:user@domain> failed for 'x.x.x.x' - Wrong password`
Nguyên nhân gốc rễ
- Wrong SIP username or password configured on the phone or softphone — the most common cause; even a single character difference causes digest authentication to produce a completely different hash
- SIP domain or realm mismatch — the phone sends credentials for 'example.com' but the server challenges for 'sip.example.com', causing the digest response to be computed for the wrong realm
- Digest authentication algorithm mismatch — server requires SHA-256 but the SIP client only supports MD5 (or vice versa), so the client either ignores the challenge or sends an unsupported algorithm
- SIP account locked or disabled on the server due to too many failed registration attempts triggering fail2ban or the PBX's built-in brute-force protection
- Clock skew between the SIP client and server causing nonce expiration — digest authentication nonces are time-bound and a clock difference greater than 5 minutes invalidates them
Chẩn đoán
**Step 1: Capture the SIP REGISTER exchange**
```bash
# On the SIP server
sngrep -d eth0 port 5060
# Filter to REGISTER messages only
# Press 'f', type: method REGISTER
```
Expand the 401 response and read the `WWW-Authenticate` header. Note the `realm` value — it must match what the client is configured with.
**Step 2: Verify credentials on the SIP server**
```bash
# Asterisk — check the peer's secret
asterisk -rx 'sip show peer <username>'
# Look for: Secret: **** (masked but present)
# FreeSWITCH
fs_cli -x 'sofia status profile internal reg'
```
**Step 3: Check for IP ban / fail2ban**
```bash
sudo fail2ban-client status asterisk
# If the client IP appears in 'Banned IP list', unban it:
sudo fail2ban-client set asterisk unbanip <client-ip>
```
**Step 4: Verify system clock synchronization**
```bash
timedatectl status
# Confirm 'System clock synchronized: yes'
# If not: sudo timedatectl set-ntp true
chronyc tracking # or: ntpq -p
```
**Step 5: Test with a SIP softphone (known-good client)**
Use Linphone or Zoiper with the exact same credentials to isolate whether the issue is the physical phone or the server configuration.
```bash
# On the SIP server
sngrep -d eth0 port 5060
# Filter to REGISTER messages only
# Press 'f', type: method REGISTER
```
Expand the 401 response and read the `WWW-Authenticate` header. Note the `realm` value — it must match what the client is configured with.
**Step 2: Verify credentials on the SIP server**
```bash
# Asterisk — check the peer's secret
asterisk -rx 'sip show peer <username>'
# Look for: Secret: **** (masked but present)
# FreeSWITCH
fs_cli -x 'sofia status profile internal reg'
```
**Step 3: Check for IP ban / fail2ban**
```bash
sudo fail2ban-client status asterisk
# If the client IP appears in 'Banned IP list', unban it:
sudo fail2ban-client set asterisk unbanip <client-ip>
```
**Step 4: Verify system clock synchronization**
```bash
timedatectl status
# Confirm 'System clock synchronized: yes'
# If not: sudo timedatectl set-ntp true
chronyc tracking # or: ntpq -p
```
**Step 5: Test with a SIP softphone (known-good client)**
Use Linphone or Zoiper with the exact same credentials to isolate whether the issue is the physical phone or the server configuration.
Giải quyết
**Fix 1: Correct the SIP username and password**
On the SIP phone or softphone, navigate to the SIP account settings and re-enter the username and password character by character. Watch for trailing spaces, smart quotes, or auto-correction changing characters on mobile clients.
**Fix 2: Match the realm in client and server config**
```ini
# Asterisk sip.conf — set defaultuser and host explicitly
[my-extension]
type=friend
username=1001
secret=my-secure-password
host=dynamic
# Ensure the client's 'SIP domain' field matches the Asterisk realm:
# asterisk -rx 'sip show settings' | grep Realm
```
**Fix 3: Unban the client IP if blocked by fail2ban**
```bash
sudo fail2ban-client set asterisk unbanip 203.0.113.42
# Then re-test registration immediately
```
**Fix 4: Synchronize clocks with NTP**
```bash
sudo timedatectl set-ntp true
# Force immediate sync
sudo chronyc makestep
# Verify offset is under 1 second
chronyc tracking | grep 'RMS offset'
```
**Fix 5: Reset the SIP account password on the server**
```bash
# Asterisk — edit sip.conf and reload
sed -i 's/secret=.*/secret=new-password/' /etc/asterisk/sip.conf
asterisk -rx 'sip reload'
```
On the SIP phone or softphone, navigate to the SIP account settings and re-enter the username and password character by character. Watch for trailing spaces, smart quotes, or auto-correction changing characters on mobile clients.
**Fix 2: Match the realm in client and server config**
```ini
# Asterisk sip.conf — set defaultuser and host explicitly
[my-extension]
type=friend
username=1001
secret=my-secure-password
host=dynamic
# Ensure the client's 'SIP domain' field matches the Asterisk realm:
# asterisk -rx 'sip show settings' | grep Realm
```
**Fix 3: Unban the client IP if blocked by fail2ban**
```bash
sudo fail2ban-client set asterisk unbanip 203.0.113.42
# Then re-test registration immediately
```
**Fix 4: Synchronize clocks with NTP**
```bash
sudo timedatectl set-ntp true
# Force immediate sync
sudo chronyc makestep
# Verify offset is under 1 second
chronyc tracking | grep 'RMS offset'
```
**Fix 5: Reset the SIP account password on the server**
```bash
# Asterisk — edit sip.conf and reload
sed -i 's/secret=.*/secret=new-password/' /etc/asterisk/sip.conf
asterisk -rx 'sip reload'
```
Phòng ngừa
- **Use a password manager** to generate and store SIP credentials — avoid manual entry that introduces typos and reused passwords
- **Enable fail2ban with appropriate thresholds** (e.g., 5 failures in 60 seconds) to block brute-force attempts, but ensure legitimate reconfiguration attempts don't trigger false positives
- **Enforce NTP on all SIP endpoints** to prevent clock-skew nonce failures — a clock difference of more than 5 minutes will cause digest authentication to fail regardless of correct credentials
- **Document realm and domain values** explicitly in your SIP provisioning templates to prevent mismatches when onboarding new phones
- **Use TLS transport with SRTP** so SIP credentials are never transmitted in cleartext, reducing the risk of credential theft that necessitates password resets
- **Enable fail2ban with appropriate thresholds** (e.g., 5 failures in 60 seconds) to block brute-force attempts, but ensure legitimate reconfiguration attempts don't trigger false positives
- **Enforce NTP on all SIP endpoints** to prevent clock-skew nonce failures — a clock difference of more than 5 minutes will cause digest authentication to fail regardless of correct credentials
- **Document realm and domain values** explicitly in your SIP provisioning templates to prevent mismatches when onboarding new phones
- **Use TLS transport with SRTP** so SIP credentials are never transmitted in cleartext, reducing the risk of credential theft that necessitates password resets