GrandID API - Svensk e

 GrandID API REST+JSON Developer documentation Version Date Author Comments 0.1 2014­03­25 Mikael Westöö Document is created 0.2 2014­03­26 Jang Kee First draft done. 0.3 2014­04­06 Mikael Westöö SOAP version 1.6 0.4 2014­12­15 Mikael Westöö JSON REST spec. 0.5 2015­01­19 Patrik Grinsvall Changed endpoints 0.6 2015­01­20 Patrik Grinsvall Fixed spelling errors 0.7 2015­01­21 Mikael Westöö Added generic info 0.8 2015­04­24 Patrik Grinsvall Changed JSON endpoint to version 1.1 0.9 2015­05­14 Hjalmar Wåhlander Added access marker 1.0 2015­05­19 Abdallah Saidane Fix links Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (1/12) Summary 1 ­ Introduction 1.1 ­ What you should already know 1.2 ­ Prerequisites 2 ­ Implementation 2.1 ­ Process schematics over GrandID API 2.2 ­ Explanation of schematics over GrandID API 3 ­ API documentation 3.1 ­ Introduction 3.2 ­ FederatedLogin 3.3 ­ GetSession 3.4 ­ FederatedDirectLogin 3.5 ­ Logout 4. Examples 4.1 PHP 4.2. C# Public This document is intended for public access. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (2/12) 1 ­ Introduction In this document, we specify the API and flow of events that will cover the functions of GrandID. 1.1 ­ What you should already know Before you read this document, you should have a basic understanding a programming language as well as JSON. 1.2 ­ Prerequisites Before starting ●
●
apiKey ­ Will be sent to you by mail authenticateServiceKey ­ Will be sent together with your apiKey 1.3 ­ How to detect a successfull login When you call the GetSession method you will get a json response. If this response contains a “username” key, this means the login is successfull. Example: { "sessionId":"d04a78214b193973ecc121d2f4b3a1e0", "username":"SE123123123123­1234", "userAttributes":{ "serialNumber":"SE123123123123­1234", "lastname":"Andersson", "firstname":"Anders" } } Note! The “userAttributes” object is different from each login methods. 2 ­ Implementation The client applicationAPI needs to do two REST request to GrandID API services as described below. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (3/12) 2.1 ­ Process schematics over GrandID API 2.2 ­ ​
Explanation of schematics over GrandID ​
API 1) HTTP request to ​
https://client.grandid.com/json1.1/FederatedLogin 2) with your apiKey and authenticateServiceKey as GET parameters as well as a callbackUrl where we will redirect the authenticated user. 3) JSON response containing a redirectUrl and a sessionId is returned. 4) Your website should now redirect the browser to the redirectUrl. 5) GrandID will authenticate the user and redirect the user back to the url specified by the callbackUrl parameter. 6) The web application calls the API method GetSession at https://client.grandid.com/json1.1/GetSession​
together with apiKey, authenticateServiceKey and the session id returned from FederatedLogin 7) The response from GetSession is returning the user information. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (4/12) 3 ­ API documentation 3.1 ­ Introduction In order to access GrandID services from a mobile/web application you will use our JSON API. Address for test: https://client­test.grandid.com/json1.1/ Address for prod: https://client.grandid.com/json1.1/ Format: https://client­test.grandid.com/json1.1/​
<function>?apiKey=xxxxx&authenticateServiceKey=xxxxx
&callbackUrl=<url to return to after authentication> Examples: https://client­test.grandid.com/json1.1/FederatedLogin?apiKey=7172342344­22bc­4234234­b5e
4­85c423424d12a&authenticateServiceKey=f524234ntu82342134kr8r&callbackUrl=<url to return to after authentication> https://client­test.grandid.com/json1.1/GetSession?sessionid=fenf5hf845hf4587h45&apiKey=71
72342344­22bc­4234234­b5e4­85c423424d12a&authenticateServiceKey=f524234ntu82342134
kr8r 3.2 ­ FederatedLogin ­Function String FederatedLogin(String apiKey, String authenticateServiceKey, string callbackUrl) ­Location https://client.grandid.com/json1.1/FederatedLogin https://client­test.grandid.com/json1.1/FederatedLogin ­Description This is the function to log in using an apiKey, authenticateServiceKey and a callbackUrl. The return value will be a sessionid and a return URL. Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (5/12) ­Return Value JSON response from service. ­Parameter table Name Type Value type Default value Multiple values Formated Values apiKey String Mandatory No authenticateServiceKey String Mandatory No callbackUrl String Mandatory No ­Output example: {"sessionId":"08efba128c49aa41bf62c27974f1a3cf","redirectUrl":"https://login.grandid.c
om/?sessionid=xxxxxxxxx"} 3.3 ­ GetSession Will return a JSON reponse with all the user data. ­Function GetSession(String sessionid, String apiKey, String authenticateServiceKey) ­Location https://client.grandid.com/json1.1/GetSession https://client­test.grandid.com/json1.1/GetSession ­Return Value JSON response from API. ­Parameter table Name Type Value type Default value Multiple values Formated Values sessionid String Mandatory No apiKey String Mandatory No Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (6/12) authenticateServiceKey String Mandatory No ­Output example: {"sessionId":"70011754034dc3be3c1e1d88831f0e5a","username":"mikael.westoo@e-ide
ntitet.se","userAttributes":{"mobile":"+46
735110424","sn":"Westoo","givenname":"Mikael","samaccountname":"mikael.westoo","tit
le":"CTO"}} 3.4 ­ FederatedDirectLogin ­Function String FederatedDirectLogin(String apiKey, String authenticateServiceKey, String username, String password) ­Location https://client.grandid.com/json1.1/FederatedDirectLogin https://client­test.grandid.com/json1.1/FederatedDirectLogin ­Description This is the function to log in using an apiKey, authenticateServiceKey, username and password and the return value will be user properties. ­Return Value JSON response from service. ­Parameter table Name Type Value type Default value Multiple values Formated Values apiKey String Mandatory No authenticateServiceKey String Mandatory No username String Mandatory No password String Mandatory No Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (7/12) ­Output example: {"sessionid":"70011754034dc3be3c1e1d88831f0e5a","username":"mikael.westoo@e-ide
ntitet.se","userAttributes":{"mobile":"+46
735110424","sn":"Westoo","givenname":"Mikael","samaccountname":"mikael.westoo","tit
le":"CTO"}} 3.5 ­ Logout ­Function String Logout(String Session, String apiKey, String authenticateServiceKey) ­Location https://client.grandid.com/json1.1/Logout https://client­test.grandid.com/json1.1/Logout ­Description This is the function to logout a user from an IDP. ­Return Value JSON response from service. ­Parameter table Name Type Value type Default value Multiple values Formated Values sessionid String Mandatory No apiKey String Mandatory No authenticateServiceKey String Mandatory No ­Output example: {"sessiondeleted":"1"} Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (8/12) 4. Examples You can download GrandID API examples from this link: https://bitbucket.org/grandid/grandid­client­demo 4.1 PHP Minimalistic example: <?php $apiKey = "yourApiKey"; $authenticateServiceKey = "yourAuthenticateServiceKey"; $callbackUrl = "http://yoursite.com"; if(!isset($_GET['grandidsession'])) { $url = "​
https://client­test.grandid.com/json1.1/FederatedLogin?authenticateServiceKey=​
". $authenticateServiceKey."&apiKey=".$apiKey."&callbackUrl=".$callbackUrl; $result = json_decode(trim(file_get_contents($url)),1); header("Location: " . $result['redirectUrl']); } else { $response = file_get_contents("​
https://client­test.grandid.com/json1.1/GetSession?authenticateServiceKey=​
". $authenticateServiceKey."&apiKey=".$apiKey."&sessionid=".$_GET['grandidsession']); echo "<pre>".print_r(json_decode($response,1),1)."</pre>"; } Here is a PHP­example on how to use the Grandid API. <?php
/**
* GrandID API example usage
* Return JSON
* v 2.0.3
* @author Grandid
*/
/**
* @var string Service Url
*/
$service_url = 'https://client.grandid.com';
/**
* @var string api Key
Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (9/12) */
$apiKey = "APIKEY";
/**
* @var string authenticate Service Key
*/
$authenticateServiceKey = "AUTHENTICATESERVICEKEY";
/**
* @var string callback Url
*/
$callbackUrl = (($_SERVER['SERVER_PROTOCOL'] == 'HTTP/1.1') ? "http://" : "https://") .
$_SERVER['HTTP_HOST'] . "" . $_SERVER['REQUEST_URI'];
if (!isset($_GET['grandidsession'])) {
// Set the request URL
$url = sprintf("%s/json1.1/FederatedLogin?apiKey=%s&authenticateServiceKey=%s&callbackUrl=%s",
$service_url, $apiKey, $authenticateServiceKey, urlencode($callbackUrl));
// Issue the request to the Grandid Rest Service
$response = file_get_contents($url);
// Decode the JSON response
$login_response = json_decode($response);
// Get the RedirectUrl from the result
print '<h1>Login</h1>';
print '<a class="btn btn-default" href="'.$login_response ->RedirectUrl.'" role="button">Click here to
login</a>';
} else {
// Set the request URL to retrieve User Profile
$url = sprintf("%s/json1.1/GetSession?apiKey=%s&authenticateServiceKey=%s&sessionid=%s",
$service_url, $apiKey, $authenticateServiceKey, $_GET['grandidsession']);
// Issue the request to the GrandID API
$response = file_get_contents($url);
// Profile information for the current user
print '<h1>Profile information for the current user</h1>';
print '<pre><code>';
print $response;
print '</code></pre>';
}
Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (10/12) 4.2. C# using
using
using
using
using
using
using
System;
System.Collections.Generic;
System.IO;
System.Linq;
System.Net;
System.Text;
System.Threading.Tasks;
/**
* GrandID API example usage
* Return JSON
* v 2.0.3
* @author Grandid
*/
namespace GrandidRest
{
class GrandidRest
{
/**
* @var string Service Url
*/
static string service_url = "https://client.grandid.com";
/// <<< PARAMETERS - NEED TO BE CHANGED IF YOU CALL A DIFFERENT FLOW CONTROL (LOGIN
METHOD)
/**
* @var string api Key
*/
static string apiKey = "APIKEY";
/**
* @var string authenticate Service Key
*/
static string authenticateServiceKey = "AUTHENTICATESERVICEKEY";
/// >>> PARAMETERS - NEED TO BE CHANGED IF YOU CALL A DIFFERENT FLOW CONTROL (LOGIN
METHOD)
/**
* @var string callback Url
*/
static string callbackUrl = "http://yourdomain.com/yourlocalfiles.aspx";
/**
* The following method issues a request and returns the entire response as one long string
*/
public static string HttpGet(string requestUrl)
{
try
Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (11/12) {
HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;
using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
{
if (response.StatusCode != HttpStatusCode.OK)
throw new Exception(String.Format(
"Server error (HTTP {0}: {1}).",
response.StatusCode,
response.StatusDescription));
string result = null;
StreamReader reader = new StreamReader(response.GetResponseStream());
result = reader.ReadToEnd();
return result;
}
}
catch (Exception e)
{
Console.WriteLine(e.Message);
return null;
}
}
/**
* get Login url
*/
public string LoginRequest()
{
// Issue the request to the Grandid Rest Service
return
HttpGet(String.Format("{0}/json1.1/FederatedLogin?apiKey={1}&authenticateServiceKey={2}&callbackUrl={3
}", service_url, apiKey, authenticateServiceKey, callbackUrl));
}
/**
* Get Profile information for the current user
*/
public string GetUserProfile(string grandidsession)
{
// Issue the request to the Grandid Rest Service
return
HttpGet(String.Format("{0}/json1.1/GetSession?apiKey={1}&authenticateServiceKey={2}&sessionid={3}",
service_url, apiKey, authenticateServiceKey, grandidsession));
}
}
}
Svensk e­identitet AB Vaksalagatan 6 Org. nr: 556776­6992 753 20 Uppsala Tel: +46 18 481 19 00 www.grandid.com​
Page (12/12)