Finding a user ID via web service

There are two methods allowing an external service to obtain a user id (uid) in the EthosCE system. A service may query by e-mail, or external user ID. Querying by e-mail may be used by any client, as a unique e-mail is required when creating a local EthosCE user. External ID is available only to clients with Single Sign-On (SSO), who may use a different unique key, than an e-mail address.

Query by E-mail

<?php
// #1 Verify if user exists by sending a GET request to the system, searching by user 'mail' attribute
$curl = curl_init("http://your-domain.com/user.json?mail=external_user@dlc-solutions.com");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
 
$json = curl_exec($curl);
$response = json_decode($json);
 
// A list of users matching criteria will be returned. If this list is empty, a user does not exist in EthosCE with the given e-mail address.
$list = $response->list;

Successful Return

The response below describes information on a user with the e-mail address external_user@dlcdev.com, the most notable item being the uid 200.

{ 
  "self":"http://your-domain.com/user?mail=external_user%40dlcdev.com",
  "first":"http://your-domain.com/user?mail=external_user%40dlcdev.com\u0026page=0",
  "last":"http://your-domain.com/user?mail=external_user%40dlcdev.com\u0026page=0",
  "list":[ 
    { 

      "uid":"200",
      "name":"external_user",
      "mail":"external_user@dlcdev.com",
      "url":"http://your-domain.com/users/external_user",
      "edit_url":"http://your-domain.com/user/200/edit",
      "last_access":"1469471140",
      "last_login":"1469469525",
      "created":"1459800968",
      "roles":[ 
        2
      ],
      "status":"1",
      "profile_profile":{ 
        "uri":"http://your-domain.com/profile2/46",
        "id":"46",
        "resource":"profile2"
      },
      "uuid":"ba5bc8af-25d7-48de-bb54-87ae70ac33b5"
    }
  ]
}

Note

uid is the unique Drupal identifier, which is different from the uuid. Uuid is the universal unique identifier, which is an internal identifier for the database system.

Query by client External ID

When a user is created via an SSO call, an authentication map entry is created, keying a uid to a client external ID. The external ID is a pre-determined key, being sent in the SSO call. It's format will vary per client install.

<?php
// #1 Verify if user exists by sending a GET request to the system, searching by user 'authname' attribute
$curl = curl_init("http://your-domain.com/authmap.json?authname=external_user_500");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "restws_webservice:webservice_password"); //Your credentials goes here
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
 
$json = curl_exec($curl);
$response = json_decode($json);
 
// A list of users matching criteria will be returned. If this list is empty, the user does not exist in EthosCE with the given e-mail address.
$list = $response->list;

Successful Return

A successful return will provide an array in the list attribute, containing one item, with an array of user information.

Return Attributes

aid: The authentication ID key tracked by the database.

uid: The user's Drupal ID.

authname: The user's unique identifier from the external system.

module: The module responsible for authenticating the user. This is usually the name of the custom SSO implementation. For SAML implementations the module name is "simplesamlphp_auth."