Authenticating SIP Messages with External OAuth 2.0 Server

The device supports the OAuth 2.0 authentication protocol (RFC 7662 and Internet Draft "draft-ietf-sipcore-sip-authn-02"), allowing it to authenticate any specified incoming SIP request (e.g., REGISTER and INVITE) with a third-party OAuth 2.0 authorization server over HTTP/S.

To authenticate SIP messages using the device's embedded NGINX server (acting as the Introspection endpoint) with Azure AD, see Authenticating SIP Messages using Device's OAuth 2.0 Server with Azure AD.

OAuth authorization consists of the following main stages:

(This stage doesn't involve the device.) The client application requires an OAuth Access Token for the user. There are multiple schemes to do this. For example, it may use the Authorization Code method, whereby the client application refers the user to the OAuth Authorization server to request an Authorization Code. The client application then uses the received Authorization Code to request an Access Token (and a Refresh Token) for the user from the Authorization server.

When the user wants to register with the device or make a call, the client application (e.g., Web browser for the WebRTC application) through which the user communicates with the device, sends a SIP REGISTER or INVITE request that includes the user's Access Token in the SIP Authorization header ("Bearer" value), as shown in the following REGISTER message example:

REGISTER sip:server.com SIP/2.0

Via: SIP/2.0/WSS 9rihbeck4vat.invalid;branch=z9hG4bK2426139

Max-Forwards: 69

To: <sip:alice@example.com>

From: "alice" <sip:alice@example.com>;tag=mstg4hpof6

Call-ID: 0il6hahess4ndc1pdlleqj

CSeq: 1 REGISTER

Authorization: Bearer eyJhbGciOiJSUzI1...
...zLbbMmZ06JA

Contact: <sip:lnumvv6i@9rihbeck4vat.invalid;transport=ws>;+sip.ice;reg-id=1;
+sip.instance="<urn:uuid:1007ed30-98a3-492e-966f 67b6f6eb99c5>";expires=600
Expires: 600
Allow: INVITE,ACK,CANCEL,BYE,UPDATE,MESSAGE,OPTIONS,REFER,INFO
Supported: path,gruu,outbound
User-Agent: Example WebRTC phone
Content-Length: 0

The device authenticates the SIP request, by sending (HTTP POST) an HTTP Introspection request with the user's Access Token to the OAuth Authorization server, as shown in the following example:

POST /realms/demo/protocol/openid-connect/token/introspect HTTP/1.1
Host: authorizationhost.com
Content-Type: application/x-www-form-urlencoded
Content-Length:…
Authorization: Basic dGVzdEludHJvc3BlY3Q6NTliZDA4NGUtMTJlNi00N2I5LWJmNz
token=<Access Token from Bearer in SIP Authorization header>

The OAuth Authorization server checks (introspects) if the token is currently active (or if it has expired or revoked). Upon a successful introspection, the OAuth Authorization server sends to the device a 200 OK response containing a JSON body ("application/ json").

The device checks the following attributes in the received JSON body:

●

"active": A "true" value indicates a valid token and the device allows the user access to its resources and continues with the regular handling and processing of the SIP request (e.g., registers user or processes the call). A "false" value indicates an invalid token and the device responds to the SIP request with a 401 (Unauthorized) response containing the header 'WWW-Authenticate: Bearer error="invalid-token"', indicating authentication failure.

●

"username": (Optional attribute) When it exists, the device compares it to the AOR of the SIP message. For REGISTER requests, the AOR is taken from the To header; for all other requests, the AOR is taken from the From header. If the username includes a "@" character, the entire AOR is compared; otherwise, only the user-part of the AOR is compared. If comparison fails, the device responds to the SIP request with a 401 (Unauthorized) response containing the header 'WWW-Authenticate: Bearer error="invalid_request"', indicating authentication failure.

The main configuration required for OAuth-based authentication, includes the following:

■

Configuring a Remote Web Service to represent the OAuth Authentication server

■

Configuring the source IP Group (client) to authenticate by an OAuth Authorization server

The following provides a step-by-step example of configuring OAuth authentication.

➢

To configure OAuth-based authentication:

Open the Remote Web Services table (see Configuring Remote Web Services), and then configure a Remote Web Service to represent the OAuth Authentication server:

Parameter	Value	Comment
'Name'	"OAUth-Server"	Any descriptive name.
'Type'	General	-
'Path'	"realms/demo/protocol/openid-connect/token/introspect"	Relative URL for the introspection service on the server.
'Username'	"device234"	Username that the device uses for authenticating the HTTP POST introspection request which it sends to the OAuth server.
'Password'	"12abMt"	Password that the device uses for authenticating the HTTP POST introspection request which it sends to the OAuth server. Note: The password cannot be configured with wide characters.

Select the Remote Web Service that you configured in Step 1, click the HTTP Remote Hosts link located below the table, and then configure an HTTP Remote Host:

Parameter	Value	Comment
'Address'	"oauth.example.com"	Address of the Authentication server.
'Port'	"443"	Port number of the Authentication server.
'Transport Type'	HTTPS	Secured HTTP.

Configure OAuth-based authentication for the source IP Group (client that the device needs to authenticate):

Parameter	Value	Comment
'Authentication Mode'	SBC as Server	The device authenticates as a server.
'Authentication Method List'	"register/setup-invite"	The SIP methods that the device needs to authenticate.
'SBC Server Authentication Type'	Authenticate with OAuth Server	The device authenticates the SIP requests with an OAuth Authentication server.
'OAuth HTTP Service'	OAuth-Server	Assigns the Remote Web Service that you configured (in Step 1) for the OAuth Authentication server.