Authentication

Authentication (Detailed)

Authentication at the IS24 API in Detail

This page gives a more detailed view of the authentication process via OAuth at IS24.

 

Authentication

Common Rules

All requests regardless whether it is 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.

Since the status code of the response in case of an error is always 401 have a deeper look on the exception message which will give you a hint of what is went wrong.

Three-legged OAuth (system and user)

This challenge authenticates the system and the user. Since the user has to provide it's credentials within the IS24 authentication web page this method is recommended if you have the possibillity to forward the user to that page (within a web browser) and aware of a callback from IS24 after successful authentication and token authorization.

IS24 Three-Legged-OAuth process

Step by Step

1. Getting a request_token

It obtains a set of temporary credentials from the IS24 API by making an request to the Temporary Credential Request endpoint.

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

Required OAuth Parameters (in addition to the always required parameters)

oauth_callback

The absolute URI to which the IS24 API will redirect when the Resource Owner Authorization step is completed. If you are unable to receive callbacks or a callback URI has been established via other means, the parameter value MUST be set to "oob" (case sensitive), to indicate an out-of-band configuration.

Note: Due to a framework bug at this moment we only support URI's starting with a scheme which matches the following regular expression (\A[a-z.+-]+://.*). Means contrary to RFC 3986 digits are not allowed within the scheme (e.g. immoscout:// is valid and is24:// is not valid).

Response Parameters

oauth_token

    The temporary credentials identifier.

oauth_token_secret

    The temporary credentials shared-secret.

oauth_callback_confirmed

    Is present and set to "true". The parameter is used to differentiate from  previous versions of the protocol.

The request token is valid for 30 minutes. So all further calls using this request token (step2+3) must be executed within 30 minutes.


2. Authorizing the request_token (a user grants the system to use his account)

Before requesting a set of token credentials from the server, send the user to the server to authorize the request. For this request you must not provide any OAuth parameter within the header. You simply use the following URL and add the token which has to be authorized by the user as URL parameter

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

Required OAuth Parameters

    none

Required Query Parameters

    oauth_token

        The temporary credentials identifier obtained in step 1 in the "oauth_token"                         parameter.

Response Parameters

    oauth_token

        The received temporary credentials identifier.

    oauth_verifier

        The verification code.

    state

        the result of the authorization which can be

        - authorized: the token was successful authorized by the user

        - rejected: the token was explicit not authorized by the user

        -error - an error has occurred while authorizing (mostly the request token is expired)

 


3. Getting an access_token by using the authorized request token (the request token can only be used once)

The access token obtains a set of token credentials from the IS24 API.

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

Required OAuth Parameters (in addition to the always required parameters)

    oauth_token

        The temporary credentials identifier.

    oauth_verifier

        The verification code received from the IS24 API in the step 2.

Response Parameters

    oauth_token

        The token identifier.

    oauth_token_secret

        The token shared-secret

The access token is valid for an unlimited time, until the user cancels the authorization. It's suggested that the system application (e.g. a mobile client) stores the access token and reuse it for subsequent calls to restricted resources of the REST API until the access token expires or is expunged by the user.

 

4. resource request

The resource request is to get or modify of an arbitrary resource.

https://rest.immobilienscout24.de/restapi/api/...

Required OAuth Parameters (in addition to the always required parameters)

oauth_token

    The token identifier received in step 3.

Response Parameters

This parameter depends on the requested resource (see API Documentation)

 

Two-legged OAuth (system only)

Two legged OAuth is in short terms already included within the classic OAuth. Since within this method only the system will be authenticated we have it already seen in step one of the classic OAuth process.

This challenge authenticates only the system. Whenever a resource requires only a simple system authentication this method is sufficiently.

 

Step by Step

1. resource request

Get or modify an arbitrary resource.

https://rest.immobilienscout24.de/restapi/api/...

Required OAuth Parameters (in addition to the always required parameters)
none

Response Parameters

depends on the requested resource (see API Documentation)

OAuth Parameters

The OAuth challenges use the following parameter. This parameter will be set within the Authorization header field.
oauth_consumer_key

    The identifier portion of the client credentials (equivalent to a username). This is the             system key within the terms of IS24.

oauth_nonce

    The nonce value. (see http://oauth.net/core/1.0a/#nonce).

oauth_timestamp

    The timestamp value in seconds.

oauth_token

    The value of the token allocates the request to the resource owner. If the request is not     allocated to a resource owner (no token is available), clients MAY omit the parameter.

oauth_signature

    The signature calculates the specified signature method the request is using. (NOTE: Do     not include this within the signature base string – it would cause a never ending loop :-))

oauth_signature_method

    The signature method the client used to sign the request.

oauth_verifier

    The verifier for the 3rd step of the classic OAuth challenge.

oauth_version

    OPTIONAL. But if present, it MUST be set to "1.0".

The following table shows the parameters which are optional, required or must be omitted in every request:

Parameter OAuth Three-Legged (System + User) OAuth Two-Legged (System only)
get request_token authorize request_token get access_token resource request resource request
oauth_ consumer_key required must omitted required required required
oauth_ token must omitted as query parameter required required must omitted
oauth_ signature_method required must omitted required required required
oauth_ timestamp required must omitted required required required
oauth_ nonce required must omitted required required required
oauth_ signature required must omitted required required required
oauth_ verifier must omitted must omitted required must omitted must omitted
oauth_ version optional must omitted optional optional optional

Signing Requests

All OAuth challenges require the signing of requests. Simply spoken the request signing is composed of two steps.

  • Extracting a signature base string for the current request
  • 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 is a consistent, reproducible concatenation of the several HTTP request elements into a single string. The string is used as an input to the "HMAC-SHA1" and "RSA-SHA1" signature methods.

The signature base string includes the following components 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 orders of these parameters id are alphabetical.

 

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

  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.

 

For example, the HTTP request:

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"

 

is represented by the following 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


Signing Key


Two-legged key

If you are requesting a request token you only need your private consumer secret. The key to use for signing the signature base string looks like follows:

consumerSecret&, e.g. Hz78P+%20VxxYu&

Note: Be aware of the ampersand at the end of the key.

Note: The consumerSecret has to be WWW URL (OAuth) encoded.

 

Three-legged key

The three-legged OAuth comes in place when requesting an access token (and secret) or requesting a resource (using the access token and secret).

Getting an Access Token

If you want to get an access token you need your private consumer secret and the formerly received request token secret. The key to use for signing the signature base string and getting an access token looks like follows:

consumerSecret$requestTokenSecret, e.g. Hz78P+%20VxxYu&Op045HJkv63MbTLCyx%3D

Note: Be aware of the ampersand in the middle of the key, between consumer secret and request token secret.

Note: The consumerSecret and the requestTokenSecret have to be WWW URL (OAuth) encoded.

Note: The token secret always ends with an equal sign, hence the encoded token secret ends with %3D (it is the last sign in a Base64 encoded strings).

Requesting a Resource

If you want to request a resource you have to follow the same steps as for requesting an access token. The only difference is the use of the access token secret instead of the request token secret.

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 as well
  • 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"

 

Calculating a signature

Please use tools for calculating a signature, there are several tools available: it reduces complexity and offers stability. For example the PHP-SDK and dotNet-SDK. Tools: http://liboauth.sourceforge.net or http://asynchttpclient.github.io/async-http-client/apidocs/com/ning/http/client/oauth/OAuthSignatureCalculator.html

 

It is recommended to use HMAC-SHA1 as signature method. So 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].

Exception Responses

Since all responses indicating an error while authentication have the HTTP status code 401. You have to pay attention to the provided message of the particular response. Basically the responses belong to 3 categories:

 

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

 

The requested resource requires authentication (indeed all IS24 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

Currently the authentication layer returns a HTML representation, even if the consumer (client) has requested another representation using a HTTP Accept header. This is a known bug and will be fixed in a future release.

 

 

 

<?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 ressource]</message>

</message>

</common:messages>

 

 

 

HTTP Status 401 - XXX

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

HTTP Status 401 - Access denied

Provided authentication details does not have the persmission to access this resource. Get in contact with the IS24 Support in order to ask for proper permissions for your system.

Recommendations

 

  • Only establish secure connections using HTTPS

 

 

  • Never ever use the system secret within a request.
    The secret will only be needed while signing requests using of OAuth. Also the secret must be handled with confidence 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.

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

 

Additional information

Known issues

 

  • 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.
  • Currently the authentication layer returns a HTML representation, even if the consumer (client) has requested another representation using a HTTP Accept header (content negotiation). This is a known bug and will be fixed in a future release.

OAuth

Using OAuth with desktop and mobile apps

OAuth support for the IPhone

OAuth support for Android