Skip to content

Commit 5956d7b

Browse files
DilshanSenarathDilshanSenarath
authored
Merge pull request #5971 from DilshanSenarath/saml-idp-doc
Automatic refresh for SAML IDP Certificates from Metadata URL
2 parents 6444c41 + bf471be commit 5956d7b

3 files changed

Lines changed: 162 additions & 7 deletions

File tree

‎en/asgardeo/docs/apis/restapis/idp.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2353,6 +2353,10 @@ components:
23532353
jwksUri:
23542354
type: string
23552355
example: "https://api.asgardeo.io/t/{org-name}/oauth2/jwks"
2356+
samlMetadataUri:
2357+
type: string
2358+
description: The SAML metadata endpoint URL of the external identity provider. When configured, Asgardeo fetches and caches the signing certificate from this URL to validate SAML response signatures and IdP-initiated logout request signatures.
2359+
example: "https://idp.example.com/saml/metadata"
23562360
IdentityProviderPOSTRequest:
23572361
type: object
23582362
required:

‎en/identity-server/next/docs/apis/restapis/idp.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2995,6 +2995,10 @@ components:
29952995
jwksUri:
29962996
type: string
29972997
example: "https://localhost:9444/oauth2/jwks"
2998+
samlMetadataUri:
2999+
type: string
3000+
description: The SAML metadata endpoint URL of the external identity provider. When configured, WSO2 Identity Server fetches and caches the signing certificate from this URL to validate SAML response signatures and IdP-initiated logout request signatures.
3001+
example: "https://idp.example.com/saml/metadata"
29983002
IdentityProviderPOSTRequest:
29993003
type: object
30003004
required:

‎en/includes/guides/authentication/standard-based-login/add-saml-idp-login.md‎

Lines changed: 154 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
# Add login with a SAML identity provider
22

3-
You can add standard SAML login to your applications using an external OIDC Identity Provider (IdP) and enable users to log in with their external identities.
3+
You can add standard SAML login to your applications using an external SAML Identity Provider (IdP) and enable users to log in with their external identities.
44

5-
Follow this guide to register an OIDC IdP in {{ product_name }} and add it to the login flow of your application.
5+
Follow this guide to register a SAML IdP in {{ product_name }} and add it to the login flow of your application.
66

77
![Configure SAML Enterprise IDP login in {{ product_name }}]({{base_path}}/assets/img/guides/idp/saml-enterprise-idp/configure-login.png){: width=600"}
88

9-
Follow this guide to register a SAML IdP in {{ product_name }} and add it to the login flow of your application.
10-
119
## Register {{ product_name }} in the IdP
1210
You need to register {{ product_name }} as a SAML application in the external identity provider. Follow the identity provider's documentation to know how to register a SAML application.
1311

@@ -77,8 +75,39 @@ If you selected **Manual Configuration** in the previous step, follow the steps
7775
</tr>
7876
</table>
7977

80-
3. (Optional) Upload the public certificate of the identity provider.
81-
4. Click **Finish** to complete the registration.
78+
{% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0") %}
79+
80+
2. (Optional) Provide the mode of certificate configuration.
81+
82+
!!! note
83+
You can either configure a SAML metadata endpoint URL or upload a PEM certificate. {{ product_name }} uses the certificate to validate SAML response signatures and federated IdP-initiated logout request signatures.
84+
85+
- **SAML metadata endpoint**: Enter the metadata endpoint URL of the external identity provider. {{ product_name }} fetches and caches the signing certificate from this URL. Learn more about [certificate validation with the SAML metadata endpoint](#certificate-validation-with-the-saml-metadata-endpoint).
86+
- **Use PEM certificate**: Upload or paste the public certificate of the external identity provider. The certificate should be in PEM format.
87+
88+
??? note "If you have a certificate in other formats such as `.crt`, `.cer` or `.der`, expand here to see how you can convert them to PEM format using [OpenSSL](https://www.openssl.org/){:target=\"_blank\"}"
89+
**Convert CRT to PEM**
90+
```bash
91+
openssl x509 -in cert.crt -out cert.pem
92+
93+
```
94+
**Convert CER to PEM:**
95+
```bash
96+
openssl x509 -in cert.cer -out cert.pem
97+
```
98+
99+
**Convert DER to PEM:**
100+
```bash
101+
openssl x509 -in cert.der -out cert.pem
102+
```
103+
104+
{% else %}
105+
106+
2. (Optional) Upload the public certificate of the identity provider.
107+
108+
{% endif %}
109+
110+
3. Click **Finish** to complete the registration.
82111

83112
### Use a SAML metadata file
84113

@@ -99,12 +128,130 @@ If you selected **File Based Configuration** in the previous step, follow the st
99128

100129
![Create SAML Enterprise IDP with Metadata file]({{base_path}}/assets/img/guides/idp/saml-enterprise-idp/register-saml-idp-with-metafile.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
101130

131+
{% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0") %}
132+
133+
3. (Optional) Provide the mode of certificate configuration.
134+
135+
!!! note
136+
You can either configure a SAML metadata endpoint URL or upload a PEM certificate. {{ product_name }} uses the certificate to validate SAML response signatures and federated IdP-initiated logout request signatures.
137+
138+
- **SAML metadata endpoint**: Enter the metadata endpoint URL of the external identity provider. {{ product_name }} fetches and caches the signing certificate from this URL. Learn more about [certificate validation with the SAML metadata endpoint](#certificate-validation-with-the-saml-metadata-endpoint).
139+
- **Use PEM certificate**: Upload or paste the public certificate of the external identity provider. The certificate should be in PEM format.
140+
141+
??? note "If you have a certificate in other formats such as `.crt`, `.cer` or `.der`, expand here to see how you can convert them to PEM format using [OpenSSL](https://www.openssl.org/){:target=\"_blank\"}"
142+
**Convert CRT to PEM**
143+
```bash
144+
openssl x509 -in cert.crt -out cert.pem
145+
146+
```
147+
**Convert CER to PEM:**
148+
```bash
149+
openssl x509 -in cert.cer -out cert.pem
150+
```
151+
152+
**Convert DER to PEM:**
153+
```bash
154+
openssl x509 -in cert.der -out cert.pem
155+
```
156+
157+
{% else %}
158+
102159
3. (Optional) Upload the public certificate of the identity provider.
160+
161+
{% endif %}
162+
103163
4. Click **Finish** to complete the registration.
104164

105165
!!! note
106166
Once the SAML identity provider is created, you can configure [additional SAML settings]({{base_path}}/references/idp-settings/saml-settings-for-idp/) from the **Settings** tab.
107-
167+
168+
{% if product_name == "Asgardeo" or (product_name == "WSO2 Identity Server" and is_version > "7.2.0") %}
169+
170+
## Certificate validation with the SAML metadata endpoint
171+
172+
When you configure a SAML metadata endpoint, {{ product_name }} fetches and caches the signing certificate from that URL to validate SAML response signatures and federated IdP-initiated logout request signatures.
173+
174+
### Certificate cache invalidation
175+
176+
{{ product_name }} honors the `validUntil` and `cacheDuration` properties defined at the `EntityDescriptor` or `IDPSSODescriptor` level in the SAML metadata to determine when to invalidate the cached certificate:
177+
178+
- **`validUntil`**: The absolute expiry timestamp of the metadata. {{ product_name }} invalidates the cached certificate when this timestamp is reached.
179+
- **`cacheDuration`**: The duration for which the metadata is considered valid. {{ product_name }} invalidates the cached certificate after this duration.
180+
181+
If neither `validUntil` nor `cacheDuration` is defined, a default maximum cache lifetime of 24 hours applies.
182+
183+
{% if product_name == "WSO2 Identity Server" and is_version > "7.2.0" %}
184+
185+
You can change this default in `deployment.toml`:
186+
187+
```toml
188+
[authentication.authenticator.saml.parameters]
189+
RemoteCertificateCacheMaxLifetime = "24h"
190+
```
191+
192+
{% endif %}
193+
194+
### Automatic certificate refresh for key rotation
195+
196+
If signature validation fails, {{ product_name }} automatically fetches fresh certificates from the metadata endpoint to support key rotation scenarios where the external IdP replaces its signing certificate.
197+
198+
{{ product_name }} applies a default 5-minute block period between consecutive refresh attempts to prevent excessive metadata refresh requests.
199+
200+
{% if product_name == "WSO2 Identity Server" and is_version > "7.2.0" %}
201+
202+
You can configure this duration in `deployment.toml`:
203+
204+
```toml
205+
[authentication.authenticator.saml.parameters]
206+
RemoteCertificateRefreshRetryBlockDuration = "5m"
207+
```
208+
209+
### HTTP client configuration
210+
211+
The following parameters configure the HTTP client that fetches the SAML metadata. The values shown are the defaults:
212+
213+
```toml
214+
[authentication.authenticator.saml.parameters]
215+
RemoteCertificateClientConnectionTimeout = "1s"
216+
RemoteCertificateClientReadTimeout = "1s"
217+
RemoteCertificateClientConnectionRequestTimeout = "1s"
218+
RemoteCertificateClientConnectionPoolSize = "20"
219+
RemoteCertificateClientMaxConnectionPerRoute = "3"
220+
RemoteCertificateRetryCount = "0"
221+
RemoteCertificateClientResponseLimit = "512000"
222+
```
223+
224+
| Parameter | Description |
225+
|---|---|
226+
| `RemoteCertificateClientConnectionTimeout` | Maximum time to wait to establish a connection to the metadata endpoint. |
227+
| `RemoteCertificateClientReadTimeout` | Maximum time to wait to read data after a connection is established. |
228+
| `RemoteCertificateClientConnectionRequestTimeout` | Maximum time to wait to obtain a connection from the connection pool. |
229+
| `RemoteCertificateClientConnectionPoolSize` | Total number of connections maintained in the pool. |
230+
| `RemoteCertificateClientMaxConnectionPerRoute` | Maximum connections maintained per route. |
231+
| `RemoteCertificateRetryCount` | Number of retry attempts on a failed metadata fetch. |
232+
| `RemoteCertificateClientResponseLimit` | Maximum response size in bytes accepted from the metadata endpoint. |
233+
234+
### Metadata certificate cache configuration
235+
236+
{{ product_name }} caches the signing certificates fetched from the metadata endpoint. Configure the cache using the following settings in `deployment.toml`. The values shown are the defaults:
237+
238+
```toml
239+
[cache.saml_cert_cache]
240+
enable = true
241+
timeout = 900
242+
capacity = 100
243+
```
244+
245+
| Parameter | Description | Default |
246+
|---|---|---|
247+
| `enable` | Enables or disables the metadata certificate cache. | `true` |
248+
| `timeout` | Cache entry expiration time in seconds. | `900` (15 minutes) |
249+
| `capacity` | Maximum number of cache entries. | `100` |
250+
251+
{% endif %}
252+
253+
{% endif %}
254+
108255
## Enable the SAML IdP for login
109256

110257
{% include "../../../guides/fragments/add-login/standard-based-login/add-saml-idp-login.md" %}

0 commit comments

Comments
 (0)