oauth authorization code.html - swisscom-api/doc GitHub Wiki

<%= modified_date %>

This tutorial describes an easy way to get an OAuth authorization code & access token and shows the integration flow.

Firstly, you must have a valid client id and secret, plus authorization to use an API which has been configured with your specific coordinates (notably redirection URL; more to follow). If you haven't, please contact us to get you set up and ready to go.

In summary, the following information is required to proceed with this tutorial.

• Your client id (32 character long, case sensitive alphanumeric string)
• Your client secret (16 characters)
• Your fully qualified return URL (HTTPS GET request).
  If you're just getting started, you may want to first request localhost.
• Coordinates for the API you want to use.

To follow this step-by-step tutorial, you may want to have the following set up beforehand:

• Google Chrome
• Modify Headers Plugin for google Chrome

or

• Use xampp to set up a simple Tomcat or PHP application

This example uses Swisscom Login for authentication. Other SSO providers are available upon request.

Open the following URL in the browser.

https://consent.swisscom.com/c/oauth2/auth?response_type=code&redirect_uri=https%3A%2F%2Flocalhost&client_id=%YOUR_CLIENT_ID%&lang=en

Note that the redirect url is fully qualified and URL encoded (use 'raw' encoding, i.e. %20 instead of '+' for example).

You will see the Swisscom login

The user has to login with his Swisscom Credentials (username and password).

After successful login a consent page appears with a request to agree that this page/app has the permission to read the users information.

The list of granted rights is determined by the list of scopes that we have configured for you. In this example: scope=read-basicprofile.

The user checks "I acknowledge..." and clicks "Authorise". (if not, your application will simply not make it into the following step).

The browser returns the user to the redirect URL that was provided in the first step.

The redirect URL redirected to: https://localhost/?code=5du16Pu6&scope=... for example. The code you see included in the query string is your authcode (hence the name of this OAuth grant type). In this example the authcode is "5du16Pu6".

The authcode was returned to the user through the public network and is therefore not safe. You must exchange this authcode for a more permanent token within a very short timeframe.

First, here's the theory of what you must do to get to that token: you send a GET request to our token endpoint as follows:

GET /o/oauth2/token?grant_type=authorization_code&code=5du16Pu6&redirect_uri=..... HTTP/1.1
Host: consent.swisscom.com
Authorization: Basic YOUR-HASHED-CLIENT-ID-AND-SECRET

where YOUR-HASHED-CLIENT-ID-AND-SECRET is the base64 hash of %YOUR_CLIENT_ID%:%YOUR_CLIENT_ID_SECRET%

If all's well, we will respond with a JSON body that contains your token (see below).

The simplest way to do this, is probably by using a browser. For example:

Set the authorization header in the browser:
Authorization: Basic YOUR-HASHED-CLIENT-ID-AND-SECRET
and enable it, as shown in the following screenshot.

You now call the URL:

https://consent.swisscom.com/o/oauth2/token?grant_type=authorization_code&code=5du16Pu6&redirect_uri=..... 

Notice, that strictly speaking you wouldn't need a redirect_uri here. However, we validate that URL against the so-called "Callback URL" that we configured on our end, hampering attempts to hijack the authcode.

Get the token from the response

NOTE: If you see 401 with “INVALID_AUTHENTICATION_CREDENTIALS” make sure that you set and enabled the Authentication header, see step (a).

In this example the token is: “kVhlBP24TjemCzvmSxSvkpa6ZUwv”

Your application will need to send your user to the login process first. This can be a simple hyperlink or button:

<a href="https://consent.swisscom.com/c/oauth2/auth?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2FgetToken.php&client_id=.....">
	<img src="login.png">
</a>

The redirect URL must be a fully qualified URL to a resource (e.g. page) that you implement on your site. In this case: http://localhost/getToken.php

The user will then be sent to the login screen and consent page as shown above. Your application will not see any of this, until the user returns to your site with the redirect URL that you provided under your login button.

http://localhost/getToken.php?code=...&scope=.....

If you have a critical dependency on the information for which you need the user's consent, then you may want to store the value of the "&scope=" parameter at this point.

Proceed now, by swapping the authcode for a token.

Example in PHP:

// Get the authorization code from the request
$authcode = $_REQUEST["code"];

// Initiate cURL, using the authcode above
$ch = curl_init("https://consent.swisscom.com/o/oauth2/token?grant_type=authorization_code&code=$authcode&redirect_uri=http%3A%2F%2Flocalhost%2FgetToken.php);

// Set the method to GET
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET);

// Get the basic auth string for your client id and secret (get from global context)
$basicAuth = base64_encode("$clientid:$clientsecret");

// Set the mandatory headers, notably basic auth
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Authorization: Basic $basicAuth"));

// Execute the cUrl call
$response = curl_exec($ch);

// Parse the JSON response, distill the access token and put it on the session
$_SESSION["access_token"] = json_decode($response, true)["access_token"];

The access_token is what you need going forward.

As example: Voice Voip Numbers as a curl call

curl -H "Authorization: Bearer kVhlBP24TjemCzvmSxSvkpa6ZUwv" "https://api.swisscom.com/voice/v1/voip/me/numbers"