avant de commencer
Avant de commencer, merci de lire les informations ci-dessous et de suivre toutes les instructions.
Vous pourrez ensuite passer à la section « pour commencer ».
deux choses à faire avant de commencer
sur l'API Manager
deux choses à faire avant de commencer
Pour commencer à tester cette API, assurez-vous d'avoir bien lu et compris la section sur les
Personal APIs (alpha) section
Ensuite, une fois dans l'API Manager, vous pourrez vous inscrire à la Personal Profile API.
|
sur l'API Manager
L'administrator web interface vous permet de contrôler et de configurer tous les aspects de vos inscriptions aux Personal APIs alpha.
Vous pourrez notamment :
obtenir l'autorisation d'utiliser les API
solliciter votre inscription aux APIs de votre choix
obtenir l'acceptation de votre inscription
puis recevoir votre clé d'accès, vos points de terminaison HTTP, vos exemples de code et la documentation technique
|
|
Les étapes ci-dessous décrivent des aspects importants de l'interface
La première fois que vous vous connecterez à l'API Manager, nous vous demanderons de remplir un formulaire pour nous fournir des informations incluant :
l'URL de votre site Web
le nom de votre site Web
le logo de votre site Web
Ces informations nous aideront à valider votre inscription.
Les informations que vous nous fournirez sur le site Web seront communiquées aux utilisateurs pour leur permettre de définir leurs paramètres en matière de respect de la vie privée et de déterminer s'ils vous autoriseront, vous, le développeur, à accéder à leurs informations personnelles via les Personal APIs.
Vous aurez ensuite accès à un écran vous permettant de solliciter une inscription à n'importe laquelle des API.
Souvenez-vous que vous DEVEZ d'abord vous inscrire à la Personal Profile API.
Une fois votre inscription validée, vous recevrez un e-mail et un fichier ZIP contenant les éléments suivants :
Votre clé d'accès (SERVICE_ID et SERVICE_PWD).
Le URL de l'API
Les exemples de codes.
Les instructions d'utilisation relatives à tous ces éléments.
accédez à l' API Manager
pour commencer
Maintenant que vous avez lu la section « avant de commencer » et que l'API Manager vous est plus familière, vous êtes prêt à en savoir plus sur…
quelles informations de profil peuvent-elles être recherchées et extraites ?
extraire des informations de profil
quelles informations de profil peuvent-elles être recherchées et extraites ?
Les informations de profil peuvent être obtenues en utilisant l'Authentication API.
Les données peuvent être utilisées pour préremplir automatiquement des formulaires, simplifiant ainsi l'expérience utilisateur et les interactions sur votre site Web.
Les informations de profil suivantes peuvent être recherchées et extraites :
nom
prénom
genre (Mlle, Mme, M)
adresse e-mail
adresse postale
code postal
localité
pays
date de naissance
numéro de portable *
numéro de téléphone fixe *
numéro de fax *
type d'utilisateur (Internet, mobile, Internet et mobile, utilisateur inscrit non abonné) *
* L'accès à ces données requiert une autorisation préalable d'Orange. Veuillez nous contacter si vous avez besoin de cette information.
Quelques informations à retenir :
Tous les attributs n'ayant pas nécessairement été remplis par les utilisateurs, Orange ne garantit pas la disponibilité de l'intégralité de ceux-ci.
Un utilisateur devra toujours donner son consentement pour la transmission de ses données personnelles par Orange (via la fonctionnalité respect de la vie privée).
Notez que si vous utilisez déjà l'Authentication API à une fin différente (par ex. pour rechercher et extraire un jeton d'utilisateur pour appeler d'autres Personal APIs et/ou déléguer l'authentification de l'utilisateur Orange à la plateforme Orange), vous devez simplement ajouter un paramètre supplémentaire dans les requêtes d'authentification que vous envoyez à Orange en utilisant l'Authentication API.
extraire des informations de profil
Pour rechercher et extraire des informations de profil, vous devez procéder comme suit :
envoyer une requête d'authentification à Orange
extraire l'identifiant de l'utilisateur (identifiant du nom) contenu dans la réponse d'authentification
envoyer une requête d'authentification à Orange
La requête d'authentification est envoyée au fournisseur d'identité d'Orange via le navigateur, sur la base d'une redirection HTTP 302.
Veuillez noter que la requête SAML doit être compressée au format ZIP à l'aide de DEFLATE puis envoyée comme paramètre d'URL encodé en Base64.
Dans la requête SAML, vous devez ajouter un paramètre doté d'une valeur indiquant les données que vous souhaitez rechercher et extraire (il s'agit d'un masque binaire sur une liste de données prédéfinie). Dans l'exemple ci-dessous, la valeur « AttributeConsumingServiceIndex=18 » renverra le nom d'affichage et l'adresse e-mail de l'utilisateur.
Ci-dessous, un exemple de requête d'authentification SAML :
|
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>
|
Ci-dessous, un exemple de code PHP utilisé pour générer et envoyer la requête:
|
<?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]" ) );
?>
|
Extraire les données de l'utilisateur contenues dans la réponse d'authentification
Pour rechercher et extraire les données de l'utilisateur contenues dans la réponse SAML, vous devez simplement :
décoder la réponse SAML en Base64 reçue dans la requête HTTP POST
analyser la réponse SAML (document XML) pour trouver les attributs.
vous rechercherez et extrairez un attribut en utilisant l'expression XPATH suivante :
|
/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")
|
Ci-dessous, un exemple de réponse d'authentification SAML :
|
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> |
Ci-dessous, un exemple de code PHP pour traiter la réponse :
|
<?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>
|
Mise en correspondance des noms d'attributs et des données de profil d'utilisateur :
| données de profil d'utilisateur correspondantes |
nom d'attribut |
| 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 |
(haut de page)
