Contents

  1. Overview
  2. Forming The URL
  3. PHP Code Example
  4. Test Your OAuth2 Settings

Arbor OAuth2 SSO allows you to use your Arbor account credentials in order to login into your application. You are using single account (Arbor) to gain access into your application, so you have to remember only one account credentials. Of course, you'l have to make some modifications into your application.

Overview

The authorization begins when your application (client application) redirects you to your school site (also acts as OAuth2 server) hosted by Arbor. You will be prompted to enter your Arbor account credentials (an email and password that you regularly use to log in into your school site). Client application also sends redirect_url as GET parameter. This is your publicly available URL to which you will be redirected after successful sign in. From now on, user's interaction is not needed, and client app will negotiate with our OAuth server in order to verify your credentials.

Forming the URL

The URL used when authentication user on school site is likehttps://your.arbor.domain.sc/oauth2/auth. Of course, you should replace your.arbor.domain.sc with your actual school domain. This endpoint is accessible over HTTPS. HTTPS request will also be redirected to HTTPS.

Endpoint Description
https://your.arbor.domain.sc/oauth2/auth This endpoint is the target of the initial request. User is getting prompted here with simple authorization form. This endpoint also handles obtaining code for further auth steps.
https://your.arbor.domain.sc/oauth2/token This endpoint is exchanges code for an authorization token.

The set of query string parameters supported by the Arbor OAuth2 Server for web server applications are:

Parameter Values Description
response_type code Determines whether the Arbor OAuth 2.0 endpoint returns an authorization code. Web server applications are supposed to use code.
client_id <Any string>The client ID is username (email) used by user to log in into Arbor school site This parameter is used to identify the client that is making request.
redirect_uri <Any string> This is client's application endpoint which handles response from Arbor OAuth server Determines where the response is sent.
scope basic Permission(s) that the application requests. So far we support basic scope and this is what you should use in your requests.
state <Any string> Random string generated as to mark session for every specific authorization request. This parameter is added automatically by Arbor OAuth2 server.

An example URL is shown below.

https://your.arbor.domain.sc/oauth2/auth?redirect_uri=http%3A%2F%2Fdeveloper-portal.local%3A8000%2Foauth%2Fauthorize

PHP Code Example

First step in authorization is pretty simple. All you have to do is to set parameterredirect_uriinto URL. After successful login, user is redirected back to your site ("redirect_uri") and you can validate results.

$code        = $_GET['code'];           // Contained within redirect URL
$secret      = $_GET['client_secret'];  // Contained within redirect URL (MD5 format)
$clientId    = $_GET['client_id'];      // Contained within redirect URL (Client's ID user for login)
$username    = $_GET['username'];       // Contained within redirect URL (Clint's Arbor username)
$tokenUri    = $_GET['token_uri'];      // Contained within redirect URL (OAuth2 token endpoint)
$redirectUri = 'http://my.application.com/authorize'; // This is custom entry point in your application

if (isset($code)) {
    // Hit token endpoint and exchange code
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_HEADER, 0);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, array(
        'grant_type'    => urlencode('authorization_code'), 
        'code'          => urlencode($code),
        'redirect_uri'  => urlencode($redirectUri),
        ));
    curl_setopt($ch, CURLOPT_USERPWD, "$clientId:$secret");
    curl_setopt($ch, CURLOPT_URL, $tokenUri);
    $response = curl_exec($ch);
}

Here is an example response fromtokenendpoint:

{"access_token":"de63ba737ecf00f02bdf30e088dcc4694769b2a4","expires_in":3600,"token_type":"Bearer","scope":"basic","refresh_token":"7f1ab8ece45147a56127c25705eff264e2edc477"}

If authorization fails, response will contain an error type and error description. Here is an example of unsuccessful authorizaktion response:

"{"error":"invalid_grant","error_description":"The authorization code has expired"}"

Redirect URL Pararameters

When user is redirected back to your site, you will also receive some additional parameters in it. Use $_GET method to extract them or any other GET parameter method that suits you development environment or framework.

Parameter Values Description
code code This is code sent by OAuth server after first negotiation. You can use it as additional check point to make sure that you are within the same authorization request.
client_id <Any string> This is user's ID (email) used by user to log in into Arbor school site Note that value of this parameter can be the same as username parameter, but this is not mandatory.
token_uri <Any string> OAuth2 server token endpoint/td> This is something that you should have stored into your application, but to make things easyer for integration, we are also providing it within URL. If you have it hard-codded, you can use this too as a secure option by making sure that those two token endpoints match.
username <Any string> Username of user registered with Arbor shool application Your school application will return username of logged in user only on successful login.
client_secret <Any string> This is user's password used for authentication. From security reasons it is in MD5 format
state <Any string> Identifies login request This is a "session like" string, unique for every login request.

Take a look at the example of redirect URL. Note that some parameters are shorten (...) to make URL more readable:

http://your.arbor.domain.sc/?code=cb2b2c31...28da30&state=092e61a...2025a&client_id=user@my-school.com&token_uri=http://your.arbor.domain.sc/oauth2/token&username=john&client_secret=fd74d01e70e19f6e0824e8c5e7d3ef89

Test Your OAuth2 Settings

For testing your OAuth2 settings you can use curl or Google's OAuth Playground.

 

Testing OAuth2 With Google's Oauth Playground

 

First navigate to Google OAuth Playground. On the right side click on settings icon and fil up the form.


Form fields explained:

 

  • OAuth flow: set it to Server-side
  • OAuth endpoints: we select Custom here, since we'll be using custom endpoints set on school domain.
  • Authorization endpoint: this is endpoint where user will be prompted with authorization form on your Arbor school application. Ypu should set something like: https://my.school.arbor.sc/oauth2/auth. Of course, you will replace my.school.arbor.sc with your actual domain name.
  • Token endpoint: at this endpoint OAuth exchanges code for token
  • Access token location: here you should set Authorization header w / Bearer prefix
  • OAuth Client ID: supply Arbor client email
  • OAuth Client secret: normally, you would set here client's unencrypted password. Since password will be transmitted as 'client_secret' parameter in URL, although we use SSL layer, we think it is a good idea to send password as MD5 hash, rather then plain unencrypted text. So, first hash your password using MD5 and then place your password hash here.

Now you are ready to test your settings.

  • Step 1: On the left side type basic into input field beside Authorize APIs button. Then clich on Authorize APIs button. Then user will be redirected to your Arbor school application and asked to authenticate. When done, Arbor redirects you back to the OAuth playground, sending code as parameter in URL.
  • Step 2: you should se Authorization code filled in step 2. Just click on Exchange authorization code for tokens button.
    Note: authorization code expires after 30 seconds so you have to exchange code for tokens before it expires. Otherwise, you will se response like:
    {
      "error_description": "The authorization code has expired", 
      "error": "invalid_grant"
    }
    On successful code - token exchange you will see Refresh token (used for refreshing session) and Access token. Also, response is shown on the right side:
    {
      "access_token": "8708ff1c83aec70540a49412c9e7aecaab3edd9c", 
      "token_type": "Bearer", 
      "expires_in": 3600, 
      "refresh_token": "42ece812815b91bc98e0cce2e2bdee3507e4ce36", 
      "scope": "basic"
    }