SIPCORE Working Group R. Shekh-Yusef, Ed. INTERNET-DRAFT Avaya Intended Status: Standards Track V. Pascual Expires: November 27, 2014 Quobis May 26, 2014 The Session Initiation Protocol (SIP) OAuth draft-yusef-sipcore-sip-oauth-00 Abstract The Session Initiation Protocol (SIP) uses a challenge-response framework to authenticate the user, but it does not have an authorization framework to control the user's access to various services in the system. This document defines an authorization framework for SIP that is based on the OAuth 2.0 framework. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Copyright and License Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. Shekh-Yusef Expires November 27, 2014 [Page 1] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) 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 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 2 OAuth 2.0 Roles . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1 Resource Owner . . . . . . . . . . . . . . . . . . . . . . 4 2.2 Resource Server . . . . . . . . . . . . . . . . . . . . . . 4 2.3 Client . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.4 Authorization Server . . . . . . . . . . . . . . . . . . . 4 3 Authorization Code Grant type . . . . . . . . . . . . . . . . . 5 3.1 Operations Overview . . . . . . . . . . . . . . . . . . . . 5 3.2 Registration . . . . . . . . . . . . . . . . . . . . . . . 7 3.3 Authorization . . . . . . . . . . . . . . . . . . . . . . . 7 3.4 Acquiring Access Token . . . . . . . . . . . . . . . . . . 8 3.5 Token Refresh . . . . . . . . . . . . . . . . . . . . . . . 9 3.6 Authenticated Requests . . . . . . . . . . . . . . . . . . 9 4 Resource Owner Password Credentials Grant type . . . . . . . . 11 4.1 Operations Overview . . . . . . . . . . . . . . . . . . . . 11 4.2 Registration and Acquiring Tokens . . . . . . . . . . . . . 12 4.3 Discarding Credentials . . . . . . . . . . . . . . . . . . 13 4.4 Token Refresh . . . . . . . . . . . . . . . . . . . . . . . 13 4.5 Authenticated Requests . . . . . . . . . . . . . . . . . . 13 4.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 14 5 Client Credentials Grant . . . . . . . . . . . . . . . . . . . 15 5.1 Registration . . . . . . . . . . . . . . . . . . . . . . . 15 5.2 Authorization . . . . . . . . . . . . . . . . . . . . . . . 16 6 Security Considerations . . . . . . . . . . . . . . . . . . . . 17 7 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 17 8 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 17 9 References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 9.1 Normative References . . . . . . . . . . . . . . . . . . . 17 9.2 Informative References . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 Shekh-Yusef Expires November 27, 2014 [Page 2] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 1 Introduction The SIP protocol [RFC3261] uses the framework used by the HTTP protocol for authenticating users, which is a simple challenge- response authentication mechanism that allows a server to challenge a client request and allows a client to provide authentication information in response to that challenge. The SIP protocol does not have an authorization framework to allow the system to control access to various services provided by the system. OAuth 2.0 [RFC6749] defines a token based authorization framework to allow clients to access resources on behalf of their user. It also defines four types of authorization grants, which the client uses to request the access token. This document defines a new authorization mechanism for SIP that is based on the OAuth 2.0 protocol. The new mechanism allows the proxy to avoid challenging every request from the client. The use of tokens is a Single Sing-On enabler, which allows for the definition of fine grained scopes that could be used by proxies and application servers to authorize clients to perform certain actions of behalf of the user but not others. 1.1 Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. Shekh-Yusef Expires November 27, 2014 [Page 3] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 2 OAuth 2.0 Roles 2.1 Resource Owner An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user. 2.2 Resource Server The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens. The Proxy will play this role with SIP. 2.3 Client An application making protected resource requests on behalf of the resource owner and with its authorization. The term "client" does not imply any particular implementation characteristics (e.g., whether the application executes on a server, a desktop, or other devices). 2.4 Authorization Server The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization. The Registrar will play this role with SIP when first-party authentication is used. [[OPEN ISSUE]] The rest of the document assumes that the Authorization Server plays two roles: the Authorization Endpoint role and the Token Endpoint role. Do we need to consider separating them? Shekh-Yusef Expires November 27, 2014 [Page 4] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 3 Authorization Code Grant type 3.1 Operations Overview The following figure provides a high level view of flow of messages for the Authorization Code Grant type: User Proxy Authorization Agent Server --------------------------------------------------------------------- | | | | REGISTER username@domain.com | | |------------------------------>| | | 302 | | |<------------------------------| | | | | | GET /authorize?response_type=code&... | |-------------------------------------------------------------->| | | 401 | |<--------------------------------------------------------------| | | | | | | o master-key = HMAC-SHA256(HA1, realm + nonce) | | | | | GET /authorize?response_type=code&... with credentials | |-------------------------------------------------------------->| | | | | | | | o master-key=HMAC-SHA256(HA1, realm + nonce) | | | | | 302 [code] | |<--------------------------------------------------------------| | | | | | | | REGISTER username@domain.com & code | |------------------------------>| | | | POST /token [code] | | |------------------------------>| | | 200 OK [ token, | | | refresh token, | | | master-key] | | |<------------------------------| | 200 OK | | |<------------------------------| | | | | | | | Shekh-Yusef Expires November 27, 2014 [Page 5] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 Subsequent Requests | | | o pop = HMAC-SHA256(master-key, some-request-headers) | | | | | INVITE pop | | |------------------------------>| | | | | | | | | o The proxy verifies the pop. | | | | | 180 Ringing | | |<------------------------------| | | | | Token Refresh | | | | | POST /token | | | [ grant_type=refresh_token& | | | refresh_token= | | |------------------------------>| | | 200 OK [ token, | | | refresh_token ] | | |<------------------------------| | | | During registration the UA initially sends a REGISTER request without providing any credentials. The registrar then redirect the UA by responding with 302 that includes the address of the Authorization Server. The UA will then contact the Authorization Server without providing any credentials in the first request. The Authorization Server challenges the request using the Digest scheme, and the client retries the request and provide the user's credentials. The Authorization Server verifies the request from the client; if the verification is successful, the Authorization Server responds with 302 to redirect the UA back to the registrar and include a code in the body of the 302. The UA then retries the request and include the code in the body of the request. The registrar then contacts the Authorization Server and exchanges the code for a token. Shekh-Yusef Expires November 27, 2014 [Page 6] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 3.2 Registration The UA initiates the process by sending a REGISTER request to the proxy. The proxy will redirect the UA to the Authorization Server by responding with 302 that include the address of the Authorization Server in the form of an HTTP URI. The UA will then follow the authorization steps defined in section 3.3. At the end of the authorization process the UA will have a code that it will use to complete the registration process. The UA will send a new REGISTER request and include the code in the body of the request with the following parameters: grant_type (REQUIRED) Value MUST be set to "authorization_code". code (REQUIRED) The authorization code received from the authorization server. The proxy will then use the code to get a token from the Authorization Server as defined in section 3.4. If the proxy is able to obtain the token, the proxy will respond with 200 OK to the UA to complete the registration process. 3.3 Authorization The UA constructs the initial request without providing any user credentials, but with the following URI parameters in the query component: response_type (REQUIRED) Value MUST be set to "code". scope (OPTIONAL) The scope of the access request as described by Section x.x. Shekh-Yusef Expires November 27, 2014 [Page 7] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 state (RECOMMENDED) The value of this parameter is a nonce created by the client to prevent replay attack. The nonce is a uniquely generated value for each request. The Authorization Server challenges the request by responding with 401 with Digest scheme. The UA will generate a master-key that is based on an HMAC-Hash algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1 and the concatenation of realm and nonce received in the challenge from the server. The UA will then send a new authorization request, but this time include the credentials requested by the server. The UA will use the same parameters values used in the initial authorization request with the exception of the state parameter which will get a new nonce value. When the server receives the request with the credentials, the server will verify the digest provided by the UA; if that is successful, the server will respond with 302 and include a code in the body of the response with the following parameters: grant_type (REQUIRED) Value MUST be set to "authorization_code". code (REQUIRED) The authorization code received from the authorization server. The server then generates a master-key that is based on an HMAC- Hash algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1, and the concatenation of realm and nonce sent in the challenge to the client. 3.4 Acquiring Access Token The proxy receives the REGISTER request that includes a body with a code, as specified in section 3.3. The proxy will then contact Shekh-Yusef Expires November 27, 2014 [Page 8] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 the Authorization Server to exchange the code with a token. The proxy sends a POST request to the Authorization Server and include the following parameters in the body: grant_type (REQUIRED) Value MUST be set to "authorization_code". code (REQUIRED) The authorization code received from the authorization server. If the request is valid and authorized, the authorization server responds with a 200 OK to complete the registration process, with toke, token refresh, and the master-key in the body. [[OPEN ISSUE]] Should the proxy forward the tokens to the UA and expect the UA agent to provide the token with subsequent requests and take care of refreshing the token? 3.5 Token Refresh The proxy makes a refresh request to the token by sending a refresh POST request that includes a body with the grant_type and the refresh_token. For example: grant_type=refresh_token&refresh_token= 3.6 Authenticated Requests When the UA wants to send any request to the proxy, it MUST include the Authorization header and use the MAC scheme to carry the proof- of-possession of the master-key. The pop is calculated using the master-key as follows: Shekh-Yusef Expires November 27, 2014 [Page 9] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 pop = HMAC-SHA256(master-key, some-request-headers) The following is an example of an Authorization header with Bearer scheme: Authorization: Bearer pop= See rfc4474, section 9, for the SIP headers to hash to create the value for the proof. [[OPEN ISSUE]] The Bearer scheme is used to deliver tokens without providing any proof of possession. We probably need to use different scheme later on. Shekh-Yusef Expires November 27, 2014 [Page 10] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 4 Resource Owner Password Credentials Grant type 4.1 Operations Overview The following figure provides a high level view of flow of messages for the Resource Owner Password Credentials Grant type: UA Proxy -------------------------------------------------------------------- | | | REGISTER username@domain.com | |------------------------------------------------------------->| | | | 401 WWW-Authenticate: Digest | |<-------------------------------------------------------------| | | | | o master-key = HMAC-SHA256(HA1, realm + nonce) | | | | REGISTER username@domain.com with Authorization | |------------------------------------------------------------->| | | | | | o master-key=HMAC-SHA256(HA1, realm + nonce) | | | 200 OK [token, expires, ...] | |<-------------------------------------------------------------| | | | | o pop = HMAC-SHA256(master-key, token + some-request-headers) | | | | INVITE token, pop | |------------------------------------------------------------->| | | | o The server verifies the pop. | | | 180 Ringing | |<-------------------------------------------------------------| | | During registration the UA initially sends a REGISTER request without providing any credentials. The registrar then challenges the UA by responding with 401 that includes the Digest scheme in the www-authenticate header. Shekh-Yusef Expires November 27, 2014 [Page 11] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 The UA will generate a master-key that is based on an HMAC-Hash algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1 and the concatenation of realm and nonce received in the challenge from the server. The UA will continue to use the existing operation of handling the Digest challenge and then sends a new REGISTER request with the credentials to the server. When the server receives the request with the credentials, the server will verify the digest provided by the UA; if that is successful, the server will accept the registration and include the details of the token in the response. The server then generates a master-key that is based on an HMAC-Hash algorithm, e.g. HMAC-SHA256, that takes an input the user's HA1, and the concatenation of realm and nonce sent in the challenge to the client. At the end of the above process the UA would have registered with the proxy and both the UA and the registrar would have created the same master-key without sending the master key on the wire. Later when the UA wants to send a request to the proxy it MUST always include the token and SHOULD use the master-key to hash the concatenation of the token and the following headers from the SIP request: See rfc4474, section 9. The resulted hash will be included in the request as a proof-of- possession of the master-key. 4.2 Registration and Acquiring Tokens The UA MUST request the access token during the registration process with the proxy, by including a body with the grant_type as "password". Initially, the UA sends a REGISTER request without providing any credentials. The registrar MUST then challenge the UA by responding with 401 with the Digest scheme in the WWW-Authenticate header. When the UA gets challenged by the proxy to provide its credentials, the UA MUST include its credentials in the new REGISTER request in the authorization header as it is done with the existing mechanism, and MUST include a body with the grant_type as "password". In addition, the UA MUST generate a master-key as follows: master-key = HMAC-SHA256(HA1, realm + nonce) Shekh-Yusef Expires November 27, 2014 [Page 12] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 o HA1 - this is the user's H(A1) as defined in [HTTP-DIGEST]. o realm - this is the realm that is returned by the server in the response to the initial request from the UA. o nonce - this is the nonce that is returned by the server in the response to the initial request from the UA. When the server receives the request with the credentials, the server will verify the digest provided by the UA; if that is successful, the server will accept the registration and include the details of the token in the response. The server then generates a master-key following the same procedure followed by the client. As a result of this procedure both the UA and the server would have created the same master-key without sending the master key on the wire. 4.3 Discarding Credentials After successfully receiving the access and refresh tokens from the registrar, the UA SHOULD discard the user credentials. 4.4 Token Refresh The UA makes a refresh request to the token by sending a refresh REGISTER request that includes the authorization header and a body with the grant_type, the refresh_token, and the proof-of-possession of the master-key. For example: grant_type=refresh_token&refresh_token=&pop= 4.5 Authenticated Requests When the UA wants to send any request to the proxy, it MUST include the Authorization header and use the Bearer scheme to carry the access token, and the proof-of-possession of the master-key. For example: Shekh-Yusef Expires November 27, 2014 [Page 13] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 Authorization: Bearer token=, pop= See rfc4474, section 9, for the SIP headers to hash to create the value for the proof. [[OPEN ISSUE]] The Bearer scheme is used to deliver tokens without providing any proof of possession. We probably need to use different scheme later on. 4.6 Examples REGISTER sip:registrar.biloxi.com SIP/2.0 Via: SIP/2.0/TCP bobspc.biloxi.com:5060;branch=z9hG4bKnashds7 Max-Forwards: 70 To: Bob From: Bob ;tag=456248 Call-ID: 843817637684230@998sdasdh09 CSeq: 1826 REGISTER Contact: Expires: 7200 Content-Length: 19 grant_type=password&pop= SIP/2.0 200 OK Via: SIP/2.0/TCP bobspc.biloxi.com:5060;branch=z9hG4bKnashds7 ;received=192.0.2.4 To: Bob ;tag=2493k59kd From: Bob ;tag=456248 Call-ID: 843817637684230@998sdasdh09 CSeq: 1826 REGISTER Contact: Expires: 7200 Content-Length: 0 { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"example", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "example_parameter":"example_value" } Shekh-Yusef Expires November 27, 2014 [Page 14] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 5 Client Credentials Grant The following flow assumes that the UA is able to get a token using some out-of-band mechanism, and the UA wants to use the token to register, subscribe, and get service. The flow uses a combination of the following from RFC6749: o Client Credentials Grant defined in section 4.4 o Extensions Grants defined in section 4.5. User Proxy Authorization Agent Server --------------------------------------------------------------------- | | | | REGISTER username@domain.com, token | |------------------------------>| | | | | | | POST /authorize | | | [ grant_type = ] | | |------------------------------>| | | | | | 200 OK | | | [validity, services] | | |------------------------------>| | | | | 200 OK | | |<------------------------------| | | | | | | | 5.1 Registration The UA is in possession of a token that was obtained through some out-of-band mechanism. The UA sends a REGISTER request and include the token in the Authorization header using the Bearer scheme as defined in RFC6750. If the proxy is able to verify the token, the proxy accepts the registration request and responds with 200 OK. Shekh-Yusef Expires November 27, 2014 [Page 15] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 5.2 Authorization When the proxy receives the REGISTER request with the token, the proxy will try to first validate the token before responding to the UA request. The proxy sends a POST request and include the following parameters in the body of the request: grant_type (REQUIRED) Some well defined URN. username (REQUIRED) The resource owner username. access_token (REQUIRED) The token received from the UA. scope (OPTIONAL) The scope of the token. If the authorization server is able to validate and authorize the request, it will respond with 200 OK with a body that contains the following parameters: access_token, token_type, expires, refresh_token, scope Shekh-Yusef Expires November 27, 2014 [Page 16] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 6 Security Considerations 7 IANA Considerations 8 Acknowledgments 9 References 9.1 Normative References [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002. [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)", RFC 5869, May 2010. [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [HTTP-DIGEST] Shekh-Yusef, R., Ahrens, D., and Bremer, S., "HTTP Digest Access Authentication", Work in Progress, January 2014. https://datatracker.ietf.org/doc/draft-ietf-httpauth- digest/ 9.2 Informative References Shekh-Yusef Expires November 27, 2014 [Page 17] INTERNET DRAFT SIP Digest Authentication Scheme May 26, 2014 Authors' Addresses Rifaat Shekh-Yusef (Editor) Avaya 250 Sydney Street Belleville, Ontario Canada Phone: +1-613-967-5267 Email: rifaat.ietf@gmail.com Victor Pascual Quobis Spain Email: victor.pascual@quobis.com Shekh-Yusef Expires November 27, 2014 [Page 18]