Skip to content

Commit 7ec5825

Browse files
himeshsiriwardanahimeshsiriwardana
authored
Merge pull request #5577 from shashimalcse/ws-fed-doc
Add ws-federation docs for asgardeo
2 parents 8670612 + 5625ebd commit 7ec5825

File tree

8 files changed

+214
-61
lines changed

8 files changed

+214
-61
lines changed

‎en/asgardeo/docs/assets/img/guides/applications/create-new-ws-federation-app.png‎

166 KB
Loading

‎en/asgardeo/docs/assets/img/guides/applications/ws-federation/upload-certificate-of-app.png‎

164 KB
Loading

‎en/asgardeo/docs/assets/img/guides/applications/ws-federation/ws-federation-settings.png‎

207 KB
Loading

‎en/asgardeo/docs/get-started/try-samples/ws-federation-webapp.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Sample WS-Federation web app
2+
3+
By following this guide, you will be able to deploy a WS-Federation-based web application and enable login for it using the Passive Security Token Service (Passive STS) of {{product_name}}.
4+
5+
!!! info
6+
{{product_name}} uses its passive security token service (Passive STS) as its WS-Federation implementation.
7+
Passive STS is capable of issuing SAML 1.1 and 2.0 security tokens. To request a SAML 2.0 security token, the Request Security Token (RST) should be sent to the passive STS endpoint with the token type, `SAMLV2.0`. If no RST is specified, {{product_name}} issued a SAML 1.1 token by default.
8+
9+
## Prerequisites
10+
11+
- Download [Apache Tomcat 8.x](https://tomcat.apache.org/download-80.cgi){:target="_blank"} and install it. Tomcat server installation location will later be referred to as `<TOMCAT_HOME>` in this guide.
12+
13+
- It is recommended that you use a hostname that is not `localhost` to avoid browser errors. Modify your machine's `/etc/hosts` entry to reflect this.
14+
15+
- Download the [Passive STS Sample application](https://github.com/wso2/samples-is/releases/download/v4.6.2/PassiveSTSSampleApp.war){:target="_blank"} from the latest release assets.
16+
17+
### Deploy the sample app
18+
19+
To deploy the sample web app on a web container:
20+
21+
1. Copy the application's downloaded `.war` file into the `webapps` directory of the Tomcat folder.
22+
23+
2. Start the Tomcat server.
24+
25+
### Configure sample properties
26+
27+
To configure additional properties for the sample application:
28+
29+
1. Add the following configurations to the `web.xml` file in `<TOMCAT_HOME>/apache-tomcat-<version>/webapps/PassiveSTSSampleApp/WEB-INF`.
30+
- Specify Asgardeo Passive STS URL as `idpUrl`.
31+
32+
``` xml
33+
<init-param>
34+
<param-name>idpUrl</param-name>
35+
<param-value>https://api.asgardeo.io/t/<organization_name>/passivests</param-value>
36+
</init-param>
37+
```
38+
39+
- Specify the `replyURL` as the URL of the web app.
40+
41+
``` xml
42+
<init-param>
43+
<param-name>replyUrl</param-name>
44+
<param-value>http://localhost:8080/PassiveSTSSampleApp/index.jsp</param-value>
45+
</init-param>
46+
```
47+
48+
- Specify the ` realm ` as a unique identifier for the web app.
49+
50+
``` xml
51+
<init-param>
52+
<param-name>realm</param-name>
53+
<param-value>PassiveSTSSampleApp</param-value>
54+
</init-param>
55+
```
56+
57+
2. Restart the tomcat server.
58+
59+
## Configure the application in Asgardeo
60+
61+
1. On the {{ product_name }} Console, go to **Applications**.
62+
63+
2. Click **New Application** and select **Standard-Based Application**.
64+
65+
3. Enter the following details:
66+
67+
![Create a new Passice STS app]({{base_path}}/assets/img/guides/applications/create-new-ws-federation-app.png){: width="700" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
68+
69+
<table>
70+
<tr>
71+
<td>Name</td>
72+
<td>
73+
An unique name to identify your application.
74+
<p>e.g.:<code>PassiveSTSSampleApp</code></p>
75+
</td>
76+
</tr>
77+
<tr>
78+
<td>Protocol</td>
79+
<td><b>WS-Federation</b>.</td>
80+
</tr>
81+
<tr>
82+
<td>Realm</td>
83+
<td>
84+
An unique identifier for the web app. Provide the same realm name given to the web app you are configuring WS-Federation for.
85+
<p>e.g.:<code>PassiveSTSSampleApp</code></p>
86+
</td>
87+
</tr>
88+
<tr>
89+
<td>Reply URL</td>
90+
<td>
91+
URL of the web app you are configuring WS-Federation for. This endpoint URL will handle the token response.
92+
<p><code>http://localhost:8080/PassiveSTSSampleApp/index.jsp</code></p>
93+
</td>
94+
</tr>
95+
</table>
96+
97+
4. Click **Register** to complete the registration.
98+
99+
5. Go to the **Protocol** section of the application, configure the following and click **Update** to save the changes.
100+
101+
<table>
102+
<tr>
103+
<td>Reply Logout URL</td>
104+
<td>
105+
This endpoint in your application handles the logout response from {{product_name}}.
106+
<p><code>http://localhost:8080/PassiveSTSSampleApp/index.jsp</code></p>
107+
</td>
108+
</tr>
109+
</table>
110+
111+
6. Go to the **User Attributes** tab and click **Add User Attribute**, and add the following attributes:
112+
113+
- `http://wso2.org/claims/username`
114+
- `http://wso2.org/claims/emailaddress`
115+
116+
7. Select `http://wso2.org/claims/emailaddress` as the **Subject attribute**.
117+
118+
8. Click **Update** to save your configurations.
119+
120+
## Try it out
121+
122+
!!! info
123+
When redirecting your users to {{product_name}} Passive STS endpoint, the following (optional) parameters are sent in the request from the sample application.
124+
125+
- **wa=wsignin1.0**: specifies whether {{product_name}} should issue a token for the relying party (this is the default action).
126+
- **wa=wsignout1.0**: specifies whether {{product_name}} should log the user out.
127+
- **wreply={replyUrl}**: specifies where the response should be sent.
128+
129+
Using a Network tracer such as a SAML tracer is recommended to analyze the HTTP request and responses in this scenario. With a tracer, you will be able to view the parameters mentioned above and also see the SAML token that is issued from {{product_name}}.
130+
131+
1. Access one of the following links on your browser and click **Login**.
132+
- To get a SAML 1.1 token: <http://localhost:8080/PassiveSTSSampleApp/index.jsp>
133+
- To get a SAML 2.0 token: <http://localhost:8080/PassiveSTSSampleApp?samlv=2-0>
134+
135+
2. Login using your credentials.
136+
137+
3. Provide the required consent. You will be redirected to the {{product_name}} WS-Federation Service and then redirected back to the configured `replyUrl`.
138+
139+
You will see the WS-Federation response with the requested claims on the screen.

‎en/asgardeo/docs/references/app-settings/ws-federation-settings-for-app.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% set product_name = "Asgardeo" %}
2+
{% set product_url_format = "https://api.asgardeo.io/t/{organization_name}" %}
3+
{% set product_url_sample = "https://api.asgardeo.io/t/bifrost" %}
4+
{% set entityID = "accounts.asgardeo.io/t/{organization_name}" %}
5+
{% include "../../../../includes/references/app-settings/ws-federation-settings-for-app.md" %}

‎en/identity-server/next/docs/references/app-settings/ws-federation-settings-for-app.md‎

Lines changed: 5 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,5 @@
1-
# WS-Federation settings for apps
2-
3-
You can find the WS-Federation protocol related settings under **Protocol** section of the selected WS-Federation application.
4-
5-
![WS-Federation settings]({{base_path}}/assets/img/guides/applications/ws-federation/ws-federation-settings.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
6-
7-
## Basic settings
8-
9-
To enable WS-Federation-based single sign-on (SSO), you need to configure the following key identifiers and endpoints.
10-
11-
### Realm
12-
13-
The Realm is a unique identifier for your application. It tells {{product_name}} which application is requesting authentication. This must match the `wtrealm` parameter in the WS-Federation request.
14-
15-
### Reply URL
16-
17-
The Reply URL is the endpoint in your application where {{product_name}} sends the authentication response after a successful login. This should match the `wreply` parameter in the WS-Federation request and must be configured to handle the security token.
18-
19-
### Reply Logout URL
20-
21-
The Reply Logout URL is the endpoint in your application that receives the logout response from {{product_name}}.
22-
23-
## Advanced settings
24-
25-
Use the following advanced settings to enhance the security and behavior of your WS-Federation integration.
26-
27-
### Certificate
28-
29-
If your application signs authentication or logout requests, {{product_name}} uses this certificate to verify their authenticity.
30-
31-
You can either upload a certificate or use a JWKS endpoint to add a certificate.
32-
33-
To upload a certificate:
34-
35-
1. Select <b>Provide Certificate</b> and click <b>New Certificate</b>.
36-
37-
![Upload app certificate]({{base_path}}/assets/img/guides/applications/ws-federation/upload-certificate-of-app.png){: width="400" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
38-
39-
??? note "Convert `.crt`, `.cer` or `.der` certificates to `.pen` using [OpenSSL](https://www.openssl.org/){:target="_blank"}"
40-
41-
{{product_name}} only accepts certificates in the `.pem` format. To convert other certificates to `pem`, use one of the following commands.
42-
43-
- Convert CRT to PEM
44-
45-
```
46-
openssl x509 -in cert.crt -out cert.pem
47-
```
48-
49-
- Convert CER to PEM:
50-
51-
```
52-
openssl x509 -in cert.cer -out cert.pem
53-
```
54-
55-
- Convert DER to PEM:
56-
57-
```
58-
openssl x509 -in cert.der -out cert.pem
59-
```
60-
61-
2. Upload the certificate file or copy the certificate contents.
1+
{% set product_name = "WSO2 Identity Server" %}
2+
{% set product_url_format = "https://localhost:9443" %}
3+
{% set product_url_sample = "https://localhost:9443" %}
4+
{% set entityID = "localhost" %}
5+
{% include "../../../../../includes/references/app-settings/ws-federation-settings-for-app.md" %}

‎en/includes/references/app-settings/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,9 @@
1111
<img src="../../assets/img/logo/saml-logo.svg" alt="SAML" />
1212
<span>SAML</span>
1313
</a>
14+
<a href="../../references/app-settings/ws-federation-settings-for-app" class="card square">
15+
<img src="../../assets/img/logo/ws-fed.svg" alt="WS-Federation" />
16+
<span>WS-Federation</span>
17+
</a>
1418
</div>
1519
</div>

‎en/includes/references/app-settings/ws-federation-settings-for-app.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# WS-Federation settings for apps
2+
3+
You can find the WS-Federation protocol related settings under **Protocol** section of the selected WS-Federation application.
4+
5+
![WS-Federation settings]({{base_path}}/assets/img/guides/applications/ws-federation/ws-federation-settings.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
6+
7+
## Basic settings
8+
9+
To enable WS-Federation-based single sign-on (SSO), you need to configure the following key identifiers and endpoints.
10+
11+
### Realm
12+
13+
The Realm is a unique identifier for your application. It tells {{product_name}} which application is requesting authentication. This must match the `wtrealm` parameter in the WS-Federation request.
14+
15+
### Reply URL
16+
17+
The Reply URL is the endpoint in your application where {{product_name}} sends the authentication response after a successful login. This should match the `wreply` parameter in the WS-Federation request and must be configured to handle the security token.
18+
19+
### Reply Logout URL
20+
21+
The Reply Logout URL is the endpoint in your application that receives the logout response from {{product_name}}.
22+
23+
## Advanced settings
24+
25+
Use the following advanced settings to enhance the security and behavior of your WS-Federation integration.
26+
27+
### Certificate
28+
29+
If your application signs authentication or logout requests, {{product_name}} uses this certificate to verify their authenticity.
30+
31+
You can either upload a certificate or use a JWKS endpoint to add a certificate.
32+
33+
To upload a certificate:
34+
35+
1. Select <b>Provide Certificate</b> and click <b>New Certificate</b>.
36+
37+
![Upload app certificate]({{base_path}}/assets/img/guides/applications/ws-federation/upload-certificate-of-app.png){: width="400" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
38+
39+
??? note "Convert `.crt`, `.cer` or `.der` certificates to `.pen` using [OpenSSL](https://www.openssl.org/){:target="_blank"}"
40+
41+
{{product_name}} only accepts certificates in the `.pem` format. To convert other certificates to `pem`, use one of the following commands.
42+
43+
- Convert CRT to PEM
44+
45+
```
46+
openssl x509 -in cert.crt -out cert.pem
47+
```
48+
49+
- Convert CER to PEM:
50+
51+
```
52+
openssl x509 -in cert.cer -out cert.pem
53+
```
54+
55+
- Convert DER to PEM:
56+
57+
```
58+
openssl x509 -in cert.der -out cert.pem
59+
```
60+
61+
2. Upload the certificate file or copy the certificate contents.

0 commit comments

Comments
 (0)