src/applications/auth/adapter/PhutilAuthAdapter.php

   1 <?php
   2
   3 /**
   4  * Abstract interface to an identity provider or authentication source, like
   5  * Twitter, Facebook, or Google.
   6  *
   7  * Generally, adapters are handed some set of credentials particular to the
   8  * provider they adapt, and they turn those credentials into standard
   9  * information about the user's identity. For example, the LDAP adapter is given
  10  * a username and password (and some other configuration information), uses them
  11  * to talk to the LDAP server, and produces a username, email, and so forth.
  12  *
  13  * Since the credentials a provider requires are specific to each provider, the
  14  * base adapter does not specify how an adapter should be constructed or
  15  * configured -- only what information it is expected to be able to provide once
  16  * properly configured.
  17  */
  18 abstract class PhutilAuthAdapter extends Phobject {
  19
  20   final public function getAccountIdentifiers() {
  21     $result = $this->newAccountIdentifiers();
  22     assert_instances_of($result, 'PhabricatorExternalAccountIdentifier');
  23     return $result;
  24   }
  25
  26   protected function newAccountIdentifiers() {
  27     $identifiers = array();
  28
  29     $raw_identifier = $this->getAccountID();
  30     if ($raw_identifier !== null) {
  31       $identifiers[] = $this->newAccountIdentifier($raw_identifier);
  32     }
  33
  34     return $identifiers;
  35   }
  36
  37   final protected function newAccountIdentifier($raw_identifier) {
  38     return id(new PhabricatorExternalAccountIdentifier())
  39       ->setIdentifierRaw($raw_identifier);
  40   }
  41
  42   /**
  43    * Get a unique identifier associated with the account.
  44    *
  45    * This identifier should be permanent, immutable, and uniquely identify
  46    * the account. If possible, it should be nonsensitive. For providers that
  47    * have a GUID or PHID value for accounts, these are the best values to use.
  48    *
  49    * You can implement @{method:newAccountIdentifiers} instead if a provider
  50    * is unable to emit identifiers with all of these properties.
  51    *
  52    * If the adapter was unable to authenticate an identity, it should return
  53    * `null`.
  54    *
  55    * @return string|null Unique account identifier, or `null` if authentication
  56    *                     failed.
  57    */
  58   public function getAccountID() {
  59     throw new PhutilMethodNotImplementedException();
  60   }
  61
  62
  63   /**
  64    * Get a string identifying this adapter, like "ldap". This string should be
  65    * unique to the adapter class.
  66    *
  67    * @return string Unique adapter identifier.
  68    */
  69   abstract public function getAdapterType();
  70
  71
  72   /**
  73    * Get a string identifying the domain this adapter is acting on. This allows
  74    * an adapter (like LDAP) to act against different identity domains without
  75    * conflating credentials. For providers like Facebook or Google, the adapters
  76    * just return the relevant domain name.
  77    *
  78    * @return string Domain the adapter is associated with.
  79    */
  80   abstract public function getAdapterDomain();
  81
  82
  83   /**
  84    * Generate a string uniquely identifying this adapter configuration. Within
  85    * the scope of a given key, all account IDs must uniquely identify exactly
  86    * one identity.
  87    *
  88    * @return string  Unique identifier for this adapter configuration.
  89    */
  90   public function getAdapterKey() {
  91     return $this->getAdapterType().':'.$this->getAdapterDomain();
  92   }
  93
  94
  95   /**
  96    * Optionally, return an email address associated with this account.
  97    *
  98    * @return string|null  An email address associated with the account, or
  99    *                      `null` if data is not available.
 100    */
 101   public function getAccountEmail() {
 102     return null;
 103   }
 104
 105
 106   /**
 107    * Optionally, return a human readable username associated with this account.
 108    *
 109    * @return string|null  Account username, or `null` if data isn't available.
 110    */
 111   public function getAccountName() {
 112     return null;
 113   }
 114
 115
 116   /**
 117    * Optionally, return a URI corresponding to a human-viewable profile for
 118    * this account.
 119    *
 120    * @return string|null  A profile URI associated with this account, or
 121    *                      `null` if the data isn't available.
 122    */
 123   public function getAccountURI() {
 124     return null;
 125   }
 126
 127
 128   /**
 129    * Optionally, return a profile image URI associated with this account.
 130    *
 131    * @return string|null  URI for an account profile image, or `null` if one is
 132    *                      not available.
 133    */
 134   public function getAccountImageURI() {
 135     return null;
 136   }
 137
 138
 139   /**
 140    * Optionally, return a real name associated with this account.
 141    *
 142    * @return string|null  A human real name, or `null` if this data is not
 143    *                      available.
 144    */
 145   public function getAccountRealName() {
 146     return null;
 147   }
 148
 149 }