Skip to content

Commit 6a7a8d6

Browse files
dereuromarkmarkstory
dereuromark
and
markstory
authored
Deprecate identifier collection approach. (#712)
* Deprecate identifier collection approach. --------- Co-authored-by: Mark Story <mark@mark-story.com>
1 parent 6edbfe6 commit 6a7a8d6

12 files changed

Lines changed: 326 additions & 126 deletions

‎docs/en/authenticators.rst‎

Lines changed: 32 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,8 @@ Add the following to your ``Application`` class::
139139
{
140140
$service = new AuthenticationService();
141141
// ...
142-
$service->loadIdentifier('Authentication.JwtSubject');
143142
$service->loadAuthenticator('Authentication.Jwt', [
143+
'identifier' => 'Authentication.JwtSubject',
144144
'secretKey' => file_get_contents(CONFIG . '/jwt.key'),
145145
'algorithm' => 'RS256',
146146
'returnPayload' => false
@@ -180,7 +180,6 @@ Using a JWKS fetched from an external JWKS endpoint is supported as well::
180180
{
181181
$service = new AuthenticationService();
182182
// ...
183-
$service->loadIdentifier('Authentication.JwtSubject');
184183

185184
$jwksUrl = 'https://appleid.apple.com/auth/keys';
186185

@@ -193,6 +192,7 @@ Using a JWKS fetched from an external JWKS endpoint is supported as well::
193192
});
194193

195194
$service->loadAuthenticator('Authentication.Jwt', [
195+
'identifier' => 'Authentication.JwtSubject',
196196
'jwks' => $jsonWebKeySet,
197197
'returnPayload' => false
198198
]);
@@ -335,14 +335,18 @@ authentication cookie is **also destroyed**. An example configuration would be::
335335
// Put form authentication first so that users can re-login via
336336
// the login form if necessary.
337337
$service->loadAuthenticator('Authentication.Form', [
338+
'identifier' => 'Authentication.Password',
338339
'fields' => $fields,
339340
'loginUrl' => '/users/login',
340341
]);
341342
// Then use sessions if they are active.
342-
$service->loadAuthenticator('Authentication.Session');
343+
$service->loadAuthenticator('Authentication.Session', [
344+
'identifier' => 'Authentication.Password',
345+
]);
343346

344347
// If the user is on the login page, check for a cookie as well.
345348
$service->loadAuthenticator('Authentication.Cookie', [
349+
'identifier' => 'Authentication.Password',
346350
'fields' => $fields,
347351
'loginUrl' => '/users/login',
348352
]);
@@ -366,12 +370,15 @@ and similar SAML 1.1 implementations. An example configuration is::
366370

367371
// Configure a token identifier that maps `USER_ID` to the
368372
// username column
369-
$service->loadIdentifier('Authentication.Token', [
370-
'tokenField' => 'username',
371-
'dataField' => 'USER_NAME',
372-
]);
373+
$identifier = [
374+
'Authentication.Token' => [
375+
'tokenField' => 'username',
376+
'dataField' => 'USER_NAME',
377+
],
378+
];
373379

374380
$service->loadAuthenticator('Authentication.Environment', [
381+
'identifier' => $identifier,
375382
'loginUrl' => '/sso',
376383
'fields' => [
377384
// Choose which environment variables exposed by your
@@ -477,19 +484,26 @@ authenticators must send specific challenge headers in the response::
477484
// Instantiate the service
478485
$service = new AuthenticationService();
479486

480-
// Load identifiers
481-
$service->loadIdentifier('Authentication.Password', [
482-
'fields' => [
483-
'username' => 'email',
484-
'password' => 'password'
485-
]
486-
]);
487-
$service->loadIdentifier('Authentication.Token');
487+
// Define identifiers
488+
$passwordIdentifier = [
489+
'Authentication.Password' => [
490+
'fields' => [
491+
'username' => 'email',
492+
'password' => 'password'
493+
]
494+
],
495+
];
488496

489497
// Load the authenticators leaving Basic as the last one.
490-
$service->loadAuthenticator('Authentication.Session');
491-
$service->loadAuthenticator('Authentication.Form');
492-
$service->loadAuthenticator('Authentication.HttpBasic');
498+
$service->loadAuthenticator('Authentication.Session', [
499+
'identifier' => $passwordIdentifier,
500+
]);
501+
$service->loadAuthenticator('Authentication.Form', [
502+
'identifier' => $passwordIdentifier,
503+
]);
504+
$service->loadAuthenticator('Authentication.HttpBasic', [
505+
'identifier' => 'Authentication.Token',
506+
]);
493507

494508
If you want to combine ``HttpBasic`` or ``HttpDigest`` with other
495509
authenticators, be aware that these authenticators will abort the request and

‎docs/en/identifiers.rst‎

Lines changed: 69 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,28 @@ that was extracted from the request by the authenticators. Identifiers
66
can take options in the ``loadIdentifier`` method. A holistic example of
77
using the Password Identifier looks like::
88

9-
$service->loadIdentifier('Authentication.Password', [
10-
'fields' => [
11-
'username' => 'email',
12-
'password' => 'passwd',
13-
],
14-
'resolver' => [
15-
'className' => 'Authentication.Orm',
16-
'userModel' => 'Users',
17-
'finder' => 'active', // default: 'all'
18-
],
19-
'passwordHasher' => [
20-
'className' => 'Authentication.Fallback',
21-
'hashers' => [
22-
'Authentication.Default',
23-
[
24-
'className' => 'Authentication.Legacy',
25-
'hashType' => 'md5',
26-
],
9+
$identifier = [
10+
'Authentication.Password' => [
11+
'fields' => [
12+
'username' => 'email',
13+
'password' => 'passwd',
2714
],
28-
],
29-
]);
15+
'resolver' => [
16+
'className' => 'Authentication.Orm',
17+
'userModel' => 'Users',
18+
'finder' => 'active', // default: 'all'
19+
],
20+
'passwordHasher' => [
21+
'className' => 'Authentication.Fallback',
22+
'hashers' => [
23+
'Authentication.Default' => [
24+
'className' => 'Authentication.Legacy',
25+
'hashType' => 'md5',
26+
],
27+
],
28+
],
29+
],
30+
];
3031

3132
Password
3233
========
@@ -60,7 +61,7 @@ Configuration options:
6061
- **resolver**: The identity resolver. Default is
6162
``Authentication.Orm`` which uses CakePHP ORM.
6263
- **hashAlgorithm**: The algorithm used to hash the incoming token
63-
with before compairing it to the ``tokenField``. Recommended value is
64+
with before comparing it to the ``tokenField``. Recommended value is
6465
``sha256``. Default is ``null``.
6566

6667
JWT Subject
@@ -119,36 +120,39 @@ or an ``Authentication\Authenticator\Result`` if you want to forward error
119120
messages::
120121

121122
// A simple callback identifier
122-
$authenticationService->loadIdentifier('Authentication.Callback', [
123-
'callback' => function($data) {
124-
// do identifier logic
123+
$identifier = [
124+
'Authentication.Callback' => [
125+
'callback' => function($data) {
126+
// do identifier logic
125127

126-
// Return an array of the identified user or null for failure.
127-
if ($result) {
128-
return $result;
129-
}
128+
// Return an array of the identified user or null for failure.
129+
if ($result) {
130+
return $result;
131+
}
130132

131-
return null;
132-
},
133-
]);
133+
return null;
134+
},
135+
]
136+
];
134137

135138
// Using a result object to return error messages.
136-
$authenticationService->loadIdentifier('Authentication.Callback', [
137-
'callback' => function($data) {
138-
// do identifier logic
139-
140-
if ($result) {
141-
return new Result($result, Result::SUCCESS);
142-
}
143-
144-
return new Result(
145-
null,
146-
Result::FAILURE_OTHER,
147-
['message' => 'Removed user.']
148-
);
149-
},
150-
]);
151-
139+
$identifier = [
140+
'Authentication.Callback' => [
141+
'callback' => function($data) {
142+
// do identifier logic
143+
144+
if ($result) {
145+
return new Result($result, Result::SUCCESS);
146+
}
147+
148+
return new Result(
149+
null,
150+
Result::FAILURE_OTHER,
151+
['message' => 'Removed user.']
152+
);
153+
},
154+
];
155+
];
152156

153157
Identity resolvers
154158
==================
@@ -183,17 +187,27 @@ reside under ``App\Identifier\Resolver`` namespace.
183187

184188
Resolver can be configured using ``resolver`` config option::
185189

186-
$service->loadIdentifier('Authentication.Password', [
187-
'resolver' => [
188-
// can be a full class name: \Some\Other\Custom\Resolver::class
189-
'className' => 'MyResolver',
190-
// Pass additional options to the resolver constructor.
191-
'option' => 'value',
192-
],
193-
]);
190+
$identifier = [
191+
'Authentication.Password' => [
192+
'resolver' => [
193+
// can be a full class name: \Some\Other\Custom\Resolver::class
194+
'className' => 'MyResolver',
195+
// Pass additional options to the resolver constructor.
196+
'option' => 'value',
197+
],
198+
];
199+
];
194200

195201
Or injected using a setter::
196202

197203
$resolver = new \App\Identifier\Resolver\CustomResolver();
198204
$identifier = $service->loadIdentifier('Authentication.Password');
199205
$identifier->setResolver($resolver);
206+
207+
As of 3.3.0, you should pass the constructed resolver into the identifier::
208+
209+
$resolver = new \App\Identifier\Resolver\CustomResolver();
210+
$identifier = [
211+
'Authentication.Password' => [
212+
'resolver' => $resolver;
213+
];

‎docs/en/index.rst‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -94,13 +94,23 @@ define the ``AuthenticationService`` it wants to use. Add the following method t
9494
'queryParam' => 'redirect',
9595
]);
9696

97+
// Define identifiers
9798
$fields = [
9899
AbstractIdentifier::CREDENTIAL_USERNAME => 'email',
99100
AbstractIdentifier::CREDENTIAL_PASSWORD => 'password'
100101
];
102+
$passwordIdentifier = [
103+
'Authentication.Password' => [
104+
'fields' => $fields,
105+
],
106+
];
107+
101108
// Load the authenticators. Session should be first.
102-
$service->loadAuthenticator('Authentication.Session');
109+
$service->loadAuthenticator('Authentication.Session', [
110+
'identifier' => $passwordIdentifier,
111+
]);
103112
$service->loadAuthenticator('Authentication.Form', [
113+
'identifier' => $passwordIdentifier,
104114
'fields' => $fields,
105115
'loginUrl' => Router::url([
106116
'prefix' => false,
@@ -110,9 +120,6 @@ define the ``AuthenticationService`` it wants to use. Add the following method t
110120
]),
111121
]);
112122

113-
// Load identifiers
114-
$service->loadIdentifier('Authentication.Password', compact('fields'));
115-
116123
return $service;
117124
}
118125

‎docs/en/middleware.rst‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,18 +42,21 @@ inspecting the request object you can configure authentication appropriately::
4242
$service = new AuthenticationService();
4343
if (strpos($path, '/api') === 0) {
4444
// Accept API tokens only
45-
$service->loadAuthenticator('Authentication.Token');
46-
$service->loadIdentifier('Authentication.Token');
45+
$service->loadAuthenticator('Authentication.Token', [
46+
'identifier' => 'Authentication.Token',
47+
]);
4748

4849
return $service;
4950
}
5051

5152
// Web authentication
5253
// Support sessions and form login.
53-
$service->loadAuthenticator('Authentication.Session');
54-
$service->loadAuthenticator('Authentication.Form');
55-
56-
$service->loadIdentifier('Authentication.Password');
54+
$service->loadAuthenticator('Authentication.Session', [
55+
'identifier' => 'Authentication.Password',
56+
]);
57+
$service->loadAuthenticator('Authentication.Form', [
58+
'identifier' => 'Authentication.Password',
59+
]);
5760

5861
return $service;
5962
}

‎docs/en/migration-from-the-authcomponent.rst‎

Lines changed: 33 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -134,35 +134,43 @@ You’ll now have to configure it this way::
134134
// Instantiate the service
135135
$service = new AuthenticationService();
136136

137-
// Load identifiers
138-
$service->loadIdentifier('Authentication.Password', [
139-
'fields' => [
140-
'username' => 'email',
141-
'password' => 'password',
142-
]
143-
]);
144-
145-
// Load the authenticators
146-
$service->loadAuthenticator('Authentication.Session');
147-
$service->loadAuthenticator('Authentication.Form');
137+
// Define identifier
138+
$passwordIdentifier = [
139+
'Authentication.Password' => [
140+
'fields' => [
141+
'username' => 'email',
142+
'password' => 'password'
143+
]
144+
],
145+
];
146+
147+
// Load the authenticators
148+
$service->loadAuthenticator('Authentication.Session', [
149+
'identifier' => $passwordIdentifier,
150+
]);
151+
$service->loadAuthenticator('Authentication.Form', [
152+
'identifier' => $passwordIdentifier,
153+
]);
148154

149155
If you have customized the ``userModel`` you can use the following
150156
configuration::
151157

152-
// Instantiate the service
153-
$service = new AuthenticationService();
154-
155-
// Load identifiers
156-
$service->loadIdentifier('Authentication.Password', [
157-
'resolver' => [
158-
'className' => 'Authentication.Orm',
159-
'userModel' => 'Employees',
160-
],
161-
'fields' => [
162-
'username' => 'email',
163-
'password' => 'password',
164-
]
165-
]);
158+
// Instantiate the service
159+
$service = new AuthenticationService();
160+
161+
// Define identifier
162+
$passwordIdentifier = [
163+
'Authentication.Password' => [
164+
'resolver' => [
165+
'className' => 'Authentication.Orm',
166+
'userModel' => 'Employees',
167+
],
168+
'fields' => [
169+
'username' => 'email',
170+
'password' => 'password'
171+
]
172+
],
173+
];
166174

167175
While there is a bit more code than before, you have more flexibility in
168176
how your authentication is handled.

0 commit comments

Comments
 (0)