ce qu'il faut savoir sur l'API
L'Authentication API est conforme au protocole SAML v2.
Le Security Assertion Markup Language (SAML) ou langage de balisage des énoncés de sécurité est une norme XML permettant l'échange de données d'authentification et d'autorisation entre différents domaines de sécurité, c'est-à-dire entre un fournisseur d'identité (un producteur d'énoncés) et un fournisseur de services (un consommateur d'énoncés).
Le SAML est un ensemble de spécifications produites par OASIS, un organisme de normalisation majeur dans le domaine des services Internet. Le SAML v2 complet est complexe, mais vous n'aurez pas besoin de l'implémenter en totalité puisque l'Authentication API est basée sur le profil SAML v2 le plus simple (le profil Web SSO SAML v2).
Vous avez simplement besoin de créer la requête SAML en utilisant les bibliothèques existantes ou en utilisant directement la création de documents XML. Pour la réponse SAML, vous devez simplement analyser le document XML pour obtenir l'information dont vous avez besoin.
(haut de page)
comment récupérer un jeton d'utilisateur pour appeler d'autres Personal APIs
L'authentification de l'utilisateur est une action clé qui doit être réalisée pour chaque session Web.
Pour une authentification réussie, il est nécessaire de récupérer un jeton d'utilisateur prouvant que l'utilisateur a été authentifié chez Orange.
Le jeton est obligatoire pour interagir avec les autres APIs de la suite Personal APIs.
Le diagramme ci-dessous montre comment le jeton de l'utilisateur est envoyé et reçu par les entités :
Pour récupérer un jeton d'utilisateur, vous devez procéder comme suit :
envoyer la requête d'authentification à Orange
récupérer le jeton d'utilisateur contenu dans la réponse d'authentification
envoyer une requête d'authentification à Orange
Cette section se rapporte à la « requête 2 » du diagramme ci-dessus.
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.
Ci-dessous, un exemple de requête d'authentification SAML :
|
Redirection HTTP depuis le navigateur de l'utilisateur vers Orange :
[IDP_SingleSignOnURL]?SAMLRequest=PEF1dGhuUmVxdWVzdCB4bWxucz1cInVybjpvYXNpczpuYW1lczp0YzpTQU
1MOjIuMDpwcm90b2NvbFwiICBJRD1cIl9iMDUwZTBmNGM2NzNlYzI1NzJmYzY1ZDk1MzU5YWZlNlwiIFZlc
nNpb249XCIyLjBcIiBJc3N1ZUluc3RhbnQ9XCIyMDA3LTAxLTE2VDE2OjU0OjAwWlwiID48SXNzdWVyIHhtb
G5zPVwidXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOmFzc2VydGlvblwiPmh0dHA6Ly9teXNwPC9Jc
3N1ZXI+PC9BdXRoblJlcXVlc3Q+DQo%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">http://mysp</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");
## <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):
The partner SP must store the metadata to communicate with Orange identity provider.
<?php
# The partner SP must store the metadata to communicate with Orange identity provider.
$idpMetadata = array(
"[IDP_ID]" =>
array( "SingleSignOnUrl" =>"[IDP_SingleSignOnURL]",
Certificate value goes here
-----END CERTIFICATE-----" )
);
?>
|
récupérer le jeton d'utilisateur contenu dans la réponse d'authentification
Cette section se rapporte à la « requête 4 » du diagramme ci-dessus.
Pour récupérer le jeton d'utilisateur contenu dans la réponse SAML, il vous suffit simplement :
de décoder la réponse SAML en Base64 SAML reçue dans la requête HTTP POST
d'analyser la réponse SAML (document XML) pour trouver le jeton d'utilisateur. Vous le récupérerez en utilisant l'expression XPATH
/samlp:Response/saml:Assertion/saml:AttributeStatement/saml:Attribute[@Name='OrangeAPIToken']/saml:AttributeValue
Le jeton d'utilisateur se présente comme suit :
|
B64W7ElXGlIgvEdGOqlH9zuQQoSu1CS4QOSv9/NoPtNva4psRc+c5BFR3z0xc3DkZrelwNonn+fVG41R
DBWZfdYovGxJvXZ9NTSLkMZeQwmN08=|sau=UNAVAILABLE|ted=1200503587|oJkued8sD2qnZiMj2
HIDyLrpkhM=
|
Veuillez noter que le jeton d'utilisateur doit être encodé en URL lorsque vous demandez d'autres APIs de la suite Personal APIs.
Ci-dessous, un exemple de réponse d'authentification SAML :
|
Réponse 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
+fVG41RDBWZfdYovGxJvXZ9NTSLkMZeQwmN08=|sau=UNAVAILABLE|ted=1200503587|oJ
kued8sD2qnZiMj2HIDyLrpkhM=
</AttributeValue>
</Attribute>
</AttributeStatement>
</Assertion>
</Response>
|
Ci-dessous, un exemple de code PHP pour traiter la réponse :
|
<?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…
?>
|
(haut de page)
comment utiliser l'API pour simplifier l'accès à un site Web ?
Si votre site requiert des visiteurs qu'ils s'inscrivent, l'Authentication API peut vous aider à faciliter ce processus pour les clients d'Orange France.
Dans de nombreux cas, le processus d'inscription peut constituer une barrière et les visiteurs abandonnent souvent le processus.
Vous pouvez utiliser l'API pour envoyer l'utilisateur vers la plateforme d'identification d'Orange, l'utilisateur pourra alors accéder directement à vos services Web sans créer de nouveaux comptes et sans remplir de formulaire d'inscription.
Tout ce que vous avez à faire, c'est d'intégrer l'Authentication API et d'insérer un bouton « m'identifier avec mon compte Orange » sur la page d'ouverture de session de votre site Web (ce bouton est fourni par Orange).
Orange ne remplace pas votre propre système de gestion d'identité. L'utilisateur qui s'authentifie sur votre site Web en utilisant l'API est l'utilisateur inscrit sur votre site.
récupérer les données de profil du client pour la première fois :
Lorsqu'un client Orange accède pour la première fois à votre site Web via la plateforme d'identification d'Orange, Orange peut envoyer à votre site les données du profil de l'utilisateur requises pour préremplir votre formulaire d'inscription.
La liste des données sera configurée rubrique par rubrique et se présentera comme suit :
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)
Tous les attributs n'ayant pas nécessairement été remplis par les utilisateurs, Orange ne garantit pas la disponibilité de tous les attributs.
Un utilisateur devra toujours donner son consentement pour la transmission de ses données personnelles par Orange (via la fonction de confidentialité).
Veuillez noter que si vous vous êtes inscrits à d'autres APIs de la suite Personal APIs, la réponse SAML contiendra automatiquement un jeton d'utilisateur à utiliser pour appeler ces (consulter la section comment récupérer un jeton d'utilisateur pour appeler d'autres Personal APIs pour de plus amples informations).
Le diagramme ci-dessous montre comment l'utilisateur est authentifié via la plateforme d'identification d'Orange.
Pour envoyer les clients Orange vers la plateforme d'identification d'Orange, vous devez procéder comme suit :
envoyer la requête d'authentification à Orange
retrieve the user's identifier (name identifier) contained in the authentication response
envoyer la requête d'authentification à Orange
Cette section se rapporte à la « requête 2 » du diagramme ci-dessus.
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 fichier ZIP à l'aide de DEFLATE, puis envoyée comme paramètre d'URL encodé en Base64.
Ci-dessous, un exemple de la requête d'authentification SAML :
|
HTTP redirection from user's browser to Orange:
[IDP_SingleSignOnURL]?SAMLRequest=PEF1dGhuUmVxdWVzdCB4bWxucz1cInVybjpvYXNpczpuYW1lczp0YzpTQU1
MOjIuMDpwcm90b2NvbFwiICBJRD1cIl9jYzgzNGMxODFmYzA0MDhjOTgzY2I1NWY4ZWZlYzI4OVwiIFZlcnNp
b249XCIyLjBcIiBJc3N1ZUluc3RhbnQ9XCIyMDA3LTEyLTIxVDIwOjI0OjQ3WlwiID48SXNzdWVyIHhtbG5zPV
widXJuOm9hc2lzOm5hbWVzOnRjOlNBTUw6Mi4wOmFzc2VydGlvblwiPmh0dHA6Ly9teXNwPC9Jc3N1ZXI
PE5hbWVJRFBvbGljeSBGb3JtYXQ9XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6bmFtZWlkL
WZvcm1hdDpwZXJzaXN0ZW50XCIgIEFsbG93Q3JlYXRlPVwidHJ1ZVwiLz48L0F1dGhuUmVxdWVzdD4%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>
|
Ci-dessous, un exemple du 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");
## <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]" ) );
?>
|
récupérer l'identifiant d'utilisateur (identifiant du nom) contenu dans la réponse d'authentification
Cette section se rapporte à la « requête 4 » du diagramme ci-dessus.
Pour récupérer l'identifiant de l'utilisateur (identifiant du nom) contenu dans la réponse SAML, il vous suffit simplement de :
vérifier la signature
vérifier l'élément <status> - cela devrait être une réussite - urn:oasis:names:tc:SAML:2.0:status:Success
vérifier l'élément <SubjectConfirmationData> - « Recipient » doit correspondre à l'URL recevant la réponse et la date « NotOnOrAfter » ne doit pas être passée
vérifier l'élément <Audience> - il DOIT correspondre à l'identifiant technique du fournisseur de service tiers
analyser la réponse SAML (document XML) pour trouver l'élément <NameID> - c'est le nom d'identifiant
Le nom d'identifiant se présente comme suit :
|
4b124ae2-0126-102b-8852-001a641049bb
|
Tant que l'utilisateur souhaite maintenir un lien entre son compte d'utilisateur sur votre site Web et son compte d'utilisateur Orange, Orange vous enverra le même nom d'identifiant chaque fois que cet utilisateur ouvrira une session sur votre site Web via Orange. Par conséquent, vous devriez conserver cet identifiant dans votre base de données de services.
Ci-dessous, un exemple de réponse d'authentification SAML :
|
Réponse 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>
|
Ci-dessous, un exemple de code PHP pour traiter la réponse :
|
<?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>
|
Mise en correspondance des noms d'attributs et des données de profil d'utilisateur :
| Données de profils d'utilisateur correspondantes |
noms d'attributs |
| 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)
