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 Authentication API and access the administrator web interface.
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 Authentication 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 administrator web interface, you're ready to create a "hello world" application and learn about the API methods.
Once you are familiar with this section, take a look at the "application example" to get a feel of how they are used in an application.
how to retrieve a user token to call other Personal APIs
User authentication is a key action that needs to be carried out for every web session.
For a successful authentication, a user token must be retrieved which contains proofs of a user authenticated at Orange.
This token is mandatory to interact with the other Personal APIs in the suite.
The diagram below shows how the user token is sent and received between the entities:

To retrieve a user token you need to do the following:
send an authentication request to Orange
retrieve the user token contained in the authentication response
send an authentication request to Orange
This section refers to "request 2" of the diagram above.
The authentication request is sent to 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.
Below is an example of a SAML authentication request:
|
HTTP redirection from user's browser to Orange:
[IDP_SingleSignOnURL]?SAMLRequest=PEF1dGhuUmVxdWVzdC B4bWxucz1cInVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDpwcm9 0b2NvbFwiICBJRD1cIl9iMDUwZTBmNGM2NzNlYzI1NzJmYzY1ZDk 1MzU5YWZlNlwiIFZlcnNpb249XCIyLjBcIiBJc3N1ZUluc3RhbnQ9XCI yMDA3LTAxLTE2VDE2OjU0OjAwWlwiID48SXNzdWVyIHhtbG5zPV widXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOmFzc2VydGlvbl wiPmh0dHA6Ly9teXNwPC9Jc3N1ZXI+PC9BdXRoblJlcXVlc3Q+DQ o%3D
Requête SAML décodée :
<AuthnRequest xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="_b050e0f4c673ec2572fc65d95359afe6" Version="2.0" IssueInstant="2007-01-16T16:54:00Z" > <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");
## <AuthnRequest> $authnRequest = "<AuthnRequest xmlns=\"urn:oasis:names:tc:SAML:2.0:protocol\" " . "ID=\"_" . $id . "\" " . "Version=\"2.0\" " . "IssueInstant=\"" . $issueInstant . "\">\n" . "<Issuer xmlns=\"urn:oasis:names:tc:SAML:2.0:assertion\">" . $issuer . "</Issuer>\n" . "</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 token contained in the authentication response
This section refers to "request 4" of the diagram above.
To retrieve the user token 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 user token. You will retrieve it using the XPATH expression
/samlp:Response/saml:Assertion/saml:AttributeStatement/
saml:Attribute[@Name='OrangeAPIToken']/saml:AttributeValue
The user token looks like this:
|
B64W7ElXGlIgvEdGOqlH9zuQQoSu1CS4QOSv9/NoPtNva4psRc +c5BFR3z0xc3DkZrelwNonn+fVG41RDBWZfdYovGxJvXZ9NTSLk MZeQwmN08=|sau=UNAVAILABLE|ted=1200503587|oJkued8sD2 qnZiMj2HIDyLrpkhM=
|
Please note that the user token must be URL encoded when requesting other Personal APIs.
Below is an example of a SAML authentication response:
|
Requête SAML décodée :
<Response xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="dBKSwXQJpOBJBRjDjuMnWBGS6ygNXHZR" Version="2.0" IssueInstant="2008-01-16T16:54:10Z" Destination="[SERVICE_RETURN_URL]" InResponseTo="_b050e0f4c673ec2572fc65d95359afe6"> <Status> <StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </Status> <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="z2gQhxaMMUVVUOsji3HOO2o95QyqupLv" Version="2.0" IssueInstant="2008-01-16T16:54:01Z"> <Issuer>[IDP_ID]</Issuer> <Subject> <NameID Format="urn:oasis:names:tc:SAML:2.0:nameidformat:transient"> YFOzpbiBX0zAJ61BI5jIRrze3ygWxW4V </NameID> <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <SubjectConfirmationData Recipient="[SERVICE_RETURN_URL]" NotOnOrAfter="2008-01-16T17:09:01Z" InResponseTo="_b050e0f4c673ec2572fc65d95359afe6"/> </SubjectConfirmation> </Subject> <Conditions> <AudienceRestriction> <Audience>[SERVICE_ID]</Audience> </AudienceRestriction> </Conditions> <AuthnStatement AuthnInstant="2008-01-16T16:54:15Z"> <AuthnContext> <AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:Password </AuthnContextClassRef> </AuthnContext> </AuthnStatement> <AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Attribute Name="OrangeAPIToken" NameFormat="urn:oasis:names:tc:SAML:2.0:profiles:attribute:basic"> <AttributeValue xsi:type="xs:string"> B64W7ElXGlIgvEdGOqlH9zuQQoSu1CS4QOSv9/NoPtNva4psRc+ c5BFR3z0xc3DkZrelwNonn+fVG41RDBWZfdYovGxJv XZ9NTSLkMZeQwmN08=|sau=UNAVAILABLE|ted= 1200503587|oJ kued8sD2qnZiMj2HIDyLrpkhM= </AttributeValue> </Attribute> </AttributeStatement> </Assertion> </Response>
|
Below is an example of PHP code to process the response:
|
<?php # decode the response $authnResponse = base64_decode($_POST['SAMLResponse']); # get data from XML $xml = simplexml_load_string($authnResponse); # user token $xml->registerXPathNamespace("samlp", "urn:oasis:names:tc:SAML:2.0:protocol"); $xml->registerXPathNamespace("saml", "urn:oasis:names:tc:SAML:2.0:assertion"); $token = $xml->xpath("/samlp:Response/saml:Assertion/saml: AttributeStatement/saml:Attribute [@Name='OrangeAPIToken']/saml:AttributeValue"); if (count($token)>0) $token = $token[0]; # the user token can then be used to call other Personal APIs… ?>
|
(back to top)
application example
Below you will find an application example that makes use of the API methods.
This will give you a good starting point to help you with your development.
how to use the API to simplify access to a website
If your website requires visitors to register, the Authentication API can help you facilitate this process for Orange France customers.
In many cases, the registration process can be a barrier and visitors often abandon the process.
You can use the API to send the user to the Orange identity platform and as a result, the user can directly access your web services without creating a new account and without filling in a registration form.
All you have to do is to integrate the Authentication API and insert a "sign-in with my Orange account" button on your website's sign-in page (this button is provided by Orange).
Orange does not replace your own identity management system. The user that authenticates on your website using the API is your registered user.
retrieving customer profile data for the first time:
When an Orange customer accesses your website through the Orange identity platform for the first time, Orange can send back to your website the user's profile data needed to pre-fill your registration form.
The data list will be configured on a case-by-case basis and will be of the following:
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)
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).
Please note that if you have also registered to other Personal APIs , the SAML response will automatically contain a user token to be used when calling these APIs
(see how to retrieve a user token to call other Personal APIs for more details).
The diagram below shows how the user is authenticated using the Orange authentication platform.

To send Orange customers to the Orange identity platform 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
This section refers to "request 2" of the diagram above.
The authentication request is sent to 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.
Below is an example of a SAML authentication request:
|
HTTP redirection from user's browser to Orange:
[IDP_SingleSignOnURL]?SAMLRequest=PEF1dGhuUmVxdWVzdCB4 bWxucz1cInVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDpwcm90b2Nv bFwiICBJRD1cIl9jYzgzNGMxODFmYzA0MDhjOTgzY2I1NWY4ZWZlYzI4 OVwiIFZlcnNpb249XCIyLjBcIiBJc3N1ZUluc3RhbnQ9XCIyMDA3LTEyLT IxVDIwOjI0OjQ3WlwiID48SXNzdWVyIHhtbG5zPVwidXJuOm9hc2lzOm5 hbWVzOnRjOlNBTUw6Mi4wOmFzc2VydGlvblwiPmh0dHA6Ly9teXNwP C9Jc3N1ZXIPE5hbWVJRFBvbGljeSBGb3JtYXQ9XCJ1cm46b2FzaXM6 bmFtZXM6dGM6U0FNTDoyLjA6bmFtZWlkLWZvcm1hdDpwZXJzaXN0Z W50XCIgIEFsbG93Q3JlYXRlPVwidHJ1ZVwiLz48L0F1dGhuUmVxdWV zdD4%3D
Requête SAML décodée :
<AuthnRequest xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="_cc834c181fc0408c983cb55f8efec289" Version="2.0" IssueInstant="2007-12-21T20:24:47Z" > <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion"[SERVICE_ID]</Issuer> <NameIDPolicy Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" AllowCreate="true"/> </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");
## <AuthnRequest> $authnRequest = "<AuthnRequest xmlns=\"urn:oasis:names:tc:SAML:2.0:protocol\" " . "ID=\"_" . $id . "\" " . "Version=\"2.0\" " . "IssueInstant=\"" . $issueInstant . "\">\n" . "<Issuer xmlns=\"urn:oasis:names:tc:SAML:2.0:assertion\">" . $issuer . "</Issuer>\n" . "<NameIDPolicy " . "Format=\"urn:oasis:names:tc:SAML:2.0:nameid-format:persistent\" " . "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 identifier (name identifier) contained in the authentication response
This section refers to "request 4" of the diagram above.
To retrieve the user's identifier (name identifier) contained in the SAML response, you simply have to:
check the signature
check the <status> element - this should be a success - urn:oasis:names:tc:SAML:2.0:status:Success
check the <SubjectConfirmationData> element - "Recipient" must be equal to the URL where the response is received and
"NotOnOrAfter" date must not be passed
check the <Audience> element - this MUST be equal to technical identifier of the third party service provider
parse the SAML response (XML document) to find the <NameID> element - this is the name Identifier
The name Identifier looks like this:
|
4b124ae2-0126-102b-8852-001a641049bb
|
As long as the user wishes to maintain a link between its user account at your website and his Orange user account, Orange will send you the same name Identifier when this user signs-in against your website through Orange. Therefore you have to store this identifier in your service database.
Below is an example of a SAML authentication response:
|
Requête SAML décodée :
<Response xmlns="urn:oasis:names:tc:SAML:2.0:protocol" ID="jw0BhUnqZ5rvjx5UlnLKszkWvZteYg56" Version="2.0" IssueInstant="2007-12-21T20:24:51Z" Destination="[SERVICE_RETURN_URL]" InResponseTo="_cc834c181fc0408c983cb55f8efec289"> <Status> <StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/> </Status> <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="EtnKtS6DKwiisFLg5DTEgtt868MccfYI" Version="2.0" IssueInstant="2007-12-21T20:24:51Z"> <Issuer>[IDP_ID]</Issuer> <Subject> <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"> 4b124ae2-0126-102b-8852-001a641049bb </NameID> <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <SubjectConfirmationData Recipient="[SERVICE_RETURN_URL]" NotOnOrAfter="2007-12-21T20:39:51Z" InResponseTo="_cc834c181fc0408c983cb55f8efec289"/> </SubjectConfirmation> </Subject> <Conditions> <AudienceRestriction><Audience>[SERVICE_ID]</Audience> </AudienceRestriction> </Conditions> <AuthnStatement AuthnInstant="2007-12-21T20:24:51Z"> <AuthnContext> <AuthnContextClassRef> urn:oasis:names:tc:SAML:2.0:ac:classes:Password </AuthnContextClassRef> </AuthnContext> </AuthnStatement> </Assertion> </Response>
|
Below is an example of PHP code to process the response:
|
<?php
require_once('idpMetadata.php');
function checkSimpleSignature($params, $cert) { $samlResponse = @base64_decode( $params['SAMLResponse'] ); $signature = @base64_decode($params['Signature']); $sigAlg = $params['SigAlg']; if ((strcmp($sigAlg, "http://www.w3.org/2000/09/xmldsig#dsa-sha1") != 0) && (strcmp($sigAlg, "http://www.w3.org/2000/09/xmldsig#rsa-sha1") != 0)) { throw new Exception("Signature algorithm ".$sigAlg." is not supported"); } if ( isset($params['RelayState'] ) ) { $signedData = "SAMLResponse=".$samlResponse. "&RelayState=".$params['RelayState']."&SigAlg=".$sigAlg; } else { $signedData = "SAMLResponse=".$samlResponse."&SigAlg=".$sigAlg; } return (@openssl_verify($signedData, $signature, $cert)); }
# Decode the response $encodedAuthnResponse = $_POST['SAMLResponse']; $authnResponse = @base64_decode($encodedAuthnResponse);
# Get some useful data from XML $xml = simplexml_load_string($authnResponse); $status = (string)$xml->{'Status'}->{'StatusCode'}['Value']; if ($status != "urn:oasis:names:tc:SAML:2.0:status:Success") { // Can be internal error, authentication failure, … // or the user refused when consent was asked ? throw new Exception("Status is not success : ". (string)$xml->{'Status'}->{'StatusMessage'}); } // Technical identifier of the IDP $idpProvider = (string)$xml->{'Assertion'}->{'Issuer'}; // Federation NameIdentifier to be used as a key to identify the user on SP side $nameID = (string)$xml->{'Assertion'}->{'Subject'}->{'NameID'}; // Authentication context $authnContext = (string)$xml->{'Assertion'}->{'AuthnStatement'}-> {'AuthnContext'}->{'AuthnContextClassRef'}; // Validity date of the assertion (to be checked by the SP) $notOnOrAfter = (string)$xml->{'Assertion'}->{'Subject'}->{'SubjectConfirmation'} ->{'SubjectConfirmationData'}['NotOnOrAfter']; $recipient = (string)$xml->{'Assertion'}->{'Subject'}->{'SubjectConfirmation'} ->{'SubjectConfirmationData'}['Recipient']; $audience = (string)$xml->{'Assertion'} ->{'Conditions'}->{'AudienceRestriction'}->{'Audience'};
# Verification of signature $ret = checkSimpleSignature($_POST, $idpMetadata[$idpProvider]['certificate']); if ($ret != 1) { throw new Exception("Signature is not valid"); }
# Verification of validity of the assertion // Check the $notOnOrAfter parameter (date MUST not be passed) if (gmdate('Y-m-d\TH:i:s\Z') > $notOnOrAfter){ throw new Exception("Authentication failed: validy period expires"); } // Check the $audience parameter (MUST be equal to the [SERVICE_ID]) if ($audience != "[SERVICE_ID]"){ throw new Exception("Authentication failed: authencation token was not for [SERVICE_ID] but for " . $audience); } // Check the $recipient parameter (MUST be equal to the URL where this response is received)
# Profile attributes (only transmitted at first time access and if authorized by Orange) $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> Signature : <?php echo $ret ?> <BR> Status : <?php echo $status ?> <BR> IDP : <?php echo $idpProvider ?> <BR> NameID : <?php echo $nameID ?> <BR> AuthnContext : <?php echo $authnContext ?> <BR> NotOnOrAfter : <?php echo $notOnOrAfter ?> <BR> Recipient : <?php echo $recipient ?> <BR> Audience : <?php echo $audience ?> <BR> <BR> 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)