AIRTEL INDIA OPEN API Application Developer Guide for OAuth2 Authentication and Authorization Document Version 1.1 This Application Developer Guide has been prepared for Airtel India. Copyright Intel Corporation 2014; all rights reserved.
Document Revision History Rev # Date Description 1.0 29 May 2014 The initial issue of Application Developer Guide for applications using the OAuth Service on the Airtel India API platform. 1.1 1 August 2014 Revised and restructured. Updated diagrams and descriptions for the sequence sections. Doc Version 1.1 2
Table of Contents Terminology... 4 1 About this Document... 6 1.1 Audience... 6 1.2 References... 6 2 OAuth Overview... 7 2.1 Application Configuration for AMP OAuth... 7 2.2 Using an OAuth-Protected Service... 7 2.3 Grant Types... 7 2.4 On-net vs Off-net... 8 3 Authorization Code Grant Type... 10 3.1 Authorization Code Sequence... 10 3.2 Authorization Code Parameters and Examples... 12 3.2.1 Authorization Request Generic, Payment and Subscriptions... 12 3.2.2 Authorization Response - Generic... 15 3.2.3 Authorization Error Response... 16 3.2.4 Access Token Request Generic... 17 3.2.5 Access Token Response - Generic... 17 3.2.6 Access Token Error Response - Generic... 19 3.3 Authorization Code Illustrations... Error! Bookmark not defined. 3.3.1 Code Illustration Authorization Request... Error! Bookmark not defined. 3.3.2 Code Illustration - Handling OAuth Callback... Error! Bookmark not defined. 4 Implicit Grant Type... 21 4.1 Implicit Grant Type Sequence... 21 4.2 Implicit Grant Parameters and Examples... 22 4.2.1 Authorization Request Generic, Payment and Subscriptions... 23 4.2.2 Access Token Response - Generic... 24 4.2.3 Access Token Error Response - Generic... 25 4.3 Implicit Grant Code Illustration... Error! Bookmark not defined. A. Appendix Payment Charge Request Examples... 27 Doc Version 1.1 3
Terminology Term Description or Terms in an acronym/abbreviation ACR Anonymous Customer Reference See:http://www.gsma.com/oneapi/anonymouscustomer-reference-beta/ Aggregator AMP AoC ASE ATI Charge CP EULA One-Off purchase OTP Partner PCC PME PSCP PSE PSL REST SSO SOAP SMSC TPS URI URL Aggregators are intermediaries between the mobile carrier and content providers. They provide connectivity to Airtel for content providers. API Monetization Platform Advice of Charge API Services Enabler Airtel India Payment transaction Merchant or Content Provider End User License Agreement One time charge purchase (as opposed to a subscription for which the Payments and Settlement Engine generates user charges on a periodic basis) One Time Password Partner is the generic term for entities that connect to AMP. A partner may be an aggregator of content providers or a single content provider that directly connects to AMP. Purchase Category Code, the term used in OneAPI to denote Media Type Partner Management Engine Partner Self-Care Portal Payments and Settlement Engine Portal Service Layer (API layer of PME) Representational state transfer (REST or RESTful) is a style of software architecture for distributed systems such as the World Wide Web. Single Sign-On A web services protocol specification for exchanging structured information. It used to be called Simple Object Protocol but this definition is no longer valid. Short Message Service Centre Transactions per second Uniform resource identifier is a string of characters used to identify a name of a web resource. Uniform Resource Locator Doc Version 1.1 4
Terminology WSDL Web Services Description Language is an XML-based interface description language that is used for describing the functionality offered by a web service. Doc Version 1.1 5
About this Document 1 About this Document This document is a guide to building applications which access services protected by OAuth 2.0 authentication and authorization framework as provided by the OAuth Authorization Server on the Airtel India API service exposure platform. 1.1 Audience The intended audience for this document are programmers who are developing or modifying the applications to be registered on the Open API platform, designed to access Airtel India services protected by OAuth 2.0. 1.2 Assumption This document is designed to provide sufficient information to implement a working solution for using OAuth protected services. As such, it does not contain a description of the OAuth protocols. The concepts and requirements of OAuth 2.0 framework are defined in IETF RFC specifications referenced below. 1.3 References The following guides and specifications must be available for reference. Relevant sections are noted in the text, as applicable. Ref #1: Open API Partner Self-Care Portal Quick Start Guide Ref #2: OAuth 2.0 Authorization Framework RFC 6749 Specification at http://tools.ietf.org/html/rfc6749, and Bearer Token Usage Specification RFC 6750 Also relevant are the following user guides: AMP-ATI Payment REST v2.1 API Guide AMP-ATI Subscriptions REST v1.0 API Guide Sample codes are available from the Open API Partner Self-Care Portal> Sample Applications tab. Doc Version 1.1 6
OAuth Overview 2 OAuth Overview AMP provides support for web services to be protected by OAuth 2.0 authentication and authorization framework. In the AMP-ATI v1.0 implementation, ASE Payment and Subscription services are available to be accessed via OAuth 2.0. AMP provides an Authorization Server component, configured with the following OAuth 2.0 endpoints: Authorization Endpoint - for user authorization access as directed by the application. This includes user authentication. Token Endpoint - for application access to obtain OAuth tokens. 2.1 Application Configuration for AMP OAuth An application requiring access to an OAuth protected ASE service must be provisioned with a service contract which includes both the protected service and the Authorization Proxy Service. The endpoints for the instances of these services can be viewed from the Partner Self-Care Portal. (Ref #1) Using the Authorization Endpoints and the ASE service public endpoints, the application developer can construct a sequence of requests according to the OAuth specification. These and the redirection URI for the application are configured by the platform administrator. 2.2 Using an OAuth-Protected Service To use an OAuth protected service, the request must include an Authorization header which contains a valid Access Token. The header used is of the Bearer type (Ref #2), for example: Authorization: Bearer 48eb90d1-cb7e-41dd-a838-098410332e18 Examples of calls to an OAuth protected Payment service are provided in Appendix A. Sections 3.1 and 4.1 describe sequences of requests and responses for the application to obtain the Access Token from the OAuth server. 2.3 Grant Types AMP supports two of the OAuth 2.0 grant types (Ref #2), each with its specific flow and parameter requirements: Authorization Code Grant Type (the default type provisioned for a client, referred to as Authorization Code for short) described in chapter 3 Implicit Grant Type described in chapter 4 If a partner requires the Implicit grant type, they must request this through the support link on the partner self-care portal. The platform administrator will provision the requested grant type, if Doc Version 1.1 7
OAuth Overview approved, on behalf of the partner. There is no automatic approval and provisioning for this request. For detailed IETF specifications of how these flows work, please refer to the OAuth 2.0 specification (Ref #2). 2.4 On-net vs Off-net The user experience for authorization and the message exchange between the application and user, and between application and the Open API platform, is influenced by the type of network connection being used by the user device to access Airtel services. The diagram below illustrates at high level the two possibilities for mobile device connection: 1. On-net over the Airtel radio access network (RAN) to the secure Airtel network, i.e. on-net means connected on the Airtel mobile network 2. Off-net via the Internet, e.g. over Wifi Figure 1 Device Data Connection The on-net case allows the Airtel network gateway to inject the mobile subscriber directory number (MSISDN ) for the user into the authorization request, and by virtue that it is a trusted gateway on a secure network the authorization service can trust the authenticity of the MSISDN. Thus, when using the mobile network data connection the user is automatically authenticated, and this gives the best possible user experience by minimizing the amount of data the user must enter to provide authorization for an application. In this flow the user will only be presented with a consent page and Doc Version 1.1 8
OAuth Overview requested to accept or cancel the consent request. For the MSISDN injection to occur, the authorization request must be sent over HTTP, rather than to the secure endpoint for the authorization service. By contrast, the off-net case is over the Internet. Therefore, it does not transit an Airtel gateway and the messages are over an insecure network. The MSISDN number is not available in the authorization request, and even if the application is able to insert the MSISDN it cannot be trusted. For the off-net case secure messaging is required over HTTPS to a secure authorization endpoint exposed by the Open API platform. The user will be asked to enter their MSISDN, they will receive a one-time password (random4-digit number) in an SMS to that MSISDN and they will be asked to enter that password to authenticate that a valid MSISDN has been provided. Following that they will be presented with a consent page. In order to simplify application development, the authorization server can accept the initial authorization request on the insecure endpoint even for the off-net case. It can detect that the session is off-net and will redirect the user agent to a secure session. For efficiency and best possible user experience it will be preferable for an application to use the mobile network data connection and on-net authorization where possible. In the case that off-net data connection is the only choice, the application should, if possible, go directly to the secure end-point, avoiding redirection from the insecure end-point. Doc Version 1.1 9
Authorization Code Grant Type 3 Authorization Code Grant Type In the Authorization Code grant type implementation, the OAuth framework is used to keep subscriber authentication and authorization separate from the application and completely in the carrier network domain, and then to pass the generated Authorization Code to the application which it will use to obtain the Authorization Access Token to access the service. The Authorization Code grant type is used to obtain Access Tokens, and also Refresh Tokens where applicable. For a payment scope, however, a refresh token is not provided, and the access token is for single use only. This flow is relevant to and optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's useragent (typically a web browser) and capable of receiving incoming requests (via redirection from the authorization server. This section provides the sequence diagram and flow, parameters required and returned in this type of OAuth grant, examples, and code illustrations. 3.1 Authorization Code Sequence An OAuth flow using the default Authorization Code grant type is depicted in a simplified sequence diagram below. It shows the three main events - to get the Authorization Code, to exchange it for the Access Token, and to use it to make a service call, such as on Payment API. Before the start of the sequence, the user (a subscriber) would have made a request to the partner s application to invoke the service, such as to purchase an item. This action invokes the OAuth sequence necessary to enable the required transaction to go ahead. Each sequence in the diagram is described in stepped order below the diagram. Figure 2 OAuth Sequence Authorization Code Grant Type Doc Version 1.1 10
Authorization Code Grant Type 1. Get Authorization Code The application initiates an OAuth authentication/authorization sequence by redirecting the subscriber to the Authorization Service at its Authorization Endpoint. The request must include the OAuth parameters. This includes response_type of code and other OAuth parameters, such as redirect_uri to specify the callback used later in the flow, and any parameters required by the specific scope associated with the request. For example, for a payment charge request, the amount and the currency must be specified. Section 3.3 lists Authorization request parameters, including the specific requirements for Payment and Subscription services. Service scopes are configured when the service is provisioned by the platform administrator. 2. User OAuth Server Interactions The call out section in the diagram is a summary of what takes place outside of the partner s domain, for the user to be authenticated and to give authorization/consent for the payment in interactions between the user and the OAuth server. If the user is on-net, the subscriber MSISDN is injected and enables automatic authentication and going straight to the Authorization page to give consent to the payment with the scope presented. If the user is off-net, the user will be required to input the OTP received at the MSISDN, on the Advice of Consent page before being redirected to the Authorization page. 3. Authorization Code When the user approves the authorization, the result is posted back to the redirect_uri of the application with the Authorization Code. If the user cancels the authorization, the result is still posted back. Table 3 lists response parameters, and Table 4 error response parameters. 4. Exchange for Token The application sends a request to the Authorization Service, using the Authorization Code, and exchanges it for the OAuth Access Token. Table 5 lists of Access Token request parameters. 5. Token Response The Access Token is returned in a JSON response, for example: access_token : 550e8400-e29b-41d4-a716-446655440000 Table 6 lists Access Token response parameters. Error response parameters are listed in Table 7. 6. Use Token to make a service API call The application can now initiate the desired service transactions, including the Access Token in its request call using the Authorization Bearer header: Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000 Doc Version 1.1 11
Authorization Code Grant Type See an example of access token used in a Payment charge request in Appendix A. Parameters for the API call are described in the specific service API guide. 3.2 Authorization Code Parameters and Examples This section lists the parameters required in each of the OAuth request operations in the sequence described above, those returned in successful responses and in error responses, together with selected message examples. Notes are supplied for the operations where applicable.! OAuth applies to Payment: charge and Subscriptions: activate operations only. Payment: refund and Subscriptions: deactivate do not require user authorization. This section contains the following sub-sections: Authorization Request Generic, Payment and Subscriptions below Authorization Response Generic section 3.3.2 Authorization Error Response Generic section 3.3.3 Access Token Request Generic section 3.3.4 Access Token Response Generic 3.3.5 Access Token Error Response Generic 3.3.6 3.2.1 Authorization Request Generic, Payment and Subscriptions The application (client) issues a redirect to the subscriber device browser in a GET operation as follows: the application constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the "application/x-www-form-urlencoded" format.! For this OAuth operation, service specific parameters are required in addition to the generic parameters. The latter is presented in the first table, below, followed by tables for the service specific parameters. 3.2.1.1 Authorization Request Auth Code Grant Type - Generic Parameters Parameter Description Optional response_type Value MUST be set to "code". No client_id Application Name from the Application profile created via the Partner Self-Care Portal. No redirect_uri URL of a callback on the application. After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent back to the client. The authorization server redirects the user-agent to the client's redirection No Doc Version 1.1 12
Authorization Code Grant Type Parameter Description Optional endpoint previously established with the authorization server during the client registration process or when making the authorization request. The redirection endpoint URI MUST be an absolute URI and match an address configured on the AMP system. Such addresses will have been provided to AMP administrators as part of the registration process for the application. The endpoint URI MAY include an "application/x-www-form-urlencoded" formatted query component, which MUST be retained when adding additional query parameters. The endpoint URI MUST NOT include a fragment component. scope The scope of the resource access to be authorized, as defined on the authorization service for the service (resource) being requested. The value of the scope parameter is expressed as a list of space-delimited, casesensitive strings. For each operation for any service the associated scope may have mandatory parameters. If it does, these should also be supplied. For example, for payment, a charge amount operation (scope) requires amount and currency parameters. No! See the service-specific configuration notes for details of the scope for each service in the tables below. state An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery Yes Table 1 Generic Authorization (Authorization Code grant type) Request Parameters 3.2.1.2 Authorization Request Payment: charge In addition to the parameters listed in the generic section above, the following service specific parameters are required for a Payment charge operation. The URI is as follows, which includes the payment service specific parameters: http://{serverroot}/services/oauth/authorize? amount={amount}¤cy=[currency]&redirect_uri={redirect_uri}&scope={scope}&cli ent_id={client_id}&response_type=code&state={state]&pn={product_name}&pd{product_ description}&pc={pcc}&imgurl={image_url} Parameter Description/Value Optional imgurl URL of an image for presentation purposes. Only displayed when subscriber is using a smart phone connected through the Airtel data network. Yes Doc Version 1.1 13
Authorization Code Grant Type Parameter Description/Value Optional pn Product Name No pd Product Description No pc Product category code associated with your application No amount Amount to be charged (as decimal, e.g. 10.20) No currency Currency code, e.g. INR No scope Value = ChargeAmount. This is the scope required for the charge amount operation. This scope has the following parameters configured: amount currency No Table 2 Charge Authorization Request Parameters 3.2.1.3 Authorization Request Subscription: activate In addition to the parameters listed in the generic section above, the following service specific parameters are required for a Subscriptions activate operation. The URI is as follows, which includes the suibscription service specific parameters: http://{serverroot}/services/oauth/authorize? amount={amount}¤cy=[currency]&redirect_uri={redirect_uri}&scope={scope}&cli ent_id={client_id}&response_type=code&state={state]&pn={product_name}&pd{product_ description}&pc={pcc}&pv={product_validity}&imgurl={image_url} Parameter Description/Value Optional imgurl URL of an image for presentation purposes. Only displayed when subscriber is using a smart phone connected through the Airtel data network. Yes pn Product Name No pd Product Description No pc Product category code associated with your application No pv Product Validity No amount Amount to be charged (as decimal, e.g. 10.20) No currency Currency code, e.g. INR No scope Value = Subscription. The scope required for the activate operation. This scope has no parameters. No Doc Version 1.1 14
Authorization Code Grant Type 3.2.1.4 Authorization Request Example Table 3 Activate Subscription Authorization Request Parameters An example of a charge authorization request, as generated from a web browser page: GET http://openapi.airtel.in/services/oauth/authorize? amount=1.0¤cy=inr&scope=chargeamount&client_id=d6340cac48f764ae2735aa3b02 20c762&state=19631935&response_type=code&pn=Name&pd=Description&pc=testPC&redir ect_uri=http%3a%2f%2fmerchant.site.com%2fwebservice%2fbillme%2fcallback&imgurl= http%3a%2f%2fmerchant.site.com%2fgamezone%2fimages%2fempty.png 3.2.2 Authorization Response - Generic If the user grants the access request, the authorization server issues an authorization code and delivers it to the application by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format. The client MUST ignore unrecognized response parameters. There are no service specific parameters in authorization responses. Parameter Description Present code The authorization code generated by the authorization server. The authorization code will normally be in form of a UUID and may include other identifiers. A length of up to 72 characters should be considered. However, the application should not make assumptions about the code value size. The authorization code will expire shortly after it is issued to mitigate the risk of leaks. A maximum authorization code lifetime of 10 minutes should be expected and the code should be used as soon as possible. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server will deny the request. Always state PRESENT IF the "state" parameter was present in the client authorization request. The exact value received from the client. If in the request Table 4 Authorization Response Parameters 3.2.2.1 Authorization Response Example An example of a successful authorization response to the application, including the authorization code. Browser interaction traces have been omitted from the initial request to this response. HTTP/1.1 302 Found Date: Fri, 04 Apr 2014 10:33:45 GMT Server: Jetty(7.6.7.v20120910) Location: http://merchant.site.com/webservice/callback?code=550e8400-e29b-41d4- a716-446655440000 Content-Length: 0 Connection: close Content-Type: text/plain; charset=utf-8 Doc Version 1.1 15
Authorization Code Grant Type 3.2.3 Authorization Error Response If the request fails due to a missing, invalid, or mismatching redirection URI, or if the application identifier is missing or invalid, the authorization server will inform the resource owner of the error and will not automatically redirect the user-agent to the invalid redirection URI. If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the application by adding the following parameters to the query component of the redirection URI using the "application/x-wwwform-urlencoded" format. There are no service specific parameters in authorization error responses. Parameter Description Present error A single ASCII error code from the following: invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. unauthorized_client The client is not authorized to request an authorization code using this method. access_denied The resource owner or authorization server denied the request. unsupported_response_type The authorization server does not support obtaining an authorization code using this method. invalid_scope server_error The requested scope is invalid, unknown, or malformed. The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.) temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.) Always error_description Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter will not include characters outside the set %x20-21 / %x23-5b / %x5d-7e. Always Doc Version 1.1 16
Authorization Code Grant Type Parameter Description Present state PRESENT If a "state" parameter was present in the application authorization request. The exact value received from the application. If in the request Table 5 Authorization Error Response Parameters 3.2.4 Access Token Request Generic The application makes a request to the token endpoint by sending the following parameters in a POST operation, using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body. The URI is as follows: https://{serverroot}/services/oauth/token On receiving a successful authorization response, the following parameters are required in all access token requests, regardless of the applicable service. Parameter Description Optional grant_type The value MUST be set to "authorization_code". No code The authorization code received from the authorization server. No redirect_uri client_id The value of this parameter MUST be identical to the "redirect_uri" included in the authorization request. This is the application user name registered on the AMP administration portal for the application. No No Table 6 Access Token Request Parameters 3.2.4.1 Access Token Request Example POST https://openapi.airtel.in/services/oauth/token HTTP/1.1 Connection: close Authorization: Basic ZDYzNDBjYWM0OGY3NjRhZTI3MzVhYTNiMDIyMGM3NjI6e0dFV1c+M20= Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&client_id=d6340cac48f764ae2735aa3b0220c762&redire ct_uri=http://merchant.site.com/webservice/callback&code=550e8400-e29b-41d4- a716-446655440000 3.2.5 Access Token Response - Generic If the access token request is valid and authorized, the authorization server issues an access token and optional refresh token. It constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code. There are no service specific parameters in access token responses. Doc Version 1.1 17
Authorization Code Grant Type Parameter Description Present access_token The access token issued by the authorization server. Always token_type The type of the token issued, which will be "bearer". Always expires_in refresh_token The lifetime in seconds of the access token. The default expiation time for payment and subscription services is 259200 seconds (72 hours). The refresh token can be used in authorization grant to obtain new access tokens. This is optional, and not relevant and not provided for payment and subscription services. Always Optional; not present for Payment and Subscriptions scope A copy of the scope from the client request. Always (for Payment and Subscriptions) Table 7 Access Token Response Parameters The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JavaScript Object Notation (JSON) structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary. The authorization server includes the HTTP "Cache-Control" response header field with a value of "no-store", as well as the "Pragma" response header field with a value of "no-cache". The application MUST ignore unrecognized value names in the response. The application should avoid making assumptions about value sizes. 3.2.5.1 Access Token Response Example An example of a successful access token response to the application, with the access token. HTTP/1.1 200 OK Content-Type: application/json grant_type: authorization_code redirect_uri: http://merchant.site.com/webservice/callback Connection: close Pragma: no-cache Cache-Control: no-store Transfer-Encoding: chunked X-Forwarded-For=[10.10.12.44, 10.56.133.37] payload={{"access_token":"46410738-7c22-4132-aab7- af1662ddadf4","token_type":"bearer","expires_in":64,"scope":"chargeamount"}} Doc Version 1.1 18
Authorization Code Grant Type 3.2.6 Access Token Error Response - Generic If the request failed or is invalid, the authorization server responds with an HTTP 400 (Bad Request) status code (unless otherwise stated below) and includes the following parameters with the response. The parameters are included in the entity-body of the HTTP response using the "application/json" media type. The parameters are serialized into a JSON structure by adding each parameter at the highest structure level. Parameter names and string values are included as JSON strings. Numerical values are included as JSON numbers. The order of parameters does not matter and can vary. Parameter Description Present error A single ASCII error code from the following: invalid_request invalid_client invalid_grant The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. Application authentication failed (e.g., unknown application, no application authentication included, or unsupported authentication method). The authorization server will return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the application attempted to authenticate via the "Authorization" request header field, the authorization server will respond with an HTTP 401 (Unauthorized) status code and include the "WWW- Authenticate" response header field matching the authentication scheme used by the application. The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another application. unauthorized_client The authenticated application is not authorized to use this authorization grant type. unsupported_grant_type The authorization grant type is not supported by the authorization server. invalid_scope The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner. Always Doc Version 1.1 19
Authorization Code Grant Type Parameter Description Present error_descripti on state Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter will not include characters outside the set %x20-21 / %x23-5b / %x5d-7e. PRESENT if a "state" parameter was present in the application authorization request. The exact value received from the application. Always If in the request Table 8 Access Token Error Parameters Doc Version 1.1 20
Implicit Grant Type 4 Implicit Grant Type The Implicit flow is used when the application is running not on a trusted host, but entirely on the user s device. For example the application may be implemented using Javascript. In this case, the callback is not implemented via a web server application, but the redirect_uri will be an URL of the web-hosted script, capable of extracting the access token which will be embedded in the URI. Another example of an application running on the mobile device would be an App written in Java, which would parse out the fragment from the Location header of the redirect response to the Authorization endpoint request. This section provides the sequence diagram and flow, and parameters required and returned in this type of OAuth grant, and code illustrations.. 4.1 Implicit Grant Type Sequence An OAuth flow using the Implicit grant type is depicted in the sequence diagram below. The network gateways the messages pass through are not shown in the diagram. The sequences are described in stepped order below the diagram. Step descriptions that differ from the Authorization Code sequence are underlined. Before the start of the sequence, the user (a subscriber) would have made a request to the partner s application to invoke a service, for example, to purchase an item. This action initiates the OAuth sequence necessary to enable the service transaction to go ahead. Figure 3 OAuth Sequence Implicit Grant Type 1. get authorization code The application initiates an OAuth authentication sequence by a request to the Authorization Service at its Authorization Endpoint. Doc Version 1.1 21
Implicit Grant Type The request must include the OAuth parameters. This includes response_type of token and other OAuth parameters, such as redirect_uri to specify the callback used later in the flow, and any parameters required by the specific scope associated with the request. For example, for a payment charge request, the amount and the currency must be specified. Section 4.3.1lists Authorization request parameters, including the specific requirements for Payment and Subscription services. Service scopes are configured when the service is provisioned by the platform administrator. 2. User OAuth server interactions The call out section in the diagram is a summary of what takes place outside of the partner s domain, for the user to be authenticated and to give authorization/consent for the payment in interactions between the user and the OAuth server. If the user is on-net, the subscriber MSISDN is injected and enables automatic authentication and going straight to the Authorization page to give consent to the payment with the scope presented. These sequences use HTTP (not secure) in order to allow MSISDN injection. If the user is off-net, the user will be required to input the OTP received at the MSISDN, on the Advice of Consent page before being redirected to the Authorization page. 3. Token response When the User approves/denies the authorization, the result is returned to the application as a redirect to the redirect_uri from the authorization request, with the Access Token in the fragment of the Location header URI. Table 4.3.2 lists the parameters returned with the access token, and Table 4.3.2.1 the error response. 4. Extract and use token to call service API The application extracts the Access Token from the fragment. In the code illustration (section 4.3), this is assumed to be done on the device in App code. In a Javascript based application running on a browser, the callback URI would be that of a script that is capable of extracting the fragment. The application then uses the Access Token in the Authentication header to request the service. See an example of access token used in a Payment charge request in Appendix A. Parameters for the API call are described in the specific service API guide. 4.2 Implicit Grant Parameters and Examples This section lists the parameters required in each of the OAuth request operations in the Implicit grant type sequence described above, those returned in successful responses and in error responses. Brief descriptions of the operations are provided.! OAuth applies to Payment: charge and Subscriptions: activate operations only. Payment: refund and Subscriptions: deactivate do not require user authorization. This section contains the following sub-sections: Authorization Request Generic, Payment and Subscriptions below Doc Version 1.1 22
Implicit Grant Type Access Token Response Generic section 4.3.2 Access Token Error Response Generic section 4.3.3 4.2.1 Authorization Request Generic, Payment and Subscriptions The application (client) issues a redirect to the subscriber device browser, as follows. The application constructs the request URI by adding the following parameters to the query component of the authorization endpoint URI using the "application/x-www-form-urlencoded" format. As this is a redirect to the subscriber, there is no response handling for this request on the application.! For this OAuth operation, service specific parameters are required in addition to the generic parameters. The latter is presented in the first table, below, followed by tables for the service specific parameters. Authorization Request Implicit grant type Generic Parameters Parameter Description Optional response_type The value MUST be set to "token". No client_id Application Name from the Application profile created via the Partner Self-Care Portal. No redirect_uri URL of a callback on the application. After completing its interaction with the resource owner, the authorization server directs the resource owner's user-agent back to the client. The authorization server redirects the user-agent to the client's redirection endpoint previously established with the authorization server during the client registration process or when making the authorization request. The redirection endpoint URI MUST be an absolute URI, and match an address configured on the AMP system. Such addresses will have been provided to AMP administrators as part of the registration process for the application. The endpoint URI MAY include an "application/x-www-formurlencoded" formatted query component, which MUST be retained when adding additional query parameters. The endpoint URI MUST NOT include a fragment component. No scope The scope of the resource access to be authorized, as defined on the authorization service for the service (resource) being requested. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. For each operation for any service the associated scope may have mandatory parameters. If it does, these should also be supplied. For example, for payment, a charge amount operation (scope) requires amount and currency parameters. No Doc Version 1.1 23
Implicit Grant Type Parameter Description Optional! See the service-specific configuration notes for details of the scope for each service. state An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery. Yes Table 9 Generic Authorization (Implicit grant type) Request Parameters 4.2.1.1 Authorization Request Payment: charge In addition to the parameters listed in the generic section above, service specific parameters are required for a Payment charge operation. As these apply regardless of the grant type used, see the list in Table 2. The URI is as follows, which includes the payment service specific parameters: http://{serverroot}/services/oauth/authorize? amount={amount}¤cy=[currency]&redirect_uri={redirect_uri}&scope={scope}&cli ent_id={client_id}&response_type=code&state={state]&pn={product_name}&pd{product_ description}&pc={pcc}&imgurl={image_url} 4.2.1.2 Authorization Request Subscription: activate In addition to the parameters listed in the generic section above, service specific parameters are required for a Subscriptions activate operation. As these apply regardless of the grant type used, see the list in Table 3. The URI is as follows, which includes the suibscription service specific parameters: http://{serverroot}/services/oauth/authorize? amount={amount}¤cy=[currency]&redirect_uri={redirect_uri}&scope={scope}&cli ent_id={client_id}&response_type=code&state={state]&pn={product_name}&pd{product_ description}&pc={pcc}&pv={product_validity}&imgurl={image_url} 4.2.2 Access Token Response - Generic If the user grants the access request, the authorization server issues an access token and delivers it to the application by adding the following parameters to the query component of the redirection URI using the "application/x-www-form-urlencoded" format. On receiving a successful authorization response, the following parameters are required in all access token requests, regardless of the applicable service. Parameter Description Present access_token The access token issued by the authorization server. Always token_type The type of the token issued, which will be "bearer". Always Doc Version 1.1 24
Implicit Grant Type Parameter Description Present expires_in The lifetime in seconds of the access token. The default expiry time for payment and subscription services is 259200 seconds (72 hours). Always scope A copy of the scope requested by the client. Always (for Payment and Subscriptions) state PRESENT if a "state" parameter was present in the application authorization request. The exact value received from the application. If in the request Table 10 Access Token (Implicit grant type) Response Parameters The Authorization server will redirect the subscriber to make the callback request on the URI specified in redirect_uri, from the request. The application MUST ignore unrecognized value names in the response. The application should avoid making assumptions about value sizes. 4.2.3 Access Token Error Response - Generic If the request fails due to a missing, invalid, or mismatching redirection URI, or if the application identifier is missing or invalid, the authorization server will inform the resource owner of the error and will not automatically redirect the user-agent to the invalid redirection URI. If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the application by adding the following parameters to the query component of the redirection URI using the "application/x-wwwform-urlencoded" format: Parameter Description Present error A single ASCII error code from the following: invalid_request The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. unauthorized_client The client is not authorized to request an authorization code using this method. access_denied The resource owner or authorization server denied the request. unsupported_response_type The authorization server does not support obtaining an authorization code using this method. invalid_scope Always Doc Version 1.1 25
Implicit Grant Type Parameter Description Present server_error The requested scope is invalid, unknown, or malformed. The authorization server encountered an unexpected condition that prevented it from fulfilling the request. (This error code is needed because a 500 Internal Server Error HTTP status code cannot be returned to the client via an HTTP redirect.) temporarily_unavailable The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server. (This error code is needed because a 503 Service Unavailable HTTP status code cannot be returned to the client via an HTTP redirect.) error_description state Human-readable ASCII [USASCII] text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the "error_description" parameter will not include characters outside the set %x20-21 / %x23-5b / %x5d-7e. PRESENT if a "state" parameter was present in the application authorization request. The exact value received from the application. Always If in the request Table 11 Access Token (Implicit grant type) Error Response Parameters Doc Version 1.1 26
Appendix A Authorization Request Examples A. Appendix Payment Charge Request Examples The following examples illustrate how the Access Token is used to authenticate a payment charge API call, and its response. An authorization header is inserted with the value of the OAuth token, and user ID (MSISDN) is replaced by acr :Authorization, which is an operator-provided string that maps to the number and protects the identity of the user. Payment request using the Access Token POST https://openapi.airtel.in/cxf/apay/2_1/payment/acr:authorization/transactions/a mount HTTP/1.1 Content-Type: application/json Authorization: Bearer 46410738-7c22-4132-aab7-af1662ddadf4 Connection: close Content-Length:448 User-Agent: Jakarta Commons-HttpClient/3.1 {"amounttransaction":{"clientcorrelator":"15379691341","enduserid":"acr:authori zation","paymentamount":{"charginginformation":{"amount":"1.0","currency":"inr","description":["description"]},"chargingmetadata":{"onbehalfof":"example Games Inc","purchaseCategoryCode":"game","channel":"WAP","taxAmount":"0.00","serviceI d":"service ID","productId":"product ID"}},"referenceCode":"ChargeAmount- 15379691341-0","transactionOperationStatus":"Charged"}} Response to payment request HTTP/1.1 201 Created Content-Type: application/json Headers: {Content-Type=[application/json], Location=[http://openapi.airtel.in/cxf/apay/2_1/payment/acr:Authorization/trans actions/amount/f0720fd2-2dd1-468a-a99f-35893ffa3b82], Date=[Wed, 26 Mar 2014 15:13:58 GMT]} { "amounttransaction" : { "enduserid" : "acr:authorization", "paymentamount" : { "charginginformation" : { "description" : [ "Airtel IOT PAY-OA-01" ], "currency" : "INR", "amount" : 1.00 }, "totalamountcharged" : 1.00, "chargingmetadata" : { "onbehalfof" : "Example Games Inc", "purchasecategorycode" : "game", "channel" : "WAP", "taxamount" : 0.00, "serviceid" : "service ID", "productid" : "product ID" } }, Doc Version 1.1 27
Appendix A Authorization Request Examples "transactionoperationstatus" : "Charged", "referencecode" : "ChargeAmount-15379691341-0", "serverreferencecode" : "f0720fd2-2dd1-468a-a99f-35893ffa3b82", "clientcorrelator" : "15379691341", "resourceurl" : "https://openapi.airtel.in/cxf/apay/2_1/payment/acr:authorization/transactions/ amount/f0720fd2-2dd1-468a-a99f-35893ffa3b82" } } End of Document Doc Version 1.1 28