PJSIP Authentication

Getting Started -- Last reviewed 2026-06-26 pjsip sip authentication configuration getting-started security trunking

PJSIP Authentication

PJSIP auth is handled by a dedicated auth object that endpoints reference. You write the credentials once, point one or more endpoints at it, and Asterisk takes care of the 401/Authorization exchange. This covers basic setup, how digest auth actually works, and the SHA-256/SHA-512-256 support added in Asterisk 20.12.

On this page

PJSIP Authentication

Basic auth setup

Inbound auth (phones registering to Asterisk)

When a phone registers or places a call, Asterisk challenges it with a 401. The phone responds with credentials, Asterisk verifies them against the auth object.

[myphone-auth]
type=auth
auth_type=userpass
username=6001
password=your_password
realm=asterisk

[6001]
type=endpoint
auth=myphone-auth
aors=6001
context=internal
disallow=all
allow=ulaw

[6001]
type=aor
max_contacts=1

realm is optional. If omitted, Asterisk uses the default_realm from the global object, which defaults to asterisk.

Outbound auth (trunks connecting to a provider)

When Asterisk registers to a SIP provider or places an outbound call, the provider sends the 401. Asterisk uses the auth object in outbound_auth to respond.

[myprovider-auth]
type=auth
auth_type=userpass
username=myaccountname
password=your_password

[myprovider]
type=endpoint
outbound_auth=myprovider-auth
aors=myprovider-aor
context=from-external
disallow=all
allow=ulaw

Leave realm off outbound auth objects. You rarely know the exact realm a provider will send, and an empty realm matches any challenge. See the realm section below.

How SIP digest authentication works

SIP uses a challenge-response model. Asterisk plays either side depending on which direction the call flows.

Asterisk as the server (UAS): A phone sends a REGISTER or INVITE. Asterisk checks the endpoint's auth parameter, gets the realm and credentials, and responds with a 401 containing a WWW-Authenticate header. The phone hashes username:realm:password, retries with an Authorization header, and Asterisk verifies by computing the same hash. Match means proceed; no match gets another 401.

Asterisk as the client (UAC): Asterisk sends a request to a provider, gets back a 401 with the provider's realm and algorithm. It finds an auth object via outbound_auth whose realm matches (or is empty), hashes the credentials, and retries with Authorization.

Pre-hashed passwords let you store a hash instead of plaintext so the password never appears in the config. The catch: the hash input is username:realm:password, which means you have to know the realm before generating it. For inbound auth you control the realm, so this is fine. For outbound auth to a provider, you need to know their realm ahead of time, which is not always practical.

SHA-256 and SHA-512-256 support

Added in Asterisk 20.12, 21.7, and 22.2. MD5 is still the default and still works fine. If your phones or providers start negotiating stronger algorithms, these parameters are what you need.

Version requirements

SHA-256 and SHA-512-256 require PJProject 2.15.1 (bundled with Asterisk 20.12/21.7/22.2). SHA-256 needs OpenSSL > 1.0.0; SHA-512-256 needs OpenSSL >= 1.1.1. To check what your system supports:

bash asterisk -rx "pjproject show buildopts"

Changed parameters

auth_type now accepts digest as the recommended value. The old values are deprecated but still load:

auth_type	Behavior
`digest`	Standard digest auth, plain-text or pre-hashed password (recommended)
`userpass`	Deprecated. Automatically converted to `digest`
`md5`	Deprecated. Automatically converted to `digest`
`google_oauth`	Google OAuth for Google Voice (unchanged)

md5_cred is deprecated. Asterisk converts it to a password_digest entry with the MD5 algorithm on load. Use password_digest for new configs.

New parameters

password_digest replaces md5_cred and extends it to SHA-256 and SHA-512-256. Format:

password_digest = <algorithm>:<hashed-value>

Where <algorithm> is MD5, SHA-256, or SHA-512-256 (IANA names, case-insensitive). One entry per algorithm per auth object.

Generate the hash with openssl:

echo -n "myuser:somedomain:somepassword" | openssl dgst -md5
# MD5(stdin)= 1650345a24d9b5fdbc9c28e1f2321387
# Set: password_digest = MD5:1650345a24d9b5fdbc9c28e1f2321387

echo -n "myuser:somedomain:somepassword" | openssl dgst -SHA-256
# SHA2-256(stdin)= e8789f45d84aac27977eed41f3eec7572bb8ee81c6398715a04a51a7f9c68122
# Set: password_digest = SHA-256:e8789f45d84aac27977eed41f3eec7572bb8ee81c6398715a04a51a7f9c68122

echo -n "myuser:somedomain:somepassword" | openssl dgst -SHA512-256
# SHA2-512/256(stdin)= f8c3d34ce5ae6550740eaed0bff78a8aed354e87f2364813e4dbe9624bf06570
# Set: password_digest = SHA-512-256:f8c3d34ce5ae6550740eaed0bff78a8aed354e87f2364813e4dbe9624bf06570

Use echo -n

The -n flag suppresses the trailing newline. Without it, the newline gets included in the hash and the result will not match what Asterisk computes.

OpenSSL names vs. IANA names

OpenSSL and the IANA use different names. In Asterisk config, use IANA names: MD5, SHA-256, SHA-512-256. In the openssl command, use SHA512-256 (no hyphen after SHA) for SHA-512-256. Do not mix them up in config.

supported_algorithms_uas lists the algorithms Asterisk offers when sending a 401. Asterisk adds one WWW-Authenticate header per algorithm in the order listed. Per RFC 7616, list most-preferred first; the client uses the first one it supports.

supported_algorithms_uas = SHA-256, MD5

Defaults to the global default_auth_algorithms_uas, or MD5 if neither is set.

supported_algorithms_uac lists the algorithms Asterisk accepts when responding to a provider's 401. If the provider offers SHA-256 and MD5 but only MD5 is listed here, Asterisk uses MD5. Order does not matter here since the provider sets the preference.

supported_algorithms_uac = SHA-256, MD5, SHA-512-256

Defaults to the global default_auth_algorithms_uac, or MD5 if neither is set.

Credentials must match the algorithm

Asterisk cannot authenticate for an algorithm it has no credentials for. If supported_algorithms_uas lists SHA-256 but the auth object has no password_digest for SHA-256 and no plain-text password, the config fails to load. Either provide a plain-text password (Asterisk derives the hash at runtime) or a password_digest entry for each algorithm listed. You can supply both; a matching password_digest is preferred, with password as fallback.

Realm notes

For inbound auth (Asterisk as UAS), set realm to a specific value. This is what appears in the WWW-Authenticate header the phone responds to.

For outbound auth (Asterisk as UAC), leave realm empty, set it to *, or omit it. Asterisk then matches any realm a provider sends.

Do not share an auth object between auth and outbound_auth

Some setups put the same auth object in both auth and outbound_auth on an endpoint. This usually breaks one direction or the other. As a UAS you need a specific realm set; as a UAC you want an empty or wildcard realm so you can handle whatever the remote end sends. Those requirements conflict. Unless you know the provider's realm in advance and it matches your own, use two separate auth objects.

Examples

Phone with plain-text password

[somephone-auth]
type=auth
auth_type=digest
realm=myrealm
username=myuser
password=my-plain-text-password
supported_algorithms_uas=SHA-256, MD5

[somephone]
type=endpoint
auth=somephone-auth

Asterisk sends a 401 with two WWW-Authenticate headers: SHA-256 first, MD5 second. The phone uses the first algorithm it supports.

Phone with pre-hashed credentials

[somephone-auth]
type=auth
auth_type=digest
realm=myrealm
username=myuser
password_digest=MD5:c3cffc6ef6f7c002a51d7f3fe2695ab4
password_digest=SHA-256:c3cffc6ef6f7c002a51d7f3fe2695ab4
password_digest=SHA-512-256:9468f16f3e37ac9c6e572e34533015e26d8b7b0b23a9f5953bd4be63a258ca60
supported_algorithms_uas=SHA-256, SHA-512-256, MD5

[somephone]
type=endpoint
auth=somephone-auth

No plaintext password in the config. The realm here must match exactly the realm used when generating the hashes.

Provider trunk, plain-text password

[someprovider-auth]
type=auth
auth_type=digest
username=myuser
password=my-plain-text-password
supported_algorithms_uac=MD5

[myendpoint]
type=endpoint
outbound_auth=someprovider-auth

Realm omitted (defaults to wildcard). If the provider offers SHA-256 first but only MD5 is listed in supported_algorithms_uac, Asterisk responds with MD5.

Provider trunk, legacy pre-hashed MD5

[someprovider-auth]
type=auth
auth_type=md5
username=myuser
md5_cred=c3cffc6ef6f7c002a51d7f3fe2695ab4

[myendpoint]
type=endpoint
outbound_auth=someprovider-auth

auth_type=md5 and md5_cred are deprecated but still work. Asterisk converts them internally. This config cannot negotiate SHA-256.