Signing Requests and More

General information

  • Only establish a secure connection using HTTPS

  • Never use the system secret within a request. The secret will only be needed for signing requests using OAuth. Also, the secret must be handled with care since it is the password of the system.

  • Provide all necessary OAuth parameters within the well-known header field Authorization: The value of this field has to start with OAuth followed by a blank and the required comma-separated OAuth parameters in the format key="value". It is also possible to provide them as query parameters or even within the body content. Nevertheless, this documentation assumes them within the header field, check the specification to use the other positions.

  • The authorisation must be done only once. The access token you receive can be saved in your application indefinitely.

  • You can perform the authorisation steps with our Playground so that you don't need to write code for this step. More info on the Playground here.

  • All requests, regardless of whether they're a token request or a resource request, must be signed. Token requests are requests for retrieving or authorizing tokens. Resource requests will be used to retrieve or modify a resource. Please see here for more information on signing requests.

  • In the event of an authentication error, you will receive a 401. Check the exception message to understand the root cause of the exception.

  • Do not supply additional unsupported parameters to the OAuth parameter string. These parameters are ignored and can lead to an exception.

  • Omit the realm using OAuth. Providing a realm can lead to undefined results.

  • It's suggested that standalone applications and mobile apps should use a out of band configuration (OOB). Anyway, callbacks are supported.

  • Check our Java tutorial for implementing OAuth.

The following SDKs can help you with the setting up the authentication:

  • PHP-SDK - maintained by ImmobilienScout24
  • .Net-SDK - not maintained by immobilienscout24
  • Java-SDK maintained by ImmobilienScout24

Signing Requests

All OAuth challenges require the signing of requests. The request signing is composed of two steps:

  • Extracting a signature base string for your request. Please see here. fixme add anchor
  • Calculating a signature for that signature base string using the specified signature method and the combination of system secret and token secret.

Signature Base String

The signature base string a consistent and reproducible concatenation of HTTP request elements. The string is used as input for the "HMAC-SHA1" and "RSA-SHA1" signature methods.

The signature base string includes the following elements of the HTTP request:

  • The HTTP request method (e.g., "GET", "POST", etc.).
  • The authority as declared by the HTTP "Host" request header field.
  • The path and query components of the request resource URI.
  • The OAuth parameters excluding the "oauth_signature".

The signature base string does not cover the entire HTTP request. Most notably, it does not include the entity-body in most requests, nor does it include most HTTP entity-headers. It is important to note that the server cannot verify the authenticity of the excluded request components without using additional protections such as SSL/TLS or other methods.

NOTE: The query and OAuth parameters are part of the signature base string. The order of these parameters id are alphabetical.

The signature base string is constructed by concatenating the following HTTP request elements and in the following order:

  1. The HTTP request method in uppercase. For example: "HEAD", "GET", "POST", etc. If the request uses a custom HTTP method, it MUST be encoded.
  2. An "&" character (ASCII code 38).
  3. The base string URI, after being encoded.
  4. An "&" character (ASCII code 38).
  5. The request parameters (Query+OAuth) as normalized, after being encoded.

Please see below for an example HTTP request and its base string representation.

HTTP Request Example:

POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b

HTTP/1.1 Host: example.com

Content-Type: application/x-www-form-urlencoded

Authorization: OAuth oauth_consumer_key="9djdj82h48djs9d2",

    oauth_version="1.0",

    oauth_token="kkk9d7dh3k39sjv7",

    oauth_signature_method="HMAC-SHA1",

    oauth_timestamp="137131201",

    oauth_nonce="7d8f3e4a",

    oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

Signature base string (line breaks in the sample code are for display purposes only!):

POST&http%3A%2F%2Fexample.com%2Frequest&a2%3Dr%2520b%26a3%3D2%2520q%26a3%3Da%26b5%3D%253D%25253D%26c%2540%3D%26c2%3D%26

oauth_consumer_key%3D9djdj82h48djs9d2%26

oauth_nonce%3D7d8f3e4a%26

oauth_signature_method%3DHMAC-SHA1%26

oauth_timestamp%3D137131201%26

oauth_token%3Dkkk9d7dh3k39sjv7%26

oauth_version%3D1.0

Calculating a Signature

It is recommended to use HMAC-SHA1 as a signature method. HMAC-SHA1 is built into many languages natively, and libraries are available for basically every other language. It is recommended to use an existing library for calculating a signature. For instance: - https://github.com/x42/liboauth - http://asynchttpclient.github.io/async-http-client/apidocs/com/ning/http/client/oauth/OAuthSignatureCalculator.html

As such, the following requirement to signature calculation assumes the usage of HMAC-SHA1. The "HMAC-SHA1" signature method uses the HMAC-SHA1 signature algorithm as defined in [RFC2104]:

digest = HMAC-SHA1 (key, text)

The HMAC-SHA1 function variables are used in following way:

text - is set to the value of the signature base string (see above)

key - is set to the concatenated values

  1. The client shared-secret, after being encoded

  2. An "&" character (ASCII code 38), which MUST be included even when either secret is empty.

  3. The token shared-secret, after being encoded

digest - is used to set the value of the "oauth_signature" parameter, after the result octet string is base64-encoded [RFC2045].

Authorization:

OAuth oauth_consumer_key="key",
oauth_nonce="49AF27E9-914D-4322-895D-A56D42F74A33",

oauth_signature_method="HMAC-SHA1",

oauth_timestamp="1278416273",

oauth_token="6b337cca-1a08-462e-af29-549aace848ea",

oauth_version="1.0",

oauth_signature=W2v1d%2FP9aI%2F0KBRuwW%2BP%2BeLkFPQ%3D

Exception Responses

Since all error responses during the authentication flow have the HTTP status code 401. You have to pay attention to the provided message of a particular response. The responses belong to 3 categories:

1. HTTP Status 401 - Full authentication is required to access this resource

The requested resource requires authentication (indeed all ImmobilienScout24 resources at least system authentication) - consult the documentation of the special resource which authentication objects are needed for that resource Note: This response also includes the WWW-Authenticate header field which always advises you the OAuth challenge

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<common:messages>

<message>

<messageCode>ERROR_COMMON_AUTHENTICATION_REQUIRED</messageCode>

<message>Authentication is required for this operation. [ERROR MESSAGE: full authentification is required to use this resource]</message>

</message>

</common:messages>

2. HTTP Status 401 - XXX

Errors while extracting and verifiing the provided authentication informations. See the particular message for details.

3. HTTP Status 401 - Access denied

Provided authentication details do not have the permission to access this resource. Please get in contact with the ImmobilienScout24 Support in order to ask for proper permissions for your system.

Troubleshooting

If your request is rejected with status code='401' and:

<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0" xmlns:xlink="http://www.w3.org/1999/xlink">
<message> <messageCode>ERROR_COMMON_AUTHENTICATION_REQUIRED</messageCode>
<message>Authentication is required for this operation. [ERROR MESSAGE: Invalid signature for signature method HMAC-SHA1]</message></message> </common:messages>

Check that it complies with the following rules:

  • all OAuth parameters set in the signature base string must be set in the Authorization header
  • the oauth_signature must not be part of the signature base string, but it must be part of the Authorization header
  • except the oauth_signature the Authorization header must not contain more/other OAuth parameters than the signature base string

Following these rules is necessary as the server recalculates the signature base string and the signature to validate the request. Note that the sequence of the parameters in the Authorization header is not relevant for the serverside recalculation.

Check, that for POST and PUT requests, when data is sent in the body, the correct Content-Type header is set e.g. application/xml or application/xml.

Error Samples

Because of the rules above the following signature base string and Authorization header combinations won't work:

Missing oauth_version in Authorization header

Signature base string:

POST&http%3A%2F%2Fexample.com%2Frequest&a2%3Dr%2520b%26a3%3D2%2520q%26a3%3Da%26b5%3D%253D%25253D%26c%2540%3D%26c2%3D%26

oauth_consumer_key%3D9djdj82h48djs9d2%26

oauth_nonce%3D7d8f3e4a%26

oauth_signature_method%3DHMAC-SHA1%26

oauth_timestamp%3D137131201%26

oauth_token%3Dkkk9d7dh3k39sjv7%26

oauth_version%3D1.0

Header

Authorization: OAuth oauth_consumer_key="9djdj82h48djs9d2",

    oauth_token="kkk9d7dh3k39sjv7",

    oauth_signature_method="HMAC-SHA1",

    oauth_timestamp="137131201",

    oauth_nonce="7d8f3e4a",

    oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

Additional oauth_version in Authorization header

Signature base string

POST&http%3A%2F%2Fexample.com%2Frequest&a2%3Dr%2520b%26a3%3D2%2520q%26a3%3Da%26b5%3D%253D%25253D%26c%2540%3D%26c2%3D%26

oauth_consumer_key%3D9djdj82h48djs9d2%26

oauth_nonce%3D7d8f3e4a%26

oauth_signature_method%3DHMAC-SHA1%26

oauth_timestamp%3D137131201%26

oauth_token%3Dkkk9d7dh3k39sjv7

Header

Authorization: OAuth oauth_consumer_key="9djdj82h48djs9d2",

    oauth_version="1.0",

    oauth_token="kkk9d7dh3k39sjv7",

    oauth_signature_method="HMAC-SHA1",

    oauth_timestamp="137131201",

    oauth_nonce="7d8f3e4a",    

    oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

URI's to get the Tokens

Getting the request token:

    https://rest.immobilienscout24.de/restapi/security/oauth/request_token

Confirm the access token:

    https://rest.immobilienscout24.de/restapi/security/oauth/confirm_access?oauth_token=...

Getting the access token:

    https://rest.immobilienscout24.de/restapi/security/oauth/access_token

Helpful Sources

OAuth

Using OAuth with desktop and mobile apps

OAuth support for IPhone

OAuth support for Android