Skip to content

Commit b1f1339

Browse files
cicnavicicnavi
committed
Set initial docs structure
1 parent e25443f commit b1f1339

File tree

7 files changed

+882
-8
lines changed

7 files changed

+882
-8
lines changed

‎docs/configuration.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# Configuration
2+
3+
This guide summarizes key configuration topics for the OIDC module.
4+
It complements the inline comments in `config/module_oidc.php`.
5+
6+
- Caching protocol artifacts
7+
- Relying Party (RP) administration UI
8+
- Cron integration
9+
- Endpoint locations and well-known URLs
10+
- Key rollover
11+
- Apache Authorization header note
12+
- Private scopes
13+
- Attribute translation
14+
- Auth Proc filters (OIDC)
15+
- Client registration permissions
16+
17+
## Caching protocol artifacts
18+
19+
The configured database is the primary storage for protocol artifacts:
20+
access tokens, authorization codes, refresh tokens, clients, and user
21+
records. In production, you should also configure a cache in front of the
22+
DB to improve performance during traffic spikes.
23+
24+
Caching uses Symfony Cache, so any compatible adapter can be used. See the
25+
`module_oidc.php` configuration file for adapter selection and parameters.
26+
27+
## Relying Party (RP) administration
28+
29+
The module provides a UI to manage clients (create, read, update, delete).
30+
After you create the database schema, go to the SimpleSAMLphp admin area:
31+
32+
- OIDC > Client Registry
33+
34+
Notes:
35+
- Clients can be public or confidential.
36+
- Public clients using Authorization Code flow must send PKCE parameters.
37+
- Client ID and secret are generated; use the "show" button to reveal.
38+
39+
## Cron integration
40+
41+
Enable and configure the SimpleSAMLphp cron module to purge expired tokens:
42+
43+
- https://simplesamlphp.org/docs/stable/cron/cron.html
44+
45+
## Endpoint locations and well-known URLs
46+
47+
After deployment, visit the SimpleSAMLphp admin area:
48+
49+
- OIDC > Protocol / Federation Settings
50+
51+
There you can see discovery URLs. Typical discovery endpoints are:
52+
53+
- OpenID Connect Discovery:
54+
https://yourserver/simplesaml/module.php/oidc/.well-known/openid-configuration
55+
- OpenID Federation configuration:
56+
https://yourserver/simplesaml/module.php/oidc/.well-known/openid-federation
57+
58+
You may publish these as ".well-known" URLs at the web root using your
59+
web server. For example, for `openid-configuration`:
60+
61+
nginx:
62+
63+
```nginx
64+
location = /.well-known/openid-configuration {
65+
rewrite ^(.*)$ /simplesaml/module.php/oidc/.well-known/openid-configuration break;
66+
proxy_pass https://localhost;
67+
}
68+
```
69+
70+
Apache:
71+
72+
```apache
73+
RewriteEngine On
74+
RewriteRule ^/.well-known/openid-configuration(.*) \
75+
/simplesaml/module.php/oidc/.well-known/openid-configuration$1 [PT]
76+
```
77+
78+
## Key rollover
79+
80+
You can configure an additional key pair to publish via JWKS endpoints or
81+
properties. This lets RPs pre-fetch the new public key before you switch
82+
signing to the new private key. Once RPs have cached the new JWKS, you can
83+
perform the key switch.
84+
85+
## Apache Authorization header note
86+
87+
Apache may strip the `Authorization` header (Bearer) from requests, a known
88+
issue: https://github.com/symfony/symfony/issues/19693
89+
90+
Although the module includes a fallback, it has performance implications.
91+
Configure Apache to preserve the header using one of these snippets:
92+
93+
```apache
94+
RewriteEngine On
95+
RewriteCond %{HTTP:Authorization} .+
96+
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
97+
```
98+
99+
or
100+
101+
```apache
102+
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
103+
```
104+
105+
If not set, you will see warnings about this in the logs.
106+
107+
## Private scopes
108+
109+
The module supports the standard scopes: `openid`, `email`, `address`,
110+
`phone`, and `profile`. You can add private scopes in `module_oidc.php`:
111+
112+
```php
113+
<?php
114+
115+
$config = [
116+
\SimpleSAML\Module\oidc\ModuleConfig::OPTION_AUTH_CUSTOM_SCOPES => [
117+
'private' => [
118+
'description' => 'private scope',
119+
'claim_name_prefix' => '',
120+
'are_multiple_claim_values_allowed' => false,
121+
'attributes' => ['national_document_id'],
122+
],
123+
],
124+
];
125+
```
126+
127+
## Attribute translation
128+
129+
Default SAML-to-OIDC claim mapping follows the REFEDS guidance:
130+
https://wiki.refeds.org/display/GROUPS/Mapping+SAML+attributes+to+OIDC+Claims
131+
132+
You can change or extend this mapping in `module_oidc.php`. Example:
133+
134+
```php
135+
<?php
136+
137+
$config = [
138+
\SimpleSAML\Module\oidc\ModuleConfig::OPTION_AUTH_SAML_TO_OIDC_TRANSLATE_TABLE => [
139+
// Overwrite default mapping
140+
'sub' => [
141+
'uid',
142+
'eduPersonPrincipalName',
143+
'eduPersonTargetedID',
144+
'eduPersonUniqueId',
145+
],
146+
// Remove default mapping by setting an empty array
147+
'family_name' => [],
148+
149+
// New claim created from SAML attribute
150+
'national_document_id' => [
151+
'schacPersonalUniqueId',
152+
],
153+
],
154+
];
155+
```
156+
157+
## Auth Proc filters (OIDC)
158+
159+
Standard SAML Auth Proc Filters do not run during OIDC authN because not
160+
all SAML entities are present (like a Service Provider). Instead, use the
161+
`authproc.oidc` configuration option to define filters specific to OIDC.
162+
163+
The OIDC authN state does not include all keys present in SAML authN.
164+
Available SAML-like keys include:
165+
166+
- ['Attributes']
167+
- ['Authority']
168+
- ['AuthnInstant']
169+
- ['Expire']
170+
171+
Source and Destination entity IDs correspond to OP issuer and Client ID:
172+
173+
- ['Source']['entityid'] → OP issuer ID
174+
- ['Destination']['entityid'] → RP (client) ID
175+
176+
Additional OIDC data in the state:
177+
178+
- ['Oidc']['OpenIdProviderMetadata']
179+
- ['Oidc']['RelyingPartyMetadata']
180+
- ['Oidc']['AuthorizationRequestParameters']
181+
182+
Example filter configuration:
183+
184+
```php
185+
<?php
186+
187+
$config = [
188+
\SimpleSAML\Module\oidc\ModuleConfig::OPTION_AUTH_PROCESSING_FILTERS => [
189+
50 => [
190+
'class' => 'core:AttributeAdd',
191+
'groups' => ['users', 'members'],
192+
],
193+
],
194+
];
195+
```
196+
197+
## Client registration permissions
198+
199+
You can allow users to register their own clients. Control this via the
200+
`permissions` setting in `module_oidc.php`.
201+
202+
Permissions expose functionality to specific users. In the following
203+
example, a user's `eduPersonEntitlement` is examined. To perform an action
204+
requiring the `client` permission (register/edit/delete a client) the user
205+
needs one of the listed entitlements.
206+
207+
```php
208+
<?php
209+
210+
$config = [
211+
\SimpleSAML\Module\oidc\ModuleConfig::OPTION_ADMIN_UI_PERMISSIONS => [
212+
'attribute' => 'eduPersonEntitlement',
213+
'client' => ['urn:example:oidc:manage:client'],
214+
],
215+
];
216+
```
217+
218+
Users can visit the following link for administration:
219+
220+
- https://example.com/simplesaml/module.php/oidc/clients/

‎docs/conformance.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# OpenID Conformance
2+
3+
This guide summarizes how to run the OpenID Foundation conformance tests
4+
against this module, both locally and using the hosted service.
5+
6+
- Run conformance tests locally
7+
- Run hosted tests
8+
9+
## Run conformance tests locally
10+
11+
This approach is best when you want to test changes without deploying.
12+
13+
### Run conformance images
14+
15+
Clone, build, and run the conformance test suite:
16+
17+
```bash
18+
git clone https://gitlab.com/openid/conformance-suite.git
19+
cd conformance-suite
20+
git checkout release-v5.1.35
21+
MAVEN_CACHE=./m2 docker-compose -f builder-compose.yml run builder
22+
docker-compose up
23+
```
24+
25+
This starts the Java conformance app and a MongoDB server. Then:
26+
27+
- Visit https://localhost:8443/
28+
- Create a new plan:
29+
"OpenID Connect Core: Basic Certification Profile Authorization server test"
30+
- Click the JSON tab and paste
31+
`conformance-tests/conformance-basic-local.json` from this repo.
32+
33+
Next, run your SSP OIDC image.
34+
35+
### Run SSP
36+
37+
Run SSP with OIDC on the same Docker network as the conformance tests so
38+
containers can communicate. See the "Docker Compose" section in the
39+
README for details.
40+
41+
### Run conformance tests (interactive)
42+
43+
The tests are interactive and will ask you to authenticate. Some tests
44+
require clearing cookies to confirm a scenario; others require existing
45+
session cookies. You may be redirected to
46+
`https://localhost.emobix.co.uk:8443/` (the Java app). Accept SSL
47+
warnings as needed.
48+
49+
### Run automated tests
50+
51+
Once manual tests pass, you can automate the browser portion:
52+
https://gitlab.com/openid/conformance-suite/-/wikis/Design/BrowserControl
53+
54+
From the `simplesamlphp-module-oidc` directory:
55+
56+
```bash
57+
# Adjust to your conformance-suite installation path
58+
OIDC_MODULE_FOLDER=.
59+
60+
# Basic profile
61+
conformance-suite/scripts/run-test-plan.py \
62+
--expected-failures-file ${OIDC_MODULE_FOLDER}/conformance-tests/basic-warnings.json \
63+
--expected-skips-file ${OIDC_MODULE_FOLDER}/conformance-tests/basic-skips.json \
64+
"oidcc-basic-certification-test-plan[server_metadata=discovery][client_registration=static_client]" \
65+
${OIDC_MODULE_FOLDER}/conformance-tests/conformance-basic-ci.json
66+
67+
# Implicit profile
68+
conformance-suite/scripts/run-test-plan.py \
69+
--expected-failures-file ${OIDC_MODULE_FOLDER}/conformance-tests/implicit-warnings.json \
70+
--expected-skips-file ${OIDC_MODULE_FOLDER}/conformance-tests/implicit-skips.json \
71+
"oidcc-implicit-certification-test-plan[server_metadata=discovery][client_registration=static_client]" \
72+
${OIDC_MODULE_FOLDER}/conformance-tests/conformance-implicit-ci.json
73+
74+
# RP initiated back-channel logout
75+
conformance-suite/scripts/run-test-plan.py \
76+
"oidcc-backchannel-rp-initiated-logout-certification-test-plan[response_type=code][client_registration=static_client]" \
77+
${OIDC_MODULE_FOLDER}/conformance-tests/conformance-back-channel-logout-ci.json
78+
79+
# RP initiated logout
80+
conformance-suite/scripts/run-test-plan.py \
81+
"oidcc-rp-initiated-logout-certification-test-plan[response_type=code][client_registration=static_client]" \
82+
${OIDC_MODULE_FOLDER}/conformance-tests/conformance-rp-initiated-logout-ci.json
83+
```
84+
85+
Prerequisites: run the docker deploy image for conformance tests (see
86+
README) and the conformance test image first.
87+
88+
## Run hosted tests
89+
90+
The OpenID Foundation hosts the conformance testing software. Your OIDC
91+
OP must be publicly accessible on the internet.
92+
93+
### Deploy SSP OIDC image
94+
95+
Use the docker image described in the README. It contains a SQLite DB
96+
pre-populated with data for the tests. Build and run the image.
97+
98+
### Register and create conformance tests
99+
100+
Visit https://openid.net/certification/instructions/
101+
102+
Use the `json` configs under `conformance-tests` to configure your cloud
103+
instances. Update `discoveryUrl` to the deployed location. Adjust `alias`
104+
if it conflicts with existing test suites (it is used in redirect URIs).

0 commit comments

Comments
 (0)