idnits 2.17.1 draft-yusef-sipcore-sip-oauth-03.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 : ---------------------------------------------------------------------------- == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. -- 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 (March 8, 2016) is 2942 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 315, but not defined == Missing Reference: 'DIGEST' is mentioned on line 909, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'OPENID' Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIPCore R. Shekh-Yusef, Ed. 3 Internet-Draft Avaya 4 Updates: 3261 (if approved) V. Pascual 5 Intended status: Standards Track Oracle 6 Expires: September 9, 2016 C. Holmberg 7 Ericsson 8 March 8, 2016 10 The Session Initiation Protocol (SIP) OAuth 11 draft-yusef-sipcore-sip-oauth-03 13 Abstract 15 This document defines an authorization framework for SIP that is 16 based on the OAuth 2.0 framework, and adds a simple identity layer on 17 top of that, based on the OpenID Connect Core 1.0, to enable Clients 18 to verify the identity of the End-User based on the authentication 19 performed by an Authorization Server, as well as to obtain basic 20 profile information about the End-User. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 9, 2016. 39 Copyright Notice 41 Copyright (c) 2016 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 This document may contain material from IETF Documents or IETF 55 Contributions published or made publicly available before November 56 10, 2008. The person(s) controlling the copyright in some of this 57 material may not have granted the IETF Trust the right to allow 58 modifications of such material outside the IETF Standards Process. 59 Without obtaining an adequate license from the person(s) controlling 60 the copyright in such materials, this document may not be modified 61 outside the IETF Standards Process, and derivative works of it may 62 not be created outside the IETF Standards Process, except to format 63 it for publication as an RFC or to translate it into languages other 64 than English. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 69 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 70 1.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 71 1.3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 4 72 1.3.1. Enterprise SSO . . . . . . . . . . . . . . . . . . . 4 73 1.3.2. 3GPP . . . . . . . . . . . . . . . . . . . . . . . . 5 74 1.3.3. Confidential SIP Hardphone . . . . . . . . . . . . . 5 75 1.3.4. Public SIP Hardphone . . . . . . . . . . . . . . . . 5 76 1.3.5. SIP SSO . . . . . . . . . . . . . . . . . . . . . . . 6 77 1.4. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 1.5. ID Token . . . . . . . . . . . . . . . . . . . . . . . . 7 79 1.6. Authentication Types . . . . . . . . . . . . . . . . . . 8 80 2. Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . 8 81 2.1. Single Sign-On . . . . . . . . . . . . . . . . . . . . . 8 82 2.2. Service Authorization . . . . . . . . . . . . . . . . . . 8 83 2.3. Third-Party Authentication . . . . . . . . . . . . . . . 9 84 3. Authorization Code Grant type . . . . . . . . . . . . . . . . 9 85 3.1. Operations Overview . . . . . . . . . . . . . . . . . . . 9 86 3.2. Authentication . . . . . . . . . . . . . . . . . . . . . 12 87 3.3. Registration . . . . . . . . . . . . . . . . . . . . . . 13 88 3.4. Subsequent Requests . . . . . . . . . . . . . . . . . . . 14 89 3.5. Token Refresh . . . . . . . . . . . . . . . . . . . . . . 14 90 3.6. Services . . . . . . . . . . . . . . . . . . . . . . . . 15 91 4. Implicit Grant Type . . . . . . . . . . . . . . . . . . . . . 16 92 4.1. OAuth Implicit Grant . . . . . . . . . . . . . . . . . . 16 93 4.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 16 94 4.1.2. Authentication . . . . . . . . . . . . . . . . . . . 17 95 4.1.3. Registration . . . . . . . . . . . . . . . . . . . . 18 96 4.1.4. Subsequent Requests . . . . . . . . . . . . . . . . . 19 97 4.1.5. Services . . . . . . . . . . . . . . . . . . . . . . 19 98 4.2. OpenID Implicit Grant . . . . . . . . . . . . . . . . . . 20 99 5. Resource Owner Password Credentials Grant type . . . . . . . 21 100 5.1. Operations Overview . . . . . . . . . . . . . . . . . . . 21 101 5.2. Registration and Acquiring Tokens . . . . . . . . . . . . 22 102 5.3. Discarding Credentials . . . . . . . . . . . . . . . . . 23 103 5.4. Token Refresh . . . . . . . . . . . . . . . . . . . . . . 23 104 5.5. Authenticated Requests . . . . . . . . . . . . . . . . . 23 105 5.6. Examples . . . . . . . . . . . . . . . . . . . . . . . . 24 106 6. Outbound . . . . . . . . . . . . . . . . . . . . . . . . . . 25 107 6.1. Authorization Code Grant type . . . . . . . . . . . . . . 25 108 6.2. Resource Owner Password Credentials Grant type . . . . . 25 109 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 110 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 111 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 112 10. Normative References . . . . . . . . . . . . . . . . . . . . 25 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 115 1. Introduction 117 The SIP protocol [RFC3261] uses the framework used by the HTTP 118 protocol for authenticating users, which is a simple challenge- 119 response authentication mechanism that allows a server to challenge a 120 client request and allows a client to provide authentication 121 information in response to that challenge. 123 The SIP protocol does not have an authorization framework to allow 124 the system to control access to various services provided by the 125 system. 127 OAuth 2.0 [RFC6749] defines a token based authorization framework to 128 allow clients to access resources on behalf of their user. It also 129 defines four types of authorization grants, which the client uses to 130 request the access token. 132 The OpenID Connect 1.0 [OPENID] specifications defines a simple 133 identity layer on top of the OAuth 2.0 protocol, which enables 134 Clients to verify the identity of the End-User based on the 135 authentication performed by an Authorization Server, as well as to 136 obtain basic profile information about the End-User. 138 This document defines an authorization framework for SIP that is 139 based on the OAuth 2.0 framework, and adds the identity layer on top 140 of that, based on the OpenID Connect Core 1.0 specification 142 1.1. Terminology 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in [RFC2119]. 148 1.2. Definitions 150 Types of SIP services: 152 * Basic SIP Services: make/receive call, transfer, call forward, 153 etc. 155 * Advanced SIP Services: services provided by SIP application 156 servers, e.g. Voice Mail, Conference Services, Presence, IM, 157 ... 159 Single Sign-On (SSO) 161 SSO is a property that allows the user to be authenticated once 162 and as a result have access to multiple services in the system. 164 Authentication 166 The process of verifying the identity of a user trying to get 167 access to some network services. 169 Authorization 171 The process of controlling an authenticated user access to 172 network services and the level of service provided to the user. 174 1.3. Use Cases 176 1.3.1. Enterprise SSO 178 An enterprise is interested in providing its users with an SSO 179 capability to the various corporate services. The enterprise has an 180 authorization server for controlling the user access to their network 181 and would like to extend that existing authorization server to 182 control the user access to the various services provided by their SIP 183 network. 185 The user is expected to provide his corporate credentials to login to 186 the corporate network and get different types of services, regardless 187 of the protocol used to provide the service, and without the need to 188 create different accounts for these different types of services. 190 1.3.2. 3GPP 192 The 3GPP network has a requirement to allow a user using a WebRTC IMS 193 Client (WIC) to authenticate to a WebRTC Authorization Function (WAF) 194 and in response be given an access token that allows the user to 195 register and get service from the 3GPP SIP network. 197 The WIC downloads an IMS webpage from the WebRTC Web Server Function 198 (WWSF) using HTTP. The WIC then requests an access token from the 199 WAF using HTTP, which the WIC then uses to register to the SIP 200 network throught the P-CSCF enhanced for WebRTC (eP-CSCF) element. 202 1.3.3. Confidential SIP Hardphone 204 A SIP hardphone with rich UI, that has the capability to maintain the 205 confidentiality of user's crecentials, is used to authenticate to an 206 authorization server, get a token, and use that token to register and 207 get service from the SIP network. 209 When the phone interacts with the authorization server and gets 210 challenged to provide credentials, the phone will prompt the user to 211 enter his credentials which will be used to authenticate to the 212 authorization server. 214 1.3.4. Public SIP Hardphone 216 A SIP hardphone with limited UI capabilities, that is incapable of 217 maintaining confidentiality of user's crecentials, is used to 218 register with the SIP network by providing an access code obtaied 219 from an authorization server. 221 When the phone interacts with the SIP network without providing any 222 credentials, the phone gets challenged to provide proper credentials. 224 The user will then use an out of band method, e.g browser, to 225 authenticate to the authorization server and get a short-lived 226 numeric access code. 228 The user will then use the phone's keypad to provide the numeric 229 access code to the SIP phone. The phone will then use the access 230 code to register and get service from the SIP network. The SIP Proxy 231 will exchange the access code with access token from the 232 authorization server. 234 1.3.5. SIP SSO 236 An enterprise is interested in providing its users with an SSO 237 capability to the various corporate SIP services. 239 The enterprise wants to control the services provided to their SIP 240 users and the level of service provided to the user by their SIP 241 application servers without the need to create different accounts for 242 these services. 244 The enterprise wants to utilize an existing authentication mechanism 245 provided by SIP, but would like to be able to control who gets access 246 to what service and when. 248 The user is expected to use his SIP credentials to login to the SIP 249 network and get access to the basic services, and to get access to 250 the services provided by the various SIP application servers without 251 being challenged to provide credentials for each type of service. 253 1.4. Roles 255 resource owner 257 An entity capable of granting access to a protected resource. 258 When the resource owner is a person, it is referred to as an 259 end-user. 261 In a typical SIP network, it is the management element in the 262 system that acts as a resource owner. 264 resource server 266 The server hosting the protected resources or services, capable 267 of accepting and responding to protected resource and services 268 requests using access tokens. 270 OAuth 2.0 client 272 An application making protected resource requests on behalf of 273 the resource owner and with its authorization. The term 274 "client" does not imply any particular implementation 275 characteristics (e.g., whether the application executes on a 276 server, a desktop, or other devices). 278 SIP client 280 An application making requests to access SIP services on behalf 281 of the end-user. 283 authorization server 285 The server issuing tokens to the OAuth 2.0 client or SIP Client 286 after successfully authenticating the resource owner and 287 obtaining authorization. 289 proof-of-possession (pop) 291 A hash used by one party to prove to another party that it is 292 in possession of some shared credentials, without sending the 293 credentials on the wire. 295 1.5. ID Token 297 ID token, as defined in the OpenID document, is a security token that 298 contains claims about the authentication of an end-user by an 299 authorization server. 301 1.6. Authentication Types 303 There are two types of user authentications in SIP: 305 o Proxy-to-User: which allows a server that is providing a service 306 to authenticate the identity of a user before providing the 307 service. 309 o User-to-User: which allows a user recieving a request to 310 authenticate the identity of the remote user before processing the 311 request. 313 The mechanism defined in this document addresses the proxy-to-user 314 authentication only. For user-to-user authentication refer to the 315 mechanism defined in [STIR]. 317 2. Benefits 319 This section describes the benefit of this authorization framework: 321 2.1. Single Sign-On 323 With the existing mechanism, the proxy and application servers might 324 need to challenge many of the requests sent by a client, which adds 325 traffic that could be avoided with this authorization mechanism. 327 Single Sign-On is a property that allows the user to be authenticated 328 once and as a result have access to multiple services in the system. 330 This authorization mechanism would enable Single Sign-On, as the user 331 will be authenticated once and as a result given a token and a 332 refresh token to allow the user access to various services based on 333 the token scope. 335 2.2. Service Authorization 337 This authorization mechanism allows the system to centrally control 338 the services provided to the user, e.g conference services, voice 339 mail, etc. The mechanism also allow control over the level of 340 services provided to the user; for example, if the user is given 341 access to conference services, the system controls whether the user 342 gets access to video conference services or only audio conference 343 services. 345 2.3. Third-Party Authentication 347 This authorization mechanism allows the user to be authenticated and 348 obtain tokens using some Third-Party Authorization mechanism and 349 still get services from the system. 351 3. Authorization Code Grant type 353 3.1. Operations Overview 355 The following figure provides a high level view of flow of messages 356 for the Authorization Code Grant type: 358 Authentication 359 -------------- 361 User Proxy Authorization 362 Agent Server 363 --------------------------------------------------------------------- 364 | | | 365 | F1 REGISTER | | 366 |------------------------------>| | 367 | F2 401 | | 368 |<------------------------------| | 369 | | | 370 | F3 GET /authorize?response_type=code&... | 371 |-------------------------------------------------------------->| 372 | | F4 401 | 373 |<--------------------------------------------------------------| 374 | | | 375 | | | 376 o master-key = HMAC-SHA256(HA1, realm + nonce) | 377 | | | 378 | F5 GET /authorize?response_type=code&... with credentials | 379 |-------------------------------------------------------------->| 380 | | | 381 | | | 382 | o master-key=HMAC-SHA256(HA1, realm + nonce) 383 | | | 384 | | F6 200 [code] | 385 |<--------------------------------------------------------------| 386 | | | 387 | | | 389 Registration 390 ------------ 392 User Proxy Authorization 393 Agent Server 394 --------------------------------------------------------------------- 395 | | | 396 | F7 REGISTER code, pop | | 397 |------------------------------>| | 398 | | F8 POST /token [code] | 399 | |------------------------------>| 400 | | | 401 | | F9 200 OK [ id-token, | 402 | | access_token, | 403 | | refresh_token] | 404 | |<------------------------------| 405 | | | 406 | | | 407 | | F10 GET /userinfo [access_token] 408 | |------------------------------>| 409 | | | 410 | | F11 200 OK [ user-info, | 411 | | master-key] | 412 | |<------------------------------| 413 | | | 414 | F12 200 OK | | 415 |<------------------------------| | 416 | | | 417 | | | 419 Subsequent Requests 420 ------------------- 422 | | | 423 o pop = HMAC-SHA256(master-key, digest-string) | 424 | | | 425 | F13 INVITE pop | | 426 |------------------------------>| | 427 | | | 428 | | | 429 | o The proxy verifies the pop. | 430 | | | 431 | F14 180 Ringing | | 432 |<------------------------------| | 433 | | | 435 Token Refresh 436 ------------- 438 User Proxy Authorization 439 Agent Server 440 --------------------------------------------------------------------- 441 | | | 442 | | F15 POST /token | 443 | | [ grant_type=refresh_token& | 444 | | refresh_token= | 445 | |------------------------------>| 446 | | | 447 | | F16 200 OK [ access_token, | 448 | | refresh_token ] | 449 | |<------------------------------| 450 | | | 451 | | | 453 The UA initially sends a REGISTER request (F1) without providing any 454 credentials. 456 The proxy challenges the UA by responding with 401 (F2) that includes 457 the address of the Authorization Server. 459 [[OPEN ISSUE]] How should the UA be redirected to the Authorization 460 Server: 1. New SIP parameter? 2. Extend the Bearer scheme? 3. 461 Define a new Scheme? 463 The UA will then contact the Authorization Server without providing 464 any credentials in the first request (F3). The Authorization Server 465 challenges the request using the Digest scheme (F4), and the client 466 retries the request (F5) and provides the user's credentials. 468 The Authorization Server verifies the request from the client; if the 469 verification is successful, the Authorization Server responds with 470 200 OK (F6) and includes a code in the body part. 472 The UA then retries the request (F7) and include the code in the body 473 of the request. The proxy then contacts the Authorization Server and 474 exchanges the code for tokens (F8 and F9), and gets the user 475 information (F10 and F11). The proxy then sends 200 OK to the UA to 476 complete the registration process. 478 3.2. Authentication 480 The UA initiates the process by sending a REGISTER request (F1) to 481 the proxy. The proxy will redirect the UA to the Authorization 482 Server by responding with 401 (F2) that includes the address of the 483 Authorization Server in the form of an HTTP URI. 485 The UA constructs the initial request (F3) to the Authorization 486 Server without providing any user credentials, but with the following 487 URI parameters in the query component: 489 response_type (REQUIRED) 491 Value MUST be set to "code". 493 user_id (REQUIRED) 495 The user's identification with the Authorization Server. 497 scope (OPTIONAL) 499 The scope of the access request 501 state (RECOMMENDED) 503 The value of this parameter is a nonce created by the client to 504 prevent replay attack. The nonce is a uniquely generated value 505 for each request. This parameter might not be included with the 506 initial request that does not include credentials (F3). 508 The Authorization Server uses the user identification specified in 509 the user_id parameter to verify that the user has an account in the 510 system, and then challenges the request by responding with 401 (F4) 511 with Digest scheme. 513 The UA will generate a master-key that is based on an HMAC-Hash 514 algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1 and 515 the concatenation of realm and nonce received in the challenge from 516 the server. 518 The UA will then send a new authorization request (F5), but this time 519 include the credentials requested by the server. The UA will use the 520 same parameters values used in the initial authorization request with 521 the exception of the state parameter which will get a new nonce 522 value. 524 When the server receives the request with the credentials (F5), the 525 server will verify the digest provided by the UA; if that is 526 successful, the server will respond with 200 OK (F6) and include a 527 code in the body of the response with the following parameters: 529 grant_type (REQUIRED) 531 Value MUST be set to "authorization_code". 533 code (REQUIRED) 535 The authorization code received from the authorization server. 537 The server then generates a master-key that is based on an HMAC-Hash 538 algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1, and 539 the concatenation of realm and nonce sent in the challenge (F4) to 540 the client. 542 3.3. Registration 544 The UA will send a new REGISTER request (F7) and include the code in 545 the body of the request with the following parameters: 547 grant_type (REQUIRED) 549 Value MUST be set to "authorization_code". 551 code (REQUIRED) 553 The authorization code received from the authorization server. 555 The proxy sends a POST request (F8) to the Authorization Server and 556 include the following parameters in the body: 558 grant_type (REQUIRED) 560 Value MUST be set to "authorization_code". 562 code (REQUIRED) 564 The authorization code received from the authorization server. 566 If the request is valid and authorized, the authorization server 567 responds with a 200 OK (F9) with id_token, access token, and 568 refresh_token in the body. 570 The UA sends a GET request (F10) to the Authorization Server to fetch 571 the user information, and includes the access token in the body of 572 the request. In response the Autorization Server will respond with 573 200 OK and include the user information and the master-key associated 574 with the user in the body part. 576 The proxy then responds with 200 OK (F12) to the UA to complete the 577 registration process. 579 3.4. Subsequent Requests 581 When the UA wants to send any request to the proxy, it MUST include 582 the Authorization header and use the Bearer scheme to carry the 583 proof-of-possession of the master-key. 585 The pop is calculated using the master-key as follows: 587 pop = HMAC-SHA256(master-key, digest-string) 589 The following is an example of an Authorization header with Bearer 590 scheme: 592 Authorization: Bearer pop= 594 See rfc4474, section 9, for the SIP headers to hash to create digest- 595 string. 597 [[OPEN ISSUE]] The Bearer scheme is used to deliver tokens without 598 providing any proof of possession. We probably need to use different 599 scheme later on. 601 3.5. Token Refresh 603 The proxy makes a refresh request to the Authorization Server by 604 sending a refresh POST request (F13) that includes a body with the 605 grant_type and the refresh_token. 607 For example: 609 grant_type=refresh_token&refresh_token= 611 If the proxy fails to refresh the token, then it MUST challenge the 612 next request from the UA, and as a result the UA MUST go through the 613 authorization process again to obtain new tokens. 615 3.6. Services 617 When the UA tries to access a service on behalf of a user, e.g. 618 Voice Mail Service, the proxy forwards the request to the server 619 providing the service and MUST include an Authorization header with 620 the Bearer scheme that carries the token needed to get service, as 621 follows: 623 Authorization: Bearer token= 625 4. Implicit Grant Type 627 The impicit grant type is used by the SIP UA to directly obtain 628 access tokens from the Authorization Server to be able to register 629 and get service from the SIP network. 631 This grant type does not support the issuance of refresh tokens, 632 which means that the SIP UA must re-authenticate again to the 633 Authorization Server to get a new token before the current token 634 expires. 636 4.1. OAuth Implicit Grant 638 4.1.1. Overview 640 The following figure provides a high level view of flow of messages 641 for the OAuth Implicit Grant type: 643 Authentication 644 -------------- 646 User Proxy Authorization 647 Agent Server 648 --------------------------------------------------------------------- 649 | | | 650 | F1 GET /authorize?response_type=token... | 651 |-------------------------------------------------------------->| 652 | | | 653 | | F2 401 | 654 |<--------------------------------------------------------------| 655 | | | 656 | | | 657 | F3 GET /authorize?response_type=token +credentials | 658 |-------------------------------------------------------------->| 659 | | | 660 | | F4 200 OK [access_token] | 661 |<--------------------------------------------------------------| 662 | | | 664 Registration 665 ------------ 667 | | | 668 | F5 REGISTER username@domain.com, access_token | 669 |------------------------------>| | 670 | | F6 POST /introspect | 671 | | [token=] | 672 | |------------------------------>| 673 | | | 674 | | F7 200 OK | 675 | |<------------------------------| 676 | F8 200 OK | | 677 |<------------------------------| | 678 | | | 680 4.1.2. Authentication 682 The UA starts the process by sending an HTTP GET request to the 683 Authorization Server without providing any credentials in the first 684 request (F1). 686 The UA constructs the initial request (F1) to the Authorization 687 Server with the following URI parameters in the query component: 689 response_type (REQUIRED) 691 Value MUST be set to "token". 693 user_id (REQUIRED) 695 The user's identification with the Authorization Server. 697 scope (OPTIONAL) 699 The scope of the access request. 701 The Authorization Server challenges the request using the Digest 702 scheme (F2). The client retries the request (F3) and provides the 703 user's credentials. In response the Authorization Server responds 704 with 200 OK (F4) with the Access Token in the body. 706 4.1.3. Registration 708 The UA starts the registration process with the SIP proxy by sending 709 a REGISTER request (F5) with the access token it obtained in the 710 previous steps (F1-F4). 712 The UA adds the following parameters to the body of the REGISTER 713 request: 715 access_token (REQUIRED) 717 The access token issued by the authorization server. 719 token_type (REQUIRED) 721 The type of the token issued by the authorization server. Value 722 is case insensitive. 724 expires (RECOMMENDED) 726 The lifetime in seconds of the access token. 728 scope (OPTIONAL) 730 The scope of the access request. 732 If introspection is used [RFC7662], then the proxy validates the 733 access token by sending an HTTP POST request (F6), with the 734 parameters sent as "application/x-www-form-urlencoded" data, to the 735 Authorization Server and include the following parameters: 737 token (REQUIRED) 739 The string value of the token. 741 token_type_hint (OPTIONAL) 743 A hint about the type of the token submitted for introspection. 745 Authorization Server then validates the request and responds with 200 746 OK (F7), with a JSON object in the body with the following 747 parameters: 749 active (REQUIRED) 751 Boolean indicator of whether or not the presented token is 752 currently active. 754 scope (OPTIONAL) 756 The scope of the access request. 758 Other parameters 760 TBD. 762 4.1.4. Subsequent Requests 764 All subsequent requests from the UA MUST include a valid access 765 token. The UA MUST obtain a new access token before the access token 766 expiry period to continue to get service from the system. 768 4.1.5. Services 770 When the proxy forwards a request from a UA to an application server, 771 it makes sure to keep the access token and scope in the message to 772 allow the application server to provide the proper service to the 773 user. 775 4.2. OpenID Implicit Grant 777 The following figure provides a high level view of flow of messages 778 for the OpenID Implicit Grant type: 780 User Proxy Authorization 781 Agent Server 782 --------------------------------------------------------------------- 783 | | | 784 | F1 GET /authorize?response_type=id_token%20token... | 785 |-------------------------------------------------------------->| 786 | | | 787 | | F2 401 | 788 |<--------------------------------------------------------------| 789 | | | 790 | F3 GET /authorize?response_type=id_token%20token +credentials | 791 |-------------------------------------------------------------->| 792 | | | 793 | | F4 200 OK [ id-token, | 794 | | access_token] | 795 |<--------------------------------------------------------------| 796 | | | 797 | F5 GET /userinfo [access_token] | 798 |-------------------------------------------------------------->| 799 | | | 800 | | F6 200 OK [ user-info] | 801 |<--------------------------------------------------------------| 802 | | | 803 | F7 REGISTER username@domain.com, access_token | 804 |------------------------------>| | 805 | | | 806 | | F8 POST /authorize | 807 | | [token=access_token ] | 808 | |------------------------------>| 809 | | | 810 | | F9 200 OK | 811 | |<------------------------------| 812 | | | 813 | F10 200 OK | | 814 |<------------------------------| | 815 | | | 817 5. Resource Owner Password Credentials Grant type 819 5.1. Operations Overview 821 The following figure provides a high level view of flow of messages 822 for the Resource Owner Password Credentials Grant type: 824 UA Proxy 825 -------------------------------------------------------------------- 826 | | 827 | F1 REGISTER | 828 |------------------------------------------------------------->| 829 | | 830 | F2 401 WWW-Authenticate: Digest | 831 |<-------------------------------------------------------------| 832 | | 833 | | 834 o master-key = HMAC-SHA256(HA1, realm + nonce) | 835 | | 836 | F3 REGISTER with Authorization | 837 |------------------------------------------------------------->| 838 | | 839 | | 840 | o master-key = HMAC-SHA256(HA1, realm + nonce) 841 | | 842 | F4 200 OK [token, expires, ...] | 843 |<-------------------------------------------------------------| 844 | | 845 | | 846 o pop = HMAC-SHA256(master-key, token + digest-string) | 847 | | 848 | F5 INVITE token, pop | 849 |------------------------------------------------------------->| 850 | | 851 | o The server verifies the pop. 852 | | 853 | F6 180 Ringing | 854 |<-------------------------------------------------------------| 855 | | 857 During registration the UA initially sends a REGISTER request (F1) 858 without providing any credentials. 860 The proxy then challenges the UA by responding with 401 (F2) that 861 includes the Digest scheme in the www-authenticate header. 863 The UA will generate a master-key that is based on an HMAC-Hash 864 algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1 and 865 the concatenation of realm and nonce received in the challenge from 866 the server. The UA will continue to use the existing operation of 867 handling the Digest challenge and then sends a new REGISTER request 868 (F3) with the credentials to the server. 870 When the server receives the request with the credentials (F3), the 871 server will verify the digest provided by the UA; if that is 872 successful, the server will accept the registration (F4) and include 873 the details of the token in the response. 875 The server then generates a master-key that is based on an HMAC-Hash 876 algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1, and 877 the concatenation of realm and nonce sent in the challenge to the 878 client. 880 At the end of the above process the UA would have registered with the 881 proxy and both the UA and the proxy would have created the same 882 master-key without sending the master-key on the wire. 884 Later when the UA wants to send a request to the proxy it MUST always 885 include the token and SHOULD include the pop as defined in section 886 4.6. 888 5.2. Registration and Acquiring Tokens 890 The UA MUST request the access token during the registration process 891 with the proxy, by including a body with the grant_type as 892 "password". Initially, the UA sends a REGISTER request without 893 providing any credentials. 895 The proxy MUST then challenge the UA by responding with 401 with the 896 Digest scheme in the WWW-Authenticate header. 898 When the UA gets challenged by the proxy to provide its credentials, 899 the UA MUST include its credentials in the new REGISTER request in 900 the authorization header as it is done with the existing mechanism, 901 and MUST include a body with the grant_type as "password". 903 In addition, the UA MUST generate a master-key as follows: 905 master-key = HMAC-SHA256(HA1, realm + nonce) 907 Where 909 o HA1 - this is the user's H(A1) as defined in [DIGEST]. 911 o realm - this is the realm that is returned by the server in the 912 response to the initial request from the UA. 914 o nonce - this is the nonce that is returned by the server in the 915 response to the initial request from the UA. 917 When the server receives the request with the credentials, the server 918 will verify the digest provided by the UA; if that is successful, the 919 server will accept the registration and include the details of the 920 token in the response. 922 [[OPEN ISSUE]] How should the tokens be transported to the UA? in the 923 body of the 200 OK? or a SIP header? 925 The server then generates a master-key following the same procedure 926 followed by the client. 928 As a result of this procedure both the UA and the server would have 929 created the same master-key without sending the master-key on the 930 wire. 932 5.3. Discarding Credentials 934 After successfully receiving the access and refresh tokens from the 935 proxy, the UA SHOULD discard the user credentials. 937 5.4. Token Refresh 939 The UA makes a refresh request to the token by sending a refresh 940 REGISTER request that includes the authorization header and a body 941 with the grant_type, the refresh_token, and the proof-of-possession 942 of the master-key. 944 For example: 946 grant_type=refresh_token&refresh_token=&pop= 948 5.5. Authenticated Requests 950 When the UA wants to send any request to the proxy, it MUST include 951 the Authorization header and use the Bearer scheme to carry the 952 access token, and the proof-of-possession of the master-key. 954 For example: 956 Authorization: Bearer token=, pop= 958 See rfc4474, section 9, for the SIP headers to hash to create the 959 value for the proof. 961 [[OPEN ISSUE]] The Bearer scheme is used to deliver tokens without 962 providing any proof of possession. We probably need to use different 963 scheme later on. 965 5.6. Examples 967 REGISTER sip:registrar.biloxi.com SIP/2.0 968 Via: SIP/2.0/TCP bobspc.biloxi.com:5060;branch=z9hG4bKnashds7 969 Max-Forwards: 70 970 To: Bob 971 From: Bob ;tag=456248 972 Call-ID: 843817637684230@998sdasdh09 973 CSeq: 1826 REGISTER 974 Contact: 975 Expires: 7200 976 Content-Length: 19 978 grant_type=password&pop= 980 SIP/2.0 200 OK 981 Via: SIP/2.0/TCP bobspc.biloxi.com:5060;branch=z9hG4bKnashds7 982 ;received=192.0.2.4 983 To: Bob ;tag=2493k59kd 984 From: Bob ;tag=456248 985 Call-ID: 843817637684230@998sdasdh09 986 CSeq: 1826 REGISTER 987 Contact: 988 Expires: 7200 989 Content-Length: 0 991 { 992 "access_token":"2YotnFZFEjr1zCsicMWpAA", 993 "token_type":"example", 994 "expires_in":3600, 995 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 996 "example_parameter":"example_value" 997 } 999 6. Outbound 1001 RFC5626 defines a mechanism that allows a UA to simultaneously 1002 connect and establish registration with multiple outbound proxies to 1003 get service. 1005 This section describes that impact of outbound on this authorization 1006 mechanism. 1008 6.1. Authorization Code Grant type 1010 During initial registration with the primary proxy, the UA is able to 1011 get an authorization code that it will use to register with the 1012 primary proxy. Assuming the authorization server is shared between 1013 the various outbound proxies, the UA will be able to use the same 1014 authorization code to register with the secondary proxies and as a 1015 result each one of the secondary proxies will get the master-key 1016 associated with the user to be used for the calculation of the proof- 1017 of-possession. 1019 6.2. Resource Owner Password Credentials Grant type 1021 During registration the proxy challenges the UA, and both the proxy 1022 and the UA create a master-key based on HA1, realm, and nonce. Since 1023 the nonce is not shared between the various proxies, it is not 1024 possible for the outbound proxies to use the same master-key; as a 1025 result, the UA is expected to maintain a master-key and token per 1026 outbound proxy. 1028 7. Security Considerations 1030 1032 8. IANA Considerations 1034 1036 9. Acknowledgments 1038 1040 10. Normative References 1042 [OPENID] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 1043 C. Mortimore, "OpenID Connect Core 1.0", February 2014. 1045 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1046 Requirement Levels", BCP 14, RFC 2119, March 1997. 1048 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, H., Johnston, 1049 A., Peterson, J., Sparks, R., Handley, M., and E. 1050 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 1051 June 2002. 1053 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 1054 RFC 6749, October 2012. 1056 [RFC7662] Richer, J., "OAuth 2.0 Token Introspection", RFC 7662, 1057 October 2015. 1059 Authors' Addresses 1061 Rifaat Shekh-Yusef (editor) 1062 Avaya 1063 250 Sidney Street 1064 Belleville, Ontario 1065 Canada 1067 Phone: +1-613-967-5267 1068 EMail: rifaat.ietf@gmail.com 1070 Victor Pascual 1071 Oracle 1072 Spain 1074 EMail: victor.pascual.avila@oracle.com 1076 Christer Holmberg 1077 Ericsson 1078 Hirsalantie 11 1079 Jorvas 02420 1080 Finland 1082 EMail: christer.holmberg@ericsson.com