Three-legged OAuth (user context)
This challenge authenticates the system and the user. Since users have to provide their credentials within the ImmobilienScout24 authentication web page, this method is recommended if you can forward the user to that page (within a web browser), and you have a callback URL for ImmobilienScout24 to redirect the user back to, after successful authentication and token authorization.
This flow involves three main steps:
- Temporary Credentials Acquisition: The system gets a set of temporary credentials from the server, also known as a Request Token.
- Authorization: The user actively "authorizes" the system which owns the
request_tokento access their account. This action is done via a web flow (web browser).
- Token Exchange: The system exchanges the short-lived temporary credentials for a lifetime token, also known as Access Token.
Steps for OAuth Flow:
1. Temporary Credentials Acquisition
The first step to authorization is acquiring a set of temporary credentials known as the Request Token (
These credentials are short-lived (30 minutes), and are used solely for the initial authorization process. They won't grant any access to data on our server, and you cannot use them for anything except the authorization flow.
You must acquire these credentials by an initial HTTP request to the following server:
The POST request must include the following OAuth parameters:
oauth_callback(the authorization callback URI)
- The request signature (
The request looks as follows:
POST /oauth/request_token HTTP/1.1 Host: server.example.com Authorization: OAuth oauth_consumer_key="your_system_key", oauth_signature_method="HMAC-SHA1", oauth_timestamp="987654321", oauth_nonce="7dk77uj4a", oauth_callback="http%3A%2F%2Fclient.example.com%2Fcb", oauth_signature="..."
The server checks the key and signature to ensure the client is valid. It also confirms the callback URI.
Once the checks are complete, the server creates a new set of temporary credentials (
oauth_token_secret) and returns them in the HTTP response (URL encoded). The response looks as follows:
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_token=kji98hr5&oauth_token_secret=ijhu787gf5ef5&oauth_callback_confirmed=true
You can then use these credentials as the oauth_token and oauth_token_secret parameters for the Authorization and Token Exchange steps (see below). All further steps using this Request Token must be executed within 30 minutes; otherwise, the token expires.
The next step is a user-facing one (web browser-based). Redirect the user to the server to grant the client permission to act on the user's behalf. This is typically done via a redirect for in-browser clients or opening a browser for native clients.
Simply use the following URL and append the temporary credential key
oauth_token, previously obtained in step 1, to the URL as a query parameter.
The user then logs into ImmobilienScout24 portal if they aren't already and authorizes the client. They can also choose to cancel the authorization process.
If the user authorizes the client, ImmobilienScout24 then accepts the token as authorized, and redirects the user back to the callback URL (from step 1).
- oauth_token - The obtained temporary credentials identifier. - oauth_verifier - a CSRF token that needs to be passed in the next step. - state - the result of the authorization which can be - authorized: the token was successfully authorized by the user, - rejected: the token was explicit not authorized by the user or - error: an error has occurred while authorizing (often due to the request token being expired)
3. Token Exchange
The final step in the OAuth flow is to exchange the temporary credentials with lifetime credentials, known as Access Tokens.
A POST request must be sent to the ImmobilienScout24 server. This request must be signed by the temporary credentials and must include the
oauth_verifier token obtained by the previous authorization step.
https://rest.immobilienscout24.de/restapi/security/oauth/access_token Required OAuth Parameters - oauth_consumer_key - oauth_token - The temporary credentials identifier. - oauth_signature_method - oauth_timestamp - oauth_nonce - oauth_signature - oauth_verifier - The verification code received from the ImmobilienScout24 API in step 2. - oauth_version (optional)
The request looks as follows:
POST oauth/access_token HTTP/1.1 Host: server.example.com Authorization: OAuth oauth_consumer_key="your_system_key", oauth_token="hdk48Djdsa", oauth_signature_method="HMAC-SHA1", oauth_timestamp="987654321", oauth_nonce="7dk77uj4a", oauth_verifier="RW7C7W", oauth_signature="..."
The server responds with the final set of credentials: HTTP response body (form data, URL-encoded):
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_token=tg76hgf5rdffer4d&oauth_token_secret=k8ujhzgfd5gfd5rfg3
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 reuses it for subsequent calls to restricted resources of the REST API until the access token expires or is revoked by the user. After this step, the temporary credentials (Request Tokens) are invalidated as well as the verifier.
The resource request is to get or modify an arbitrary resource. Every resource request must be signed (see below).
Required OAuth Parameters
- oauth_token - The token identifier received in step 3.
- oauth_version (optional)
- See API Documentation of the requested resource.
All OAuth challenges require the signing of requests. The request signing is composed of the following 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.
You create a signature key by URL encoding your system_secret and the request_token_secret, then concatenating them with & into a string.
For example, if your system_secret is
abcde and your request_token_secret is
12345, the key is
- The request_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).