You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/simplesamlphp-authproc.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -160,16 +160,16 @@ Writing your own Auth Proc Filter
160
160
161
161
Look at the included *Auth Proc Filters* as examples. Copy the classes into your own module and start playing around.
162
162
163
-
Authentication processing filters are created by creating a class under `Auth/Process/` in a module. This class is expected to subclass `SimpleSAML_Auth_ProcessingFilter`. A filter must implement at least one function - the `process(&$request)`-function. This function can access the `$request`-array to add, delete and modify attributes, and can also do more advanced processing based on the SP/IdP metadata (which is also included in the `$request`-array). When this function returns, it is assumed that the filter has finished processing.
163
+
Authentication processing filters are created by creating a class under `Auth/Process/` in a module. This class is expected to subclass `\SimpleSAML\Auth\ProcessingFilter`. A filter must implement at least one function - the `process(&$request)`-function. This function can access the `$request`-array to add, delete and modify attributes, and can also do more advanced processing based on the SP/IdP metadata (which is also included in the `$request`-array). When this function returns, it is assumed that the filter has finished processing.
164
164
165
-
If a filter for some reason needs to redirect the user, for example to show a web page, it should save the current request. Upon completion it should retrieve the request, update it with the changes it is going to make, and call `SimpleSAML_Auth_ProcessingChain::resumeProcessing`. This function will continue processing the next configured filter.
165
+
If a filter for some reason needs to redirect the user, for example to show a web page, it should save the current request. Upon completion it should retrieve the request, update it with the changes it is going to make, and call `\SimpleSAML\Auth\ProcessingChain::resumeProcessing`. This function will continue processing the next configured filter.
166
166
167
167
Requirements for authentication processing filters:
168
168
169
-
- Must be derived from the `SimpleSAML_Auth_ProcessingFilter`-class.
169
+
- Must be derived from the `\SimpleSAML\Auth\ProcessingFilter`-class.
170
170
- If a constructor is implemented, it must first call the parent constructor, passing along all parameters, before accessing any of the parameters. In general, only the $config parameter should be accessed.
171
171
- The `process(&$request)`-function must be implemented. If this function completes, it is assumed that processing is completed, and that the $request array has been updated.
172
-
- If the `process`-function does not return, it must at a later time call `SimpleSAML_Auth_ProcessingChain::resumeProcessing` with the new request state. The request state must be an update of the array passed to the `process`-function.
172
+
- If the `process`-function does not return, it must at a later time call `\SimpleSAML\Auth\ProcessingChain::resumeProcessing` with the new request state. The request state must be an update of the array passed to the `process`-function.
173
173
- No pages may be shown to the user from the `process`-function. Instead, the request state should be saved, and the user should be redirected to a new page. This must be done to prevent unpredictable events if the user for example reloads the page.
174
174
- No state information should be stored in the filter object. It must instead be stored in the request state array. Any changes to variables in the filter object may be lost.
175
175
- The filter object must be serializable. It may be serialized between being constructed and the call to the `process`-function. This means that, for example, no database connections should be created in the constructor and later used in the `process`-function.
Copy file name to clipboardExpand all lines: docs/simplesamlphp-authsource.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@ Creating authentication sources
2
2
===============================
3
3
4
4
All authentication sources are located in the `lib/Auth/Source/` directory in a module, and the class name is `sspmod_<module>_Auth_Source_<name>`.
5
-
The authentication source must extend the `SimpleSAML_Auth_Source` class or one of its subclasses.
5
+
The authentication source must extend the `\SimpleSAML\Auth\Source` class or one of its subclasses.
6
6
7
7
The "entry point" of an authentication source is the `authenticate()`-function.
8
8
Once that function is called, the authentication module can do whatever it wishes to do.
@@ -13,18 +13,18 @@ There are only two requirements:
13
13
14
14
- Return control to SimpleSAMLphp after authenticating the user.
15
15
If the module is able to authenticate the user without doing any redirects, it should just update the state-array and return.
16
-
If the module does a redirect, it must call `SimpleSAML_Auth_Source::completeAuth()` with the updated state array.
16
+
If the module does a redirect, it must call `\SimpleSAML\Auth\Source::completeAuth()` with the updated state array.
17
17
18
18
Everything else is up to the module.
19
19
If the module needs to redirect the user, for example because it needs to show the user a page asking for credentials, it needs to save the state array.
20
-
For that we have the `SimpleSAML_Auth_State` class.
20
+
For that we have the `\SimpleSAML\Auth\State` class.
21
21
This is only a convenience class, and you are not required to use it (but its use is encouraged, since it handles some potential pitfalls).
22
22
23
23
24
24
Saving state
25
25
------------
26
26
27
-
The `SimpleSAML_Auth_State` class has two functions that you should use:
27
+
The `\SimpleSAML\Auth\State` class has two functions that you should use:
28
28
`saveState($state, $stage)`, and `loadState($id, $stage)`.
29
29
The `$stage` parameter must be an unique identifier for the current position in the authentication.
30
30
It is used to prevent a malicious user from taking a state you save in one location, and give it to a different location.
@@ -51,7 +51,7 @@ Generic rules & requirements
51
51
----------------------------
52
52
53
53
-
54
-
Must be derived from the `SimpleSAML_Auth_Source`-class.
54
+
Must be derived from the `\SimpleSAML\Auth\Source`-class.
55
55
56
56
**Rationale**:
57
57
- Deriving all authentication sources from a single base class allows us extend all authentication sources by extending the base class.
@@ -62,7 +62,7 @@ Generic rules & requirements
62
62
63
63
**Rationale**:
64
64
- PHP doesn't automatically call any parent constructor, so it needs to be done manually.
65
-
- The `$info`-array is used to provide information to the `SimpleSAML_Auth_Source` base class, and therefore needs to be included.
65
+
- The `$info`-array is used to provide information to the `\SimpleSAML\Auth\Source` base class, and therefore needs to be included.
66
66
- Including the `$config`-array makes it possible to add generic configuration options that are valid for all authentication sources.
67
67
68
68
-
@@ -74,7 +74,7 @@ Generic rules & requirements
74
74
This can be used if the authentication doesn't require user input, for example if the authentication can be done based on the IP-address of the user.
75
75
76
76
-
77
-
If the `authenticate`-function does not return, it must at a later time call `SimpleSAML_Auth_Source::completeAuth` with the new state array.
77
+
If the `authenticate`-function does not return, it must at a later time call `\SimpleSAML\Auth\Source::completeAuth` with the new state array.
78
78
The state array must be an update of the array passed to the `authenticate`-function.
Copy file name to clipboardExpand all lines: docs/simplesamlphp-errorhandling.md
+40-40Lines changed: 40 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ This document describes the way errors and exceptions are handled in authenticat
14
14
The basic goal is to be able to throw an exception during authentication, and then have that exception transported back to the SP in a way that the SP understands.
15
15
16
16
This means that internal SimpleSAMLphp exceptions must be mapped to transport specific error codes for the various transports that are supported by SimpleSAMLphp.
17
-
E.g.: When a `SimpleSAML_Error_NoPassive` error is thrown by an authentication processing filter in a SAML 2.0 IdP, we want to map that exception to the `urn:oasis:names:tc:SAML:2.0:status:NoPassive` status code.
17
+
E.g.: When a `\SimpleSAML\Error\NoPassive` error is thrown by an authentication processing filter in a SAML 2.0 IdP, we want to map that exception to the `urn:oasis:names:tc:SAML:2.0:status:NoPassive` status code.
18
18
That status code should then be returned to the SP.
19
19
20
20
@@ -26,42 +26,42 @@ The simplest case is if you want to throw it during the `authenticate()`-method
26
26
In those methods, you can just throw an exception:
27
27
28
28
public function process(&$state) {
29
-
if ($state['something'] === FALSE) {
30
-
throw new SimpleSAML_Error_Exception('Something is wrong...');
29
+
if ($state['something'] === false) {
30
+
throw new \SimpleSAML\Error\Exception('Something is wrong...');
31
31
}
32
32
}
33
33
34
34
Exceptions thrown at this stage will be caught and delivered to the appropriate error handler.
35
35
36
-
If you want to throw an exception outside of those methods, i.e. after you have done a redirect, you need to use the `SimpleSAML_Auth_State::throwException()` function:
36
+
If you want to throw an exception outside of those methods, i.e. after you have done a redirect, you need to use the `\SimpleSAML\Auth\State::throwException()` function:
new \SimpleSAML\Error\Exception('Something is wrong...'));
43
43
?>
44
44
45
-
The `SimpleSAML_Auth_State::throwException` function will then transfer your exception to the appropriate error handler.
45
+
The `\SimpleSAML\Auth\State::throwException` function will then transfer your exception to the appropriate error handler.
46
46
47
47
48
48
### Note
49
49
50
-
Note that we use the `SimpleSAML_Error_Exception` class in both cases.
50
+
Note that we use the `\SimpleSAML\Error\Exception` class in both cases.
51
51
This is because the delivery of the exception may require a redirect to a different web page.
52
52
In those cases, the exception needs to be serialized.
53
53
The normal `Exception` class in PHP isn't always serializable.
54
54
55
-
If you throw an exception that isn't a subclass of the `SimpleSAML_Error_Exception` class, your exception will be converted to an instance of `SimpleSAML_Error_UnserializableException`.
56
-
The `SimpleSAML_Auth_State::throwException` function does not accept any exceptions that does not subclass the `SimpleSAML_Error_Exception` class.
55
+
If you throw an exception that isn't a subclass of the `\SimpleSAML\Error\Exception` class, your exception will be converted to an instance of `\SimpleSAML\Error\UnserializableException`.
56
+
The `\SimpleSAML\Auth\State::throwException` function does not accept any exceptions that does not subclass the `\SimpleSAML\Error\Exception` class.
57
57
58
58
59
59
Returning specific SAML 2 errors
60
60
--------------------------------
61
61
62
62
By default, all thrown exceptions will be converted to a generic SAML 2 error.
63
63
In some cases, you may want to convert the exception to a specific SAML 2 status code.
64
-
For example, the `SimpleSAML_Error_NoPassive` exception should be converted to a SAML 2 status code with the following properties:
64
+
For example, the `\SimpleSAML\Error\NoPassive` exception should be converted to a SAML 2 status code with the following properties:
65
65
66
66
* The top-level status code should be `urn:oasis:names:tc:SAML:2.0:status:Responder`.
67
67
* The second-level status code should be `urn:oasis:names:tc:SAML:2.0:status:NoPassive`.
@@ -97,7 +97,7 @@ This is handled by the `toException()` method in `sspmod_saml_Error`.
97
97
The assertion consumer script of the SAML 2 authentication source (`modules/saml2/sp/acs.php`) uses this method.
98
98
The result is that generic exceptions are thrown from that authentication source.
99
99
100
-
For example, `NoPassive` errors will be converted back to instances of `SimpleSAML_Error_NoPassive`.
100
+
For example, `NoPassive` errors will be converted back to instances of `\SimpleSAML\Error\NoPassive`.
101
101
102
102
103
103
Other protocols
@@ -113,9 +113,9 @@ Technical details
113
113
This section attempts to describe the internals of the error handling framework.
114
114
115
115
116
-
### `SimpleSAML_Error_Exception`
116
+
### `\SimpleSAML\Error\Exception`
117
117
118
-
The `SimpleSAML_Error_Exception` class extends the normal PHP `Exception` class.
118
+
The `\SimpleSAML\Error\Exception` class extends the normal PHP `Exception` class.
119
119
It makes the exceptions serializable by overriding the `__sleep()` method.
120
120
The `__sleep()` method returns all variables in the class which should be serialized when saving the class.
121
121
@@ -136,7 +136,7 @@ This may be confusing since the new stack trace leads into the `unserialize()` f
136
136
It is therefore recommended to use the getBacktrace() method.
137
137
138
138
139
-
### `SimpleSAML_Auth_State`
139
+
### `\SimpleSAML\Auth\State`
140
140
141
141
There are two methods in this class that deals with exceptions:
142
142
@@ -147,44 +147,44 @@ There are two methods in this class that deals with exceptions:
147
147
#### `throwException`
148
148
149
149
This method delivers the exception to the code that initialized the exception handling in the authentication state.
150
-
That would be `SimpleSAML_Auth_Default` for authtentication sources, and `www/saml2/idp/SSOService.php` for processing filters.
150
+
That would be `\SimpleSAML\Auth\DefaultAuth` for authtentication sources, and `www/saml2/idp/SSOService.php` for processing filters.
151
151
To configure how and where the exception should be delivered, there are two fields in the state-array which can be set:
152
152
153
-
*`SimpleSAML_Auth_State::EXCEPTION_HANDLER_FUNC`, in which case the exception will be delivered by a function call to the function specified in that field.
154
-
*`SimpleSAML_Auth_State::EXCEPTION_HANDLER_URL`, in which case the exception will be delivered by a redirect to the URL specified in that field.
153
+
*`\SimpleSAML\Auth\State::EXCEPTION_HANDLER_FUNC`, in which case the exception will be delivered by a function call to the function specified in that field.
154
+
*`\SimpleSAML\Auth\State::EXCEPTION_HANDLER_URL`, in which case the exception will be delivered by a redirect to the URL specified in that field.
155
155
156
156
If the exception is delivered by a function call, the function will be called with two parameters: The exception and the state array.
157
157
158
-
If the exception is delivered by a redirect, SimpleSAML_Auth_State will save the exception in a field in the state array, pass a parameter with the id of the state array to the URL.
159
-
The `SimpleSAML_Auth_State::EXCEPTION_PARAM` constant contains the name of that parameter, while the `SimpleSAML_Auth_State::EXCEPTION_DATA` constant holds the name of the field where the exception is saved.
158
+
If the exception is delivered by a redirect, \SimpleSAML\Auth\State will save the exception in a field in the state array, pass a parameter with the id of the state array to the URL.
159
+
The `\SimpleSAML\Auth\State::EXCEPTION_PARAM` constant contains the name of that parameter, while the `\SimpleSAML\Auth\State::EXCEPTION_DATA` constant holds the name of the field where the exception is saved.
160
160
161
161
162
162
#### `loadException`
163
163
164
-
To retrieve the exception, the application should check for the state parameter in the request, and then retrieve the state array by calling `SimpleSAML_Auth_State::loadExceptionState()`.
165
-
The exception can be located in a field named `SimpleSAML_Auth_State::EXCEPTION_DATA`.
164
+
To retrieve the exception, the application should check for the state parameter in the request, and then retrieve the state array by calling `\SimpleSAML\Auth\State::loadExceptionState()`.
165
+
The exception can be located in a field named `\SimpleSAML\Auth\State::EXCEPTION_DATA`.
166
166
The following code illustrates this behaviour:
167
167
168
-
if (array_key_exists(SimpleSAML_Auth_State::EXCEPTION_PARAM, $_REQUEST)) {
An exception which isn't a subclass of `SimpleSAML_Error_Exception` will be converted to the `SimpleSAML_Error_UnserializedException` class.
224
+
An exception which isn't a subclass of `\SimpleSAML\Error\Exception` will be converted to the `\SimpleSAML\Error\UnserializedException` class.
225
225
This happens regardless of whether the exception is delivered directly or through the error handler.
226
226
This is done to be consistent in what the application receives - now it will always receive the same exception, regardless of whether it is delivered directly or through a redirect.
227
227
228
228
229
229
Custom error show function
230
230
--------------------------
231
231
232
-
Optional custom error show function, called from SimpleSAML_Error_Error::show, is defined with 'errors.show_function' in config.php.
232
+
Optional custom error show function, called from \SimpleSAML\Error\Error::show, is defined with 'errors.show_function' in config.php.
233
233
234
-
Example code for this function, which implements the same functionality as SimpleSAML_Error_Error::show, looks something like:
234
+
Example code for this function, which implements the same functionality as \SimpleSAML\Error\Error::show, looks something like:
235
235
236
236
public static function show(\SimpleSAML\Configuration $config, array $data) {
237
-
$t = new SimpleSAML_XHTML_Template($config, 'error.php', 'errors');
237
+
$t = new \SimpleSAML\XHTML\Template($config, 'error.php', 'errors');
0 commit comments