recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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 */
18abstract class PhutilAuthAdapter extends Phobject {
19
20 final public function getAccountIdentifiers() {
21 $result = $this->newAccountIdentifiers();
22 assert_instances_of($result, PhabricatorExternalAccountIdentifier::class);
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}