before getting started
Before getting started, please read the information below, and follow any instructions.
You'll then be ready to move onto the 'getting started' section.
two things to do before you get started
all about the API manager
two things to do before you get started
To start playing with this API, please make sure you have read and understood the
Personal APIs (alpha) section
 |
You need to be an Orange Partner Member in order to use the
Personal Profile API and access the API Manager.
If not already, become an Orange Partner member now
|
 |
Access the API Manager |
And then, within the API Manager, you'll be able to subscribe to the Personal Profile API.
|
all about the API Manager
The API Manager allows you to control and configure all aspects of your Personal APIs alpha subscriptions.
Specifically you'll be able to:
gain immediate approval to use the APIs
request subscription to any or all of the APIs
gain approval for your subscription
and then receive your access key, endpoint URLs, sample codes and advanced technical documentation
|
|
The steps below describe important aspects of the interface:
The first time you log on to the API Manager, we will ask you to fill in a form to provide us with information that includes:
your website URL
your website name
your website logo
This information will help us validate your subscription.
The website information you provide will be displayed to the users to enable them to set their privacy settings, and will determine if the users will allow you - the developer - to access their personal information via the Personal APIs.
You will then have access to a screen, allowing you to request a subscription to any of the APIs.
Remember, you MUST subscribe to the Authentication API first.
Once your subscription has been validated, you will receive an email and a ZIP file containing the following:
Your access key (SERVICE_ID and SERVICE PWD)
The API endpoint URL
Sample codes
Instructions on how to use it all.
access the API Manager
getting started
Now that you've read the 'before getting started' section, and become familiar with API Manager, you're ready to learn about...
what profile information can be retrieved?
retrieving profile information
what profile information can be retrieved?
Profile information can be obtained using the Authentication API.
The data can be used to automatically pre-fill forms - simplifying user experience and interaction on your website.
The following profile information can be retrieved:
gender
display name
given name
surname
email address
street address
postal code
locality
country
date of birth
mobile phone number *
fix line phone number *
fax phone number *
user type (internet, mobile, internet&mobile, non-subscriber registered user) *
* This data requires prior authorisation from Orange. Please contact us if you require this information.
A few things to note:
Not all attributes may have been collected from / provided by the user and so availability of all attributes is not guaranteed by Orange.
A user will always have to give consent for the release of its data at the Orange side (done through the privacy function).
Note that if you are already using the Authentication API for another purpose (e.g. to retrieve a user token to call other Personal APIs and/or delegate Orange's user authentication to the Orange platform), you just need to add an additional parameter in the authentication requests you send to Orange using the Authentication API.
retrieving profile information
To retrieve profile information you need to do the following:
send an authentication request to Orange
retrieve the user's identifier (name identifier) contained in the authentication response
send an authentication request to Orange
The authentication request is sent to the Orange Identity provider via the browser, based on an HTTP 302 redirection.
Please note that the SAML request has to be zipped with DEFLATE and then sent as a Base64-encoded URL parameter.
In the SAML request, you must add a parameter with a value which indicates the data you would like to retrieve (it is a bitmask on a pre-defined list of data). In the example below, the value "AttributeConsumingServiceIndex=18" will return the user's display name and email address.
Below is an example of a SAML authentication request:
|
HTTP redirection from user's browser to Orange:
[IDP_SingleSignOnURL]?SAMLRequest=jZAxT8MwFIR3foXlPcROo9
i1kkgRXSrBQhEDC3
LNa2qpsVO%2FZ1T%2BPRYsjKx3p%2B9O10%2BZzuEZrhmQ2G
25BBx4TsFEix5NsAugIWcO09Ojae6FWVOk6OKFs%2F1u4O8b3
Wmw7WkDWyWV6JrGuUa59tQdO6u2wNlElPwxEzzEgHnxYT5A%
2BvQO9uEDbgOXmrNXSOhjGHhpKGDEXFwkG6hIQuhKNJXQL7
IzUplWvnE23vU%2FsfSfzRYREpUCPp6JVlPXyxeu1TzHvv6lFFz994
nxGw%3D%3D">http://idp/sso?SAMLRequest=jZAxT8MwFIR3foXl
PcROo9i1kkgRXSrBQhEDC3LNa2qpsVO%2FZ1T%2BPRYsjKx3p%
2B9O10%2BZzuEZrhmQ2G25BBx4TsFEix5NsAugIWcO09Ojae6FWV
Ok6OKFs%2F1u4O8b3Wmw7WkDWyWV6JrGuUa59tQdO6u2wNlE
lPwxEzzEgHnxYT5A%2BvQO9uEDbgOXmrNXSOhjGHhpKGDEXFwkG6hI
QuhKNJXQL7IzUplWvnE23vU%2FsfSfzRYREpUCPp6JVlPXyxeu1
TzHvv6lFFz994nxGw%3D%3D
Decoded SAML request:
<AuthnRequest xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
ID="_3868ea4f3e97170622cc27c4f6b6a79e"
AttributeConsumingServiceIndex="18"
Version="2.0"
IssueInstant="2008-02-08T16:17:41Z">
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">[SERVICE_ID]</Issuer>
</AuthnRequest>
|
Below is an example of the PHP code used to generate and send the request:
|
<?php
function randomhex($length)
{
$key = "";
for ( $i=0; $i < $length; $i++ )
{
$key .= dechex( rand(0,15) );
}
return $key;
}
## Metadata
require_once("idpMetadata.php");
$issuer = "[SERVICE_ID]";
$idpTargetUrl = $idpMetadata['[IDP_ID]']['SingleSignOnUrl'];
## Dynamic data of the SAML request
$id = randomhex(32);
$issueInstant = gmdate("Y-m-d\TH:i:s\Z");
$attributeConsumingServiceIndex = 18; #this is an example
## <AuthnRequest>
$authnRequest =
"<AuthnRequest xmlns=\"urn:oasis:names:tc:SAML:2.0:protocol\" " .
"ID=\"_" . $id . "\" " .
"Version=\"2.0\" " .
"IssueInstant=\"" . $issueInstant . "\">\n" .
AttributeConsumingServiceIndex=\"" . $attributeConsumingServiceIndex . "\">\n" .
"<Issuer xmlns=\"urn:oasis:names:tc:SAML:2.0:assertion\">" .
$issuer . "</Issuer>\n" .
"<NameIDPolicy " .
"AllowCreate=\"true\"/>" .
"</AuthnRequest>";
## HTTP-Redirect Binding
$encodedAuthnRequest = urlencode( base64_encode( gzdeflate( $authnRequest ) ));
$redirectUrl = $idpTargetUrl . "?SAMLRequest=" . $encodedAuthnRequest;
## Redirect
Header("Location: ".$redirectUrl);
?>
"idpMetadata.php" configuration file (used in previous code example):
<?php
# The partner SP must store the metadata to communicate with Orange identity provider.
$idpMetadata = array(
"[IDP_ID]" =>
array( "SingleSignOnUrl" =>"[IDP_SingleSignOnURL]",
"certificate" =>"[IDP_Certificate]" ) );
?>
|
retrieve the user's data contained in the authentication response
To retrieve the user's data contained in the SAML response, you simply have to:
decode the Base64 SAML response received in the HTTP POST request
parse the SAML response (XML document) to find the attributes.
You will retrieve an attribute using the following XPATH expression:
|
/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute
[@Name='Attribute Name']/saml:AttributeValue (using the following namespaces :
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" and
xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol")
|
Below is an example of a SAML authentication response:
|
Decoded SAML response:
<Response xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="_nS4RnQwSEXneSTLMVlq" Version="2.0"
IssueInstant="2008-02-08T16:18:22Z"
Destination="[SERVICE_RETURN_URL]"
InResponseTo="_3868ea4f3e97170622cc27c4f6b6a79e">
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://idp</Issuer>
<Status>
<StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</Status>
<Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="_B2TAbq1C3KnpSeSO4Yf"
Version="2.0" IssueInstant="2008-02-08T16:18:22Z">
<Issuer>[IDP_ID]</Issuer>
<Subject>
<NameID Format="urn:oasis:names:tc:SAML:2.0:nameidformat:transient">
5kQkvXaqjONx4d70jC5L
</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData
Recipient="[SERVICE_RETURN_URL]"
NotOnOrAfter="2008-02-08T16:33:22Z"
InResponseTo="_3868ea4f3e97170622cc27c4f6b6a79e" />
</SubjectConfirmation>
</Subject>
<Conditions>
<AudienceRestriction>
<Audience>[SERVICE_ID]</Audience>
</AudienceRestriction>
</Conditions>
<AuthnStatement AuthnInstant="2008-02-08T16:18:22Z">
<AuthnContext>
<AuthnContextClassRef>
urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
</AuthnContext>
</AuthnStatement>
<AttributeStatement>
<Attribute Name="displayname"
NameFormat="urn:oasis:names:tc:SAML:2.0:profiles:attribute:basic">
<AttributeValue xsi:type="xs:string">Claude Bertau</AttributeValue>
</Attribute>
<Attribute Name="emailaddress"
NameFormat="urn:oasis:names:tc:SAML:2.0:profiles:attribute:basic">
<AttributeValue xsi:type="xs:string">claude.bertau@orange.fr</AttributeValue>
</Attribute>
</AttributeStatement>
</Assertion>
</Response> |
Below is an example of PHP code to process the response:
|
<?php
# Decode the Response
$encodedAuthnResponse = $_POST['SAMLResponse'];
$authnResponse = @base64_decode($encodedAuthnResponse);
# Get some useful data from XML
$xml = simplexml_load_string($authnResponse);
# Profile attributes
$user_info = array();
if ($xml->{'Assertion'}->{'AttributeStatement'} &&
$xml->{'Assertion'}->{'AttributeStatement'}->{'Attribute'}) {
foreach ($xml->{'Assertion'}->{'AttributeStatement'}->{'Attribute'} as $attribute) {
$key = $attribute['Name'];
$user_info["$key"] = (string)$attribute->{'AttributeValue'};
}
}
?>
<HTML>
<BODY>
Attributes : <?php var_dump($user_info) ?>
</BODY>
</HTML>
|
Mapping between attribute names and user profile data:
| corresponding user profile data |
attribute name |
| gender |
gender |
| display name |
displayname |
| given name |
givenname |
| surname |
surname |
| email address |
emailaddress |
| street address |
streetaddress |
| postal code |
postalcode |
| locality |
locality |
| country |
country |
| date of birth |
dateofbirth |
| mobile phone number |
mobilephone |
| fixed line phone number |
homephone |
| fax phone number |
facsimile |
user type
(internet, mobile, internet&mobile,
non-subscriber registered user) |
usertype |
(back to top)
