home forums become a member Français
 
site search
our programme mobile apps & solutions other innovation APIs news & events


 documentation


Here, you'll find all of the technical information you need to enable you to start developing with the API.


We've tried to make it easy for you, by breaking the information down into clear areas: 
before getting started, getting started and application example.


When you have finished with this section, go to the API Manager


Authentication API

  •      before getting started     
  •      getting started      
  •      application example     
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)

related APIs

 Personal Calendar API alpha
 Personal Contacts API alpha
 Personal Content API alpha
 Personal Favourites API alpha
 Personal Messages API alpha
 Personal Photos API alpha
 Personal Profile API alpha
 Personal RichProfile API alpha

something not clear?

if you're stuck, get in touch with us at developers@orange.com

share your views

Use the forum to share your views and start a discussion about this API or
ask technical questions.

access the forum