Add-on Authentication

From fringDocumentation

Jump to: navigation, search

The API Authentication enables Add-ons to make secured calls to FIS API.

This document is a subset of the OAuth Core 1.0 protocol. fring based its authentication on OAuth because "OAuth creates a freely-implementable and generic methodology for API authentication" (OAuth Protocol Abstract). With fring, since there is no user authentication on FIS, ApiAuth does not include the user parts (see the note in Authenticating with ApiAuth discussing OAuth three players versus ApiAuth two players).

Contents

Registration

ApiAuth includes an Add-on Key and matching Add-on Secret, together they authenticate the Add-on to FIS. ApiAuth defines two request URLs as follows:


Parameters

ApiAuth uses the same parameter names as OAuth Core 1.0 Protocol and they are case-sensitive.

Parameter Encoding

All parameter names and values are escaped using the (RFC 3986) percent-encoding (%xx) mechanism. Characters not in the unreserved character set (RFC 3986, section 2.3) MUST be encoded. Characters in the unreserved character set MUST NOT be encoded. Hexadecimal characters in encodings MUST be upper case. Text names and values MUST be encoded as UTF-8 octets before percent-encoding them per RFC 3629. 

unreserved = ALPHA, DIGIT, '-', '.', '_', '~'

Add-on Request Parameters

As opposed to OAuth protocol, ApiAuth Parameters are sent from the Add-on to the FIS only in the HTTP Authorization header as defined in HTTP Authorization Header.

FIS Response Parameters

Response parameters are sent by FIS to return Tokens and other information to the Add-on in the HTTP response body. The parameter names and values are first encoded as per Parameter Encoding, and concatenated with the & character (ASCII code 38) as defined in RFC 3986 Section 2.1.

For example: 

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=xyz4992k83j47x0b

Authorization Header

The ApiAuth Parameters are sent in the Authorization header in the following way:

  • Parameter names and values are encoded per Parameter Encoding.
  • For each parameter, the name is immediately followed by: = character (ASCII code 61), ” character (ASCII code 34), parameter value (MAY be empty) and ” character (ASCII code 34).
  • Parameters are separated by a comma character (ASCII code 44) and OPTIONAL linear whitespace per [RFC2617] (J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, and L. Stewart, HTTP Authentication: Basic and Digest Access Authentication).
  • The OPTIONAL realm parameter is added and interpreted per RFC 2617, section 1.2.

For example: 

Authorization: OAuth realm="http://www.fringcall.com/",
oauth_consumer_key="0685bd9184jfhq22",
oauth_token="ad180jjd733klru7",
oauth_signature_method="HMAC-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0"

Authenticating with ApiAuth

Add-ons use Tokens generated by FIS to identify themselves. The process uses the following Token types:

  • Request Token: Used by the Add-on to ask for a challenge to use along with their Secret. The Request Token is exchanged for an Access Token, can only be used once, and MUST NOT be used for any other purpose. Request Tokens have a limited lifetime.
  • Access Token: Used by the Add-on to access the FIS API. Access Tokens MAY limit access to certain Protected Resources and have a limited lifetime.

Note: Open Authentication (OAuth) is meant for three players (User, Consumer and Service Provider), whereas, the Add-on architecture has only two, Consumer (Add-on) and Service Provider (FIS). Therefore, fring removed the parts where a user is authorizing the request. The user’s parts: C and D in the OAuth Authentication Flow diagram, below, were removed from ApiAuth.

The following diagram was taken from OAuth Core 1.0 protocol, similar to ApiAuth, it is included here for reference:

API Authentication is done in two steps (instead of three):

  1. Add-on obtains an unauthorized Request Token (Steps A and B above).
  2. Add-on exchanges the Request Token for an Access Token (Steps E and F above).

After the Add-on retrieved an Access Token, it can call the FIS API (Step G above) as shown in the following:

Obtaining an Unauthorized Request Token

The Add-on obtains an unauthorized Request Token by asking the FIS to issue a Token. The Request Token process is as follows:

1. Add-on Obtains a Request Token

To obtain a Request Token, the Add-on sends an HTTPS request to the Request Token URL. The request MUST be signed and contains the following parameters:

  • oauth_consumer_key: The Add-on Key (User ID).
  • oauth_signature_method: The signature method the Add-on used to sign the request (MUST be SHA1).
  • oauth_signature: The signature as defined in Signing Requests.
  • oauth_timestamp: As defined in Nonce and Timestamp.
  • oauth_nonce: As defined in Nonce and Timestamp.
  • oauth_version: The value MUST be 1.0.

2. FIS Issues an Unauthorized Request Token

The FIS verifies the signature and Add-on Key. If successful, it generates a Request Token and Token Secret and returns them to the Add-on in the HTTP response body as defined in FIS Response Parameters.

The response contains the following parameters:

  • oauth_token: The Request Token
  • oauth_token_secret: The Token Secret

If the request fails verification or is rejected for other reasons, FIS responds with the appropriate response code as defined in HTTP Response Codes. FIS MAY include some further details about why the request was rejected in the HTTP response body as defined in FIS Response Parameters.

Obtaining an Access Token

The Add-on exchanges the Request Token for an Access Token capable of calling FIS API. Obtaining an Access Token includes the following steps:

1. Add-on Requests an Access Token

The Request Token and Token Secret MUST be exchanged for an Access Token and Token Secret.

To request an Access Token, the Add-on sends an HTTPS request to the Access Token URL. The request MUST be signed per Signing Requests and contains the following parameters:

  • oauth_consumer_key: The Add-on Key.
  • oauth_token: The Request Token obtained previously.
  • oauth_signature_method: The signature method the Add-on used to sign the request (MUST be SHA1).
  • oauth_signature: The signature as defined in Signing Requests.
  • oauth_timestamp: As defined in Nonce and Timestamp.
  • oauth_nonce: As defined in Nonce and Timestamp.
  • oauth_version: The value MUST be 1.0.

No additional FIS specific parameters are allowed when requesting an Access Token.

2. FIS Grants an Access Token

The FIS ensures that:

  • The request signature has been successfully verified.
  • The Request Token has never been exchanged for an Access Token.
  • The Request Token matches the Add-on Key.
  • Five minutes has not passed since the Request Token has been issued.

If successful, FIS generates an Access Token and Token Secret and returns them in the HTTP response body as defined in FIS Response Parameters. The Access Token and Token Secret are stored by the Add-on and used when signing subsequent requests. The response contains the following parameters:

  • oauth_token: The Access Token.
  • oauth_token_secret: The Token Secret.
  • Additional parameters: Any additional parameters defined by FIS.

If the request fails verification or is rejected for other reasons, FIS responds with the appropriate response code as defined in HTTP Response Code. FIS MAY include some further details about why the request was rejected in the HTTP response body as defined in FIS Response Parameters.

Calling API from Add-on to FIS (OAuth Language: Accessing Protected Resources)

After successfully receiving the Access Token and Token Secret, the Add-on is able to call the FIS API.

Note: The following list of parameters have been modified from OAuth.

The request MUST be signed per Signing Requests and contains the following parameters:

  • oauth_consumer_key: The Add-on Key.
  • oauth_token: The Access Token.
  • oauth_signature_method: The signature method the Add-on used to sign the request (MUST be SHA1).
  • oauth_version: The value MUST be 1.0.
  • Additional parameters: Any additional parameters defined by FIS.

Nonce and Timestamp

The timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be a positive integer and MUST be equal to or greater than the timestamp used in previous requests.

The Add-on SHALL then generate a Nonce value that is unique for all requests with that timestamp. A nonce is a random string, uniquely generated for each request. The nonce allows the FIS to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel (such as HTTP).

Signing Requests

All Token requests and API calls MUST be signed by the Add-on and verified by the FIS. The purpose of signing requests is to prevent unauthorized parties from using the Add-on Key and Tokens when making Token requests or API calls. The signature process encodes the Add-on Secret and Token Secret into a verifiable value which is included with the request.

As opposed to OAuth, ApiAuth support only one signature method: HMAC-SHA1.

The Add-on declares a signature method in the oauth_signature_method parameter, generates a signature and stores it in the oauth_signature parameter. FIS verifies the signature as specified in each method. When verifying an Add-on signature, FIS checks the request nonce to ensure it has not been used in a previous Add-on request.

The signature process MUST NOT change the request parameter names or values, with the exception of the oauth_signature parameter.

Signature Base String

The Signature Base String is a consistent reproducible concatenation of the request elements into a single string. The string is used as an input to the hashing or signing algorithms. The HMAC-SHA1 signature method provides both a standard and an example of using the Signature Base String with a signing algorithm to generate signatures. All request parameters MUST be encoded as described in Parameter Encoding prior to constructing the Signature Base String.


Normalize Request Parameters

(Modified from OAuth)

The request parameters are collected, sorted and concatenated into a normalized string as follows:

  • Normalize parameters in the Authorization header excluding the realm parameter.
  • HTTP GET and DELETE parameters are added to the URLs in the query part (as defined by RFC 3986 section 3).
  • (Modified from OAuth) HTTP POST and PUT requests to FIS contain an XML as the request body (with a content-type of application/xml) defined in FAXL. To make the signature meaningful, when signing requests, the entire request body is treated as a single parameter named req_body. This parameter MUST be treated exactly as the other parameters (meaning, url-encoding, sorting and concatnating to the Base String).

The oauth_signature parameter MUST be excluded.

The parameters are normalized into a single string as follows:

  • Parameters are sorted by name, using lexicographical byte value ordering. If two or more parameters share the same name, they are sorted by their value. For example: 
a=1, c=hi%20there, f=25, f=50, f=a, z=p, z=t
  • Parameters are concatenated in their sorted order into a single string. For each parameter, the name is separated from the corresponding value by an = character (ASCII code 61), even if the value is empty. Each name-value pair is separated by an & character (ASCII code 38). For example: 
a=1&c=hi%20there&f=25&f=50&f=a&z=p&z=t

Construct Request URL

The Signature Base String includes the request absolute URL, tying the signature to a specific endpoint. The URL used in the Signature Base String MUST include the scheme, authority and path and MUST exclude the query and fragment as defined by RFC 3986 section 3.

URL scheme and authority MUST be lowercase and include the port number; http default port 80 and https default port 443 MUST be excluded.

For example, the request: 

HTTP://Example.com:80/resource?id=123

Is included in the Signature Base String as: 

http://example.com/resource

Concatenate Request Elements

The following items MUST be concatenated in order into a single string. Each item is encoded and separated by an ‘&’ character (ASCII code 38), even if empty, as follows:

  1. The HTTP request method used to send the request. Value MUST be uppercase, for example: GET, POST, DELETE and PUT.
  2. The request URL from Construct Request URL.
  3. The normalized request parameters string from Normalize Request Parameters.

See Signature Base String example in Appendix A.5.1 of the OAuth Core 1.0 protocol Generating Signature Base String.

HMAC-SHA1

The HMAC-SHA1 signature method uses the HMAC-SHA1 signature algorithm as defined in RFC 2104 where the Signature Base String is the text and the key is the concatenated values (each first encoded per Parameter Encoding) of the Add-on Secret and Token Secret, separated by an & character (ASCII code 38) even if empty.

Generating Signature

oauth_signature is set to the calculated digest octet string, first base64-encoded per RFC 2045 section 6.8, then URL-encoded per Parameter Encoding).

Verifying Signature

The FIS verifies the request by generating a new request signature octet string and compares it to the signature provided by the Add-on, first URL-decoded per Parameter Encoding), then base64-decoded per RFC 2045 section 6.8. The signature is generated using the request parameters as provided by the Add-on (and the request body, FAXL, under the name req_body) and the Add-on Secret and Token Secret as stored by the FIS.

HTTP Response Codes

This section applies only to the Request Token and Access Token requests. In general, FIS use the response codes defined in RFC 2616 Section 10. When FIS rejects an Add-on request, it responds with HTTP 400 Bad Request or HTTP 401 Unauthorized.

  • HTTP 400 Bad Request
    • Unsupported parameter
    • Unsupported signature method
    • Missing required parameter
    • Duplicated OAuth Protocol Parameter
  • HTTP 401 Unauthorized
    • Invalid Add-on Key
    • Invalid/expired Token
    • Invalid signature
    • Invalid/used nonce

References

[NIST] National Institute of Standards and Technology, NIST Brief Comments on Recent Cryptanalytic Attacks on Secure Hashing Functions and the Continued Security Provided by SHA-1

RFC 2045 N. Freed and N. Borenstein, Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies

RFC 2104 H. Krawczyk, M. Bellare and R. Canetti, HMAC: Keyed-Hashing for Message Authentication

RFC 2119 B. Bradner, Key words for use in RFCs to Indicate Requirement Levels

RFC 2606 D. Eastlake and A. Panitz, Reserved Top Level DNS Names

RFC 2616 R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach and T. Berners-Lee, Hypertext Transfer Protocol – HTTP/1.1

RFC 2617 J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen and L. Stewart, HTTP Authentication: Basic and Digest Access Authentication

RFC 3447 J. Jonsson and B. Kaliski, Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography; Specifications Version 2.1

RFC 3629 F. Yergeau, UTF-8, a Transformation Format of Unicode and ISO 10646

RFC 3986 T. Berners-Lee, Uniform Resource Identifiers (URI): Generic Syntax

[SHA1] C. De Canniere and C. Rechberger, Finding SHA-1 Characteristics: General Results and Applications

Retrieved from "http://www.fringcall.com/index.php?title=Add-on_Authentication"
Personal tools