Third-Party Token-Based Authentication and Authorization for Session Initiation Protocol (SIP)Auth0OttawaOntarioCanadarifaat.s.ietf@gmail.comEricssonHirsalantie 11Jorvas02420Finlandchrister.holmberg@ericsson.comNokiaBarcelonaSpainvictor.pascual_avila@nokia.com
RAI
SIP CoreSIP OAuth3rd party authenticationThird party authentication
This document defines the "Bearer" authentication scheme for
the Session Initiation Protocol (SIP) and a mechanism by
which user authentication and SIP registration authorization
is delegated to a third party, using the OAuth 2.0 framework
and OpenID Connect Core 1.0. This document updates RFC 3261
to provide guidance on how a SIP User Agent Client (UAC)
responds to a SIP 401/407 response that contains multiple
WWW-Authenticate/Proxy-Authenticate header fields.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by
the Internet Engineering Steering Group (IESG). Further
information on Internet Standards is available in Section 2 of
RFC 7841.
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
.
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
() in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Simplified BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Simplified BSD License.
Table of Contents
. Introduction
. Terminology
. Applicability
. Token Types and Formats
. Example Flows
. Registration
. Registration with Preconfigured AS
. SIP Procedures
. UAC Behavior
. Obtaining Tokens and Responding to Challenges
. Protecting the Access Token
. REGISTER Request
. Non-REGISTER Request
. User Agent Server (UAS) and Registrar Behavior
. Proxy Behavior
. Access Token Claims
. WWW-Authenticate Response Header Field
. Security Considerations
. IANA Considerations
. New Proxy-Authenticate Header Field Parameters
. New WWW-Authenticate Header Field Parameters
. Normative References
. Informative References
Acknowledgments
Authors' Addresses
Introduction
The Session Initiation Protocol (SIP) uses the same framework
as HTTP to authenticate users: a simple
challenge-response authentication mechanism that allows a SIP User Agent Server (UAS), proxy, or
registrar to challenge a SIP User Agent Client (UAC) request and allows
the UAC to provide authentication information in response to that
challenge.
OAuth 2.0 defines a token-based authorization
framework to allow an OAuth client to access resources on behalf of its user.
The OpenID Connect Core 1.0 specification defines
a simple identity layer on top of the OAuth 2.0 protocol, which enables
OAuth/OpenID clients to verify the identity of the user based on the authentication
performed by a dedicated authorization server (AS), referred to as
OpenID Provider (OP), as well as to obtain basic profile information about the user.
This document defines the "Bearer" authentication scheme for
SIP and a mechanism by which user
authentication and SIP registration authorization is delegated to a
third party, using the OAuth 2.0 framework and OpenID Connect Core
1.0. This kind of user authentication enables single sign-on,
which allows the user to authenticate once and gain access to both SIP
and non-SIP services.
This document also updates by defining the UAC procedures
when a UAC receives a 401/407 response with multiple WWW-Authenticate/Proxy-Authenticate
header fields, providing challenges using different authentication schemes
for the same realm.
Terminology
The key words "MUST", "MUST NOT",
"REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are
to be interpreted as
described in BCP 14
when, and only when, they appear in all capitals, as shown here.
Applicability
This document covers cases where grants that allow the UAC to obtain an
access token from the AS are used. Cases where the UAC is not able to obtain
an access token (e.g., in the case of an authorization code grant) are not covered.
Token Types and Formats
The tokens used in third-party authorization depend on the type of
AS.
An OAuth AS provides the following tokens to a successfully
authorized UAC:
Access Token:
The UAC will use this token to gain access to services by
providing the token to a SIP server.
Refresh Token:
The UAC will present this token to the AS
to refresh a stale access token.
An OP returns an additional token:
ID Token:
This token contains a SIP URI associated with the user and other
user-specific details that will be consumed by the UAC.
Tokens can be represented in two different formats:
Structured Token:
A token that consists of a structured object that contains the
claims associated with the token, e.g., JSON Web Token (JWT), as defined
in .
Reference Token:
A token that consists of an opaque string that is used to obtain the
details of the token and its associated claims, as defined in .
Access tokens are represented in one of the above two formats. Refresh tokens
usually are represented in a reference format, as this token is consumed
only by the AS that
issued the token. The ID token is defined as a structured token in the form of a JWT.
Example FlowsRegistration below shows an example of a SIP registration where
the registrar informs the UAC about the AS from which the UAC can
obtain an access token.
Example Registration Flow
UAC Registrar AS/OP
---------------------------------------------------------------------
| | |
| [1] REGISTER | |
|------------------------------>| |
| | |
| [2] 401 Unauthorized | |
| WWW-Authenticate: Bearer "authz_server"="<authz_server>" |
|<------------------------------| |
| | |
| [3] The UAC interacts with the AS and obtains tokens using |
| some out-of-scope mechanism. |
|<=============================================================>|
| | |
| [4] REGISTER | |
| Authorization: Bearer <access_token> |
|------------------------------>| |
| | [5] HTTP POST /introspect |
| | {access_token} |
| | (OPTIONAL) |
| |------------------------------>|
| | |
| | [6] 200 OK {metadata} |
| | (OPTIONAL) |
| |<------------------------------|
| | |
| [7] 200 OK | |
|<------------------------------| |
| | |
In step [1], the UAC starts the registration process by sending a
SIP REGISTER request to the registrar without any credentials.
In step [2], the registrar challenges the UA by sending a SIP
401 (Unauthorized) response to the REGISTER request. In the response,
the registrar includes information about the AS to contact in order
to obtain a token.
In step [3], the UAC interacts with the AS via an out-of-scope mechanism, potentially using the OAuth Native
App mechanism defined in . The AS authenticates the user and provides the UAC with the
tokens needed to access the SIP service.
In step [4], the UAC retries the registration process by sending a new
REGISTER request that includes the access token that the UAC
obtained in the step above.
The registrar validates the access token. If the access token is a
reference token, the registrar MAY perform an introspection
, as in steps [5] and [6], in order to obtain more
information about the access token and its scope, per .
Otherwise, after the registrar validates the token, it inspects its
claims and acts upon it.
In step [7], once the registrar has successfully verified and accepted the
access token, it sends a 200 (OK) response to the REGISTER request.
Registration with Preconfigured AS shows an example of a SIP registration where
the UAC has been preconfigured with information about the AS
from which to obtain the access token.
Example Registration Flow - AS Information Preconfigured
UAC Registrar AS/OP
---------------------------------------------------------------------
| | |
| [1] The UAC interacts with the AS and obtains tokens using |
| some out-of-scope mechanism. |
|<=============================================================>|
| | |
| [2] REGISTER | |
| Authorization: Bearer <access_token> |
|------------------------------>| |
| | [3] HTTP POST /introspect |
| | {access_token} |
| | (OPTIONAL) |
| |------------------------------>|
| | |
| | [4] 200 OK {metadata} |
| | (OPTIONAL) |
| |<------------------------------|
| | |
| [5] 200 OK | |
|<------------------------------| |
| | |
In step [1], the UAC interacts with the AS using an out-of-scope mechanism, potentially using the OAuth Native
App mechanism defined in . The AS authenticates the user and provides the UAC with the
tokens needed to access the SIP service.
In step [2], the UAC initiates the registration process by sending a new
REGISTER request that includes the access token that the UAC
obtained in the step above.
The registrar validates the access token. If the access token is a
reference token, the registrar MAY perform an introspection
, as in steps [4] and [5], in order to obtain more
information about the access token and its scope, per .
Otherwise, after the registrar validates the token, it inspects its
claims and acts upon it.
In step [5], once the registrar has successfully verified and accepted the
access token, it sends a 200 (OK) response to the REGISTER request.
SIP Procedures defines the
SIP procedures for the Digest authentication mechanism. The same
procedures apply to the "Bearer" authentication mechanism, with the
changes described in this section.UAC BehaviorObtaining Tokens and Responding to Challenges
When a UAC sends a request without credentials (or with invalid credentials),
it could receive either a 401 (Unauthorized) response with a WWW-Authenticate header field or a 407 (Proxy
Authentication Required) response with a Proxy-Authenticate header field.
If the WWW-Authenticate or Proxy-Authenticate header field indicates "Bearer" scheme authentication
and contains an address to an AS, the UAC contacts the
AS in order to obtain tokens and includes the requested
scopes, based on a local configuration ().
The UAC MUST check the AS URL received in the 401/407 response
against a list of trusted ASs configured on the UAC in order
to prevent several classes of possible vulnerabilities when a client blindly
attempts to use any provided AS.
The detailed OAuth2 procedure to authenticate the user and obtain
these tokens is out of scope of this document.
The address of the AS might already be known to the UAC via configuration.
In such cases, the UAC can contact the AS for tokens
before it sends a SIP request ().
Procedures for native applications are defined in .
When using the mechanism defined
in , the user of the UAC will be directed to interact
with the AS using a web browser, which allows the AS
to prompt the user for multi-factor authentication, to redirect the user to
third-party identity providers, and to enable the use of single sign-on sessions.
The tokens returned to the UAC depend on the type of AS; an OAuth AS provides an
access token and, optionally, a refresh token . The refresh
token is only used between the UAC and the AS. If the AS provides a refresh token
to the UAC, the UAC uses it to request a new access token from
the AS before the currently used access token expires ().
If the AS does not provide a refresh token, the UAC needs to reauthenticate the user
in order to get a new access token before the currently used access token expires.
An OP returns an additional ID token that contains claims about
the authentication of the user by an authorization server. The ID token can potentially
include other optional claims about the user, e.g., the SIP URI, that will be consumed by
the UAC and later used to register with the registrar.
If the UAC receives a 401/407 response with multiple WWW-
Authenticate/Proxy-Authenticate header fields, providing challenges
using different authentication schemes for the same realm, the UAC
provides credentials for one of the schemes that it supports,
based on local policy.
Protecting the Access Token mandates that access tokens are protected with
TLS when in transit. However, SIP makes use of intermediary SIP proxies,
and TLS only guarantees hop-to-hop protection when used to protect SIP signaling.
Therefore, the access token MUST be protected in a way so that only authorized SIP
servers will have access to it. SIP endpoints that support this document MUST
use encrypted JWTs for encoding and protecting
access tokens when they are included in SIP requests, unless some other mechanism
is used to guarantee that only authorized SIP endpoints have access to
the access token. TLS can still be used for protecting traffic between
SIP endpoints and the AS, as defined in .
REGISTER RequestThe procedures in this section apply when the UAC has received a
challenge that contains a "Bearer" scheme and the UAC has obtained
a token, as specified in .The UAC sends a REGISTER request with an Authorization header
field containing the response to the challenge, including the "Bearer"
scheme carrying a valid access token in the request, as specified in
.
Note that if there were multiple challenges with different schemes, then the UAC may be
able to successfully retry the request using non-"Bearer" credentials.
Typically, a UAC will obtain a new access token for each new
binding. However, based on local policy, a UAC MAY
include an access token that has been used for another binding
associated with the same Address Of Record (AOR) in the request.
If the access token included in a REGISTER request is not accepted
and the UAC receives a 401 response or a 407 response, the UAC
follows the procedures in .
Non-REGISTER RequestThe procedures in this section apply when the UAC has received a
challenge that contains a "Bearer" scheme and the UAC has obtained a
token, as specified in .
When the UAC sends a request, it MUST include an Authorization header field
with a "Bearer" scheme carrying a valid access token obtained from the AS indicated
in the challenge in the request, as specified in .
Based on local policy, the UAC MAY include an access token that has been used
for another dialog, or for another stand-alone request, if the target of the
new request is the same.
If the access token included in a request is not accepted and the UAC receives
a 401 response or a 407 response, the UAC follows the procedures in
.
User Agent Server (UAS) and Registrar Behavior
When a UAS or registrar receives a request that fails to contain
authorization credentials acceptable to it, the UAS/registrar SHOULD challenge the
request by sending a 401 (Unauthorized) response. If the UAS/registrar
chooses to challenge the request and is willing to accept an access token
as a credential, it MUST include a WWW-Authenticate header
field in the response that indicates a "Bearer" scheme and includes an AS address,
encoded as an https URI , from which the UAC can obtain
an access token.
When a UAS or registrar receives a SIP request that contains an Authorization
header field with an access token, the UAS/registrar MUST validate the access
token using the procedures associated with the type of access token (structured
or reference) used, e.g., .
If the token provided is an expired access token, then the UAS/registrar MUST reply with
a 401 (Unauthorized) response, as defined in .
If the validation is successful, the UAS/registrar can continue to process
the request using normal SIP procedures. If the validation fails, the UAS/registrar
MUST reply with a 401 (Unauthorized) response.
Proxy Behavior
When a proxy receives a request that fails to contain
authorization credentials acceptable to it, it SHOULD challenge the
request by sending a 407 (Proxy Authentication Required) response.
If the proxy chooses to challenge the request and is willing to accept an access token
as a credential, it MUST include a Proxy-Authenticate
header field in the response that indicates a "Bearer" scheme and includes an AS address,
encoded as an https URI , from which the UAC can obtain
an access token.
When a proxy wishes to authenticate a received request, it MUST
search the request for Proxy-Authorization header fields with 'realm'
parameters that match its realm. It then MUST successfully validate
the credentials from at least one Proxy-Authorization header field
for its realm. When the scheme is "Bearer", the proxy MUST validate the
access token using the procedures associated with the type of access
token (structured or reference) used, e.g., .
Access Token Claims
The type of services to which an access token grants access can be determined
using different methods. The methods used and the access provided by the token
are based on local policy agreed between the AS and the registrar.
If an access token is encoded as a JWT, it will contain a list of claims
, including both registered and application-specific claims. The
registrar can grant access to services based on such claims,
some other mechanism, or a combination of claims and some other mechanism.
If an access token is a reference token, the registrar will grant access
based on some other mechanism. Examples of such other mechanisms are
introspection and user profile lookups.
WWW-Authenticate Response Header FieldThis section uses ABNF to describe the
syntax of the WWW-Authenticate header field when used with the "Bearer"
scheme to challenge the UAC for credentials by extending the
'challenge' parameter defined by ."Bearer" Scheme Syntax
challenge =/ ("Bearer" LWS bearer-cln *(COMMA bearer-cln))
bearer-cln = realm / scope-param / authz-server-param / error-param /
auth-param
realm = <defined in RFC 3261>
scope-param = "scope" EQUAL DQUOTE scope DQUOTE
scope = <defined in RFC 6749>
authz-server-param = "authz_server" EQUAL DQUOTE authz-server DQUOTE
authz-server = https-URI
https-URI = <defined in RFC 7230>
error-param = "error" EQUAL DQUOTE error DQUOTE
error = <defined in RFC 6749>
auth-param = <defined in RFC 3261>
The authz_server parameter contains the HTTPS URI, as defined in
, of the AS. The UAC can discover
metadata about the AS using a mechanism like the one defined in .
The realm and auth-param parameters are defined in .
Per , "the realm string alone defines the protection
domain". states that the realm string must be
globally unique and recommends that the realm string contain a hostname or
domain name. It also states that the realm string should be a human-readable identifier
that can be rendered to the user.
The scope and error parameters are defined in .
The scope parameter can be used by the registrar/proxy to indicate to the UAC
the minimum scope that must be associated with the access token to be able to get
service. As defined in , the value of the scope parameter
is expressed as a list of space-delimited, case-sensitive strings. The strings are
defined by the AS. The values of the scope parameter are out of
scope of this document. The UAC will use the scope provided by the registrar to
contact the AS and obtain a proper token with the requested scope.
The error parameter could be used by the registrar/proxy to indicate to the UAC
the reason for the error, with possible values of "invalid_token" or "invalid_scope".
Security Considerations
The security considerations for OAuth are defined in .
The security considerations for "Bearer" tokens are defined in .
The security considerations for JWTs are defined in .
These security considerations also apply to SIP usage of access tokens, as defined in this
document.
mandates that access tokens are protected with
TLS when in transit. However, SIP makes use of intermediary SIP proxies,
and TLS only guarantees hop-to-hop protection when used to protect SIP signaling.
Therefore, the access token MUST be protected in a way so that only authorized SIP
servers will have access to it. SIP endpoints that support this document MUST
use encrypted JWTs for encoding and protecting
access tokens when they are included in SIP requests, unless some other mechanism
is used to guarantee that only authorized SIP endpoints have access to
the access token. TLS can still be used for protecting traffic between
SIP endpoints and the AS, as defined in .
Single Sign-On (SSO) enables the user to use one set of credentials to
authenticate once and gain access to multiple SIP and non-SIP services
using access token(s). If the SSO login is compromised, that single
point of compromise has a much broader effect than is the case without
SSO. Further, an attacker can often use a compromised account to set
up Single Sign-On for other services that the victim has not
established an account with and sometimes can even switch a dedicated
account into SSO mode, creating a still broader attack.
Because of that, it is critical to make sure that extra security
measures be taken to safeguard credentials used for Single Sign-On.
Examples of such measures include a long passphrase instead of a
password, enabling multi-factor authentication, and the use of
the native platform browser when possible, as defined in .
Although this is out of scope for this document, it is important to
carefully consider the claims provided in the tokens used to access
these services to make sure of the privacy of the user accessing these
services. As mentioned above, this document calls for encrypting JWTs
representing the access token.
It is important that both parties participating in SSO provide
mechanisms for users to sever the SSO relationship so that it is
possible without undue difficulty to mitigate a compromise that has
already happened.
The operator of an SSO authentication system has access to
private information about sites and services that their users log
into and even, to some extent, their usage patterns. It's
important to call these out in privacy disclosures and policies and
to make sure that users can be aware of the trade-offs between
convenience and privacy when they choose to use SSO.
When a registrar chooses to challenge a REGISTER request, if the registrar
can provide access to different levels of services, it is RECOMMENDED that
the registrar include a scope in the response in order to indicate the minimum
scope needed to register and access basic services. The access token might
include an extended scope that gives the user access to more advanced features
beyond basic services. In SIP, the AS administrator will typically decide what level
of access is provided for a given user.
The UAC MUST check the AS URL received in the 401/407 response
against a list of trusted ASs configured on the UAC in order
to prevent several classes of possible vulnerabilities when a client blindly
attempts to use any provided AS.
IANA ConsiderationsNew Proxy-Authenticate Header Field Parameters
This section defines new SIP header field parameters in the "Header Field
Parameters and Parameter Values" subregistry of the "Session
Initiation Protocol (SIP) Parameters" registry:
Header Field: Proxy-Authenticate
Parameter Name
Predefined Values
Reference
authz_server
No
RFC 8898
error
No
RFC 8898
scope
No
RFC 8898
New WWW-Authenticate Header Field Parameters
This section defines new SIP header field parameters in the "Header Field
Parameters and Parameter Values" subregistry of the "Session
Initiation Protocol (SIP) Parameters" registry:
Header Field: WWW-Authenticate
Parameter Name
Predefined Values
Reference
authz_server
No
RFC 8898
error
No
RFC 8898
scope
No
RFC 8898
Normative ReferencesOpenID Connect Core 1.0Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.SIP: Session Initiation ProtocolThis document describes Session Initiation Protocol (SIP), an application-layer control (signaling) protocol for creating, modifying, and terminating sessions with one or more participants. These sessions include Internet telephone calls, multimedia distribution, and multimedia conferences. [STANDARDS-TRACK]Augmented BNF for Syntax Specifications: ABNFInternet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]The OAuth 2.0 Authorization FrameworkThe OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK]The OAuth 2.0 Authorization Framework: Bearer Token UsageThis specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK]Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.JSON Web Token (JWT)JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.OAuth 2.0 Token IntrospectionThis specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.Informative ReferencesOAuth 2.0 for Native AppsOAuth 2.0 authorization requests from native apps should only be made through external user-agents, primarily the user's browser. This specification details the security and usability reasons why this is the case and how native apps and authorization servers can implement this best practice.OAuth 2.0 Authorization Server MetadataThis specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities.AcknowledgmentsThe authors would like to specially thank for his multiple detailed reviews and suggested text that
significantly improved the quality of the document.The authors would also like to thank the following for their review
and feedback on this document:, , , and .The authors would also like to thank the following for their review
and feedback of the original document that was replaced with this
document:, , , , , , ,
, ,
, , , , and ., , , , , and provided feedback and suggestions for
improvements as part of the IESG evaluation of the document. Special
thanks to for his detailed and
comprehensive reviews and comments.The authors would also like to specially thank for her multiple reviews, editorial help, and
the conversion of the XML source file from v2 to v3.Authors' AddressesAuth0OttawaOntarioCanadarifaat.s.ietf@gmail.comEricssonHirsalantie 11Jorvas02420Finlandchrister.holmberg@ericsson.comNokiaBarcelonaSpainvictor.pascual_avila@nokia.com