idnits 2.17.1 draft-ietf-sipcore-sip-authn-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC3261, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC3261, updated by this document, for RFC5378 checks: 2000-07-17) -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 26, 2017) is 2396 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'STIR' is mentioned on line 208, but not defined == Unused Reference: 'RFC7662' is defined on line 578, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'MITKB' -- Possible downref: Non-RFC (?) normative reference: ref. 'OPENID' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIP Core R. Shekh-Yusef, Ed. 3 Internet-Draft Avaya 4 Updates: 3261 (if approved) C. Holmberg 5 Intended status: Standards Track Ericsson 6 Expires: March 30, 2018 V. Pascual 7 webrtchacks 8 September 26, 2017 10 Third-Party Authentication for Session Initiation Protocol (SIP) 11 draft-ietf-sipcore-sip-authn-01 13 Abstract 15 This document defines an authentication mechanism for SIP, that is 16 based on the OAuth 2.0 and OpenID Connect Core 1.0 specifications, to 17 enable the delegation of the user authentication to a dedicated 18 third-party IdP entity that is separate from the SIP network elements 19 that provide the SIP service. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 30, 2018. 38 Copyright Notice 40 Copyright (c) 2017 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 This document may contain material from IETF Documents or IETF 54 Contributions published or made publicly available before November 55 10, 2008. The person(s) controlling the copyright in some of this 56 material may not have granted the IETF Trust the right to allow 57 modifications of such material outside the IETF Standards Process. 58 Without obtaining an adequate license from the person(s) controlling 59 the copyright in such materials, this document may not be modified 60 outside the IETF Standards Process, and derivative works of it may 61 not be created outside the IETF Standards Process, except to format 62 it for publication as an RFC or to translate it into languages other 63 than English. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.2. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 3 70 1.3. ID Token . . . . . . . . . . . . . . . . . . . . . . . . 4 71 1.4. SIP User Agent Types . . . . . . . . . . . . . . . . . . 5 72 1.5. Authentication Types . . . . . . . . . . . . . . . . . . 5 73 2. Authentication using the Authorization Code Flow . . . . . . 6 74 2.1. Public UA with Rich UI . . . . . . . . . . . . . . . . . 6 75 2.1.1. Registration . . . . . . . . . . . . . . . . . . . . 7 76 2.1.2. Shared-Key . . . . . . . . . . . . . . . . . . . . . 8 77 2.1.3. Re-Registration Requests . . . . . . . . . . . . . . 8 78 2.1.4. Token Refresh . . . . . . . . . . . . . . . . . . . . 9 79 2.2. Public UA with Limited UI . . . . . . . . . . . . . . . . 10 80 2.2.1. Registration . . . . . . . . . . . . . . . . . . . . 10 81 2.2.2. Shared-Key . . . . . . . . . . . . . . . . . . . . . 11 82 2.2.3. Token Refresh . . . . . . . . . . . . . . . . . . . . 11 83 2.2.4. Re-Registration Requests . . . . . . . . . . . . . . 12 84 3. Authentication using the Resource Owner Password Credentials 85 flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 13 87 3.2. Registration . . . . . . . . . . . . . . . . . . . . . . 13 88 3.3. Subsequent Requests . . . . . . . . . . . . . . . . . . . 14 89 4. Authorization Header Syntax . . . . . . . . . . . . . . . . . 14 90 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 91 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 92 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 93 8. Normative References . . . . . . . . . . . . . . . . . . . . 15 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 96 1. Introduction 98 The SIP protocol [RFC3261] uses the framework used by the HTTP 99 protocol for authenticating users, which is a simple challenge- 100 response authentication mechanism that allows a server to challenge a 101 client request and allows a client to provide authentication 102 information in response to that challenge. 104 OAuth 2.0 [RFC6749] defines a token based authorization framework to 105 allow clients to access resources on behalf of their user. 107 The OpenID Connect 1.0 [OPENID] specifications defines a simple 108 identity layer on top of the OAuth 2.0 protocol, which enables 109 clients to verify the identity of the user based on the 110 authentication performed by a dedicated IdP entity, as well as to 111 obtain basic profile information about the user. 113 This document defines an authentication mechanism for SIP, that is 114 based on the OAuth 2.0 and OpenID Connect Core 1.0 specifications, to 115 enable the delegation of the user authentication to a dedicated 116 third-party IdP entity that is separate from the SIP network elements 117 that provide the SIP service. 119 1.1. Terminology 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 1.2. Roles 127 resource owner 129 An entity capable of granting access to a protected resource. 130 When the resource owner is a person, it is referred to as an 131 end-user. 133 In a typical SIP network, it is the management element in the 134 system that acts as a resource owner. 136 resource server 138 The server hosting the protected resources or services, capable 139 of accepting and responding to protected resource and services 140 requests using access tokens. 142 OAuth 2.0 client 144 An application making protected resource requests on behalf of 145 the resource owner and with its authorization. The term 146 "client" does not imply any particular implementation 147 characteristics (e.g., whether the application executes on a 148 server, a desktop, or other devices). 150 SIP client 152 An application making requests to access SIP services on behalf 153 of the end-user. 155 authorization server 157 The server issuing tokens to the OAuth 2.0 client or SIP Client 158 after successfully authenticating the resource owner and 159 obtaining authorization. 161 Identity Provider (IdP) 163 This definition is borrowed from [MITKB] 165 "IdP (Identity Provider), is a system that creates, maintains, 166 and manages identity information for principals (users, 167 services, or systems) and provides principal authentication to 168 other service providers (applications) within a federation or 169 distributed network. It is a trusted third party that can be 170 relied upon by users and servers when users and servers are 171 establishing a dialog that must be authenticated. The IdP 172 sends an attribute assertion containing trusted information 173 about the user to the SP". 175 1.3. ID Token 177 ID token, as defined in the OpenID document, is a security token that 178 contains claims about the authentication of an end-user by an 179 authorization server. 181 1.4. SIP User Agent Types 183 [RFC6749] defines two types of clients, confidential and public, that 184 apply to the SIP User Agents. 186 o Confidential User Agent: is a SIP UA that is capable of 187 maintaining the confidentiality of the user credentials and any 188 tokens obtained using these user credentials. 190 o Public User Agent: is a SIP UA that is incapable of maintainings 191 the confidentiality of the user credentials and any obtained 192 tokens. 194 1.5. Authentication Types 196 There are two types of user authentications in SIP: 198 o Proxy-to-User: which allows a server that is providing a service 199 to authenticate the identity of a user before providing the 200 service. 202 o User-to-User: which allows a user receiving a request to 203 authenticate the identity of the remote user before processing the 204 request. 206 The mechanism defined in this document addresses the proxy-to-user 207 authentication only. For user-to-user authentication refer to the 208 mechanism defined in [STIR]. 210 2. Authentication using the Authorization Code Flow 212 Authorization Code Flow is used by the SIP UA to authenticate to a 213 third-party IdP entity to obtain an authorization code that would be 214 later used by the SIP Proxy to obtain tokens to allow the SIP UA to 215 register and get service from the SIP network. 217 2.1. Public UA with Rich UI 219 The following figure provides a high level view of flow of messages 220 for the user authentication using a Public UA that has a rich UI that 221 would prompt the user for his credentials: 223 User Proxy Authorization 224 Agent Server 225 --------------------------------------------------------------------- 226 | | | 227 | F1 REGISTER | | 228 |------------------------------>| | 229 | F2 401 Unauthorized | | 230 |<------------------------------| | 231 | | | 232 | | | 233 The UA prompts the user to provide his/her credentials. | 234 The UA then, as per OAuth 2.0 protocol, authenticates the user to | 235 the AuthZ server, and obtains an authorization code, which the UA | 236 will later hand to the Proxy. | 237 |<------------------------------------------------------------->| 238 | | | 239 | | | 240 | F3 REGISTER [authz code] | | 241 |------------------------------>| | 242 | | | 243 | | The proxy will then use the | 244 | | authz code to obtain tokens | 245 | | from the authz server | 246 | |<----------------------------->| 247 | | | 248 | F4 200 OK | | 249 |<------------------------------| | 250 | | | 251 Both the proxy and the UA will then create a shared-key based on | 252 the from-tag, to-tag, and call-id are taken from the 200 OK | 253 | | | 255 The UA initially sends a REGISTER request (F1) without providing any 256 credentials. The proxy redirects the UA by responding with 401 257 Unauthorized (F2). 259 The UA will then contact the Authorization Server and obtain an 260 authorization code to be used with the SIP proxy. 262 The UA then retries the request (F3) and includes the authorization 263 code in the body of the request. 265 The proxy then contacts the Authorization Server and exchanges the 266 authorization code for tokens. If the proxy is successful in 267 exchanging the authorization code with the tokens, the proxy then 268 replies with 200 OK to complete the registration process, and locally 269 generates the shared-key with the UA for this user. 271 When the UA receives the 200 OK, it will follow the same procedure 272 used by the proxy and calculate its shared-key locally. 274 2.1.1. Registration 276 The UA initiates the process by sending a REGISTER request (F1) to 277 the proxy. The proxy will redirect the UA to the Authorization 278 Server by responding with 401 Unauthorized (F2) that includes the 279 address of the Authorization Server in the form of an HTTP URI in a 280 Location header field, as defined in RFC7231, section 7.1.2. 282 [[OPEN ISSUE]] The above text suggests defining a new Location header 283 to carry the authorization server URL. Is that reasonable? other 284 ideas? 286 The UA will then contact the Authorization Server and obtain an 287 authorization code to be used with the SIP proxy. The method used by 288 the UA to obtain the code is out of scope for this document. 290 The UA will then send a new REGISTER request (F3) and include the 291 authorization code in the body of the request with the following 292 parameters: 294 grant_type (REQUIRED) 296 Value MUST be set to "authorization_code". 298 code (REQUIRED) 300 The authorization code received from the authorization server. 302 The proxy then contacts the Authorization Server and exchanges the 303 authorization code for access token, refresh token, and maybe ID 304 token. The method used by the UA to obtain the tokens is out of 305 scope for this document. 307 If the proxy is successful in exchanging the authorization code with 308 the tokens, the proxy then responds with 200 OK (F4) to the UA to 309 complete the registration process. 311 2.1.2. Shared-Key 313 After sending the 200 OK to the UA to complete the registration 314 process, the proxy and the UA use the HMAC-SHA256(key, message) to 315 calculates the shared-key associated with this user as follows: 317 key 319 The authorization code obtained from the Authorization Server. 321 message 323 The concatenation of the 'from-tag', 'to-tag', and 'call-id' of 324 the 200 OK that completes the registration process. 326 This shared-key will be used to allow the UA to re-register to the 327 proxy, in case of a connection loss to the proxy, without the need to 328 obtain a new code or prompt the user for his credentials. 330 2.1.3. Re-Registration Requests 332 When the UA loses its connection to the proxy and it wants to send a 333 new registration request to the proxy, the UA will send a new 334 REGISTER request and include the proof-of-possession (pop) of the 335 shared-key in the body of the request: 337 grant_type (REQUIRED) 339 Value MUST be set to "proof_of_possession". 341 pop (REQUIRED) 343 The pop calculated the first time the UA registered with the 344 proxy. 346 The pop is calculated using the shared-key as follows: 348 pop = HMAC-SHA256(shared-key, digest-string) 350 See rfc4474, section 9, for the SIP headers to hash to create digest- 351 string. 353 [[OPEN ISSUE]] Is there any issue with using digest-string as defined 354 in RFC4474? 356 [[OPEN ISSUE]] Should pop not be limited to re-registration, and 357 instead be used with all subsequent requests? If the answer is yes, 358 a new header should be defined to carry the pop instead of carrying 359 it in the payload. 361 2.1.4. Token Refresh 363 Before the tokens expire, the proxy makes a refresh request to the 364 Authorization Server to try to obtain new tokens. The method used by 365 the UA to refresh the tokens is out of scope for this document. 367 If the proxy fails to refresh the tokens, then it MUST challenge the 368 next request from the UA, and as a result the UA MUST go through the 369 authorization process again. 371 2.2. Public UA with Limited UI 373 The following figure provides a high level view of flow of messages 374 for the user authentication using a Public UA that has a limited UI 375 that cannot prompt the user for his credentials. 377 This use case requires the user to use his browser to authenticate to 378 the Authorization Server and obtain a short lived numeric 379 authorization code that would be used by the phone to register with 380 the SIP proxy. 382 User Proxy Authorization 383 Agent Server 384 --------------------------------------------------------------------- 385 | | | 386 The UA collects the numeric code from the user through the key-pad| 387 | | | 388 | | | 389 | F1 REGISTER [code] | | 390 |------------------------------>| | 391 | | | 392 | | The proxy will then use the | 393 | | authz code to obtain an access| 394 | | token and refresh token | 395 | |<----------------------------->| 396 | | | 397 | F2 200 OK | | 398 |<------------------------------| | 399 | | | 401 2.2.1. Registration 403 The UA will send a REGISTER request (F1) and include the code in the 404 body of the request with the following parameters: 406 grant_type (REQUIRED) 408 Value MUST be set to "authorization_code". 410 code (REQUIRED) 412 The code received from the authorization server through the 413 browser. 415 The proxy then contacts the Authorization Server and exchanges the 416 authorization code for access token, refresh token, and maybe an ID 417 token. The method used by the UA to obtain the tokens is out of 418 scope for this document. 420 If the proxy is successful in exchanging the authorization code with 421 the tokens, the proxy then responds with 200 OK (F2) to the UA to 422 complete the registration process. 424 2.2.2. Shared-Key 426 After sending the 200 OK to the UA to complete the registration 427 process, the proxy and the UA use the HMAC-SHA256(key, message) to 428 calculates the shared-key associated with this user as follows: 430 key 432 The authorization code obtained from the Authorization Server. 434 message 436 The concatenation of the 'from-tag', 'to-tag', and 'call-id' of 437 the 200 OK that completes the registration process. 439 This shared-key will be used to allow the UA to re-register to the 440 proxy, in case of a connection loss to the proxy, without the need to 441 obtain a new authorization code. 443 2.2.3. Token Refresh 445 Before the tokens expire, the proxy makes a refresh request to the 446 Authorization Server to try to obtain new tokens. The method used by 447 the UA to refresh the tokens is out of scope for this document. 449 If the proxy fails to refresh the tokens, then it MUST challenge the 450 next request from the UA, and as a result the UA MUST go through the 451 authorization process again. 453 2.2.4. Re-Registration Requests 455 When the UA loses its connection to the proxy and it wants to send a 456 new registration request to the proxy, the UA will send a new 457 REGISTER request and include the proof-of-possession (pop) of the 458 shared-key in the body of the request: 460 grant_type (REQUIRED) 462 Value MUST be set to "proof_of_possession". 464 pop (REQUIRED) 466 The pop calculated the first time the UA registered with the 467 proxy. 469 The pop is calculated using the shared-key as follows: 471 pop = HMAC-SHA256(shared-key, digest-string) 473 See rfc4474, section 9, for the SIP headers to hash to create digest- 474 string. 476 [[OPEN ISSUE]] Should this be not limited to re-registration, and 477 instead be used with all subsequent requests? 479 3. Authentication using the Resource Owner Password Credentials flow 481 The resource owner password credentials flow is used by a 482 Confidential UA with rich UI to authenticate to a third-party IdP 483 entity and to directly obtain tokens to be able to register and get 484 service from the SIP network. 486 3.1. Overview 488 The following figure provides a high level view of flow of messages 489 for the OAuth Resource Owner Password Credentials flow: 491 User Proxy Authorization 492 Agent Server 493 --------------------------------------------------------------------- 494 | | | 495 The UA contacts the authorization server and authenticates the | 496 user, and as a result obtains an access and refresh tokens. | 497 | | | 498 |<------------------------------------------------------------->| 499 | | | 500 | | | 501 | F1 REGISTER Authorization: Bearer access_token= | 502 |------------------------------>| | 503 | | | 504 | | The proxy validates the token | 505 | | Optional introspection step | 506 | |<----------------------------->| 507 | | | 508 | F2 200 OK | | 509 |<------------------------------| | 510 | | | 512 3.2. Registration 514 The UA first contacts the Authorization Server to authenticate the 515 user and obtain tokens to be used to get access to the SIP network. 516 The method used by the UA to obtain the tokens is out of scope for 517 this document. 519 The UA starts the registration process with the SIP proxy by sending 520 a REGISTER request (F1) with the access token it obtained previously. 522 The UA includes an Authorization header field with the Bearer scheme 523 in the request to carry the access token obtained previously. 525 The proxy then validates the token, and MAY perform an introspection 526 step to get more information about the token and its scope. The 527 introspection step is out of scope for this document. 529 When the proxy is satisfied with the token, it then replies with the 530 200 OK to complete the registration process. 532 3.3. Subsequent Requests 534 All subsequent requests from the UA MUST include a valid access 535 token. The UA MUST obtain a new access token before the access token 536 expiry period to continue to get service from the system. 538 4. Authorization Header Syntax 540 This section describes the syntax of the authorization header with 541 the Bearer scheme. 543 Authorization = "Authorization" HCOLON "Bearer" LWS 544 "access_token" EQUAL access_token 545 access_token = quoted-string 547 5. Security Considerations 549 551 6. IANA Considerations 553 555 7. Acknowledgments 557 559 8. Normative References 561 [MITKB] "IdP (Identity Provider)", MIT Knowledge 562 Base, http://kb.mit.edu/confluence/x/XoK2, March 2011. 564 [OPENID] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 565 C. Mortimore, "OpenID Connect Core 1.0", February 2014. 567 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 568 Requirement Levels", BCP 14, RFC 2119, March 1997. 570 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, H., Johnston, 571 A., Peterson, J., Sparks, R., Handley, M., and E. 572 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 573 June 2002. 575 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 576 RFC 6749, October 2012. 578 [RFC7662] Richer, J., "OAuth 2.0 Token Introspection", RFC 7662, 579 October 2015. 581 Authors' Addresses 583 Rifaat Shekh-Yusef (editor) 584 Avaya 585 250 Sidney Street 586 Belleville, Ontario 587 Canada 589 Phone: +1-613-967-5176 590 EMail: rifaat.ietf@gmail.com 591 Christer Holmberg 592 Ericsson 593 Hirsalantie 11 594 Jorvas 02420 595 Finland 597 EMail: christer.holmberg@ericsson.com 599 Victor Pascual 600 webrtchacks 601 Spain 603 EMail: victor.pascual.avila@gmail.com