Skip to content

Commit e92703d

Browse files
shashimalcseshashimalcse
committed
add ws-federation docs
1 parent fb91d0b commit e92703d

File tree

6 files changed

+203
-0
lines changed

6 files changed

+203
-0
lines changed

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

121 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: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
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+
10+
### Prerequisites
11+
12+
- 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.
13+
14+
- 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.
15+
16+
- 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.
17+
18+
### Deploy the sample app
19+
20+
To deploy the sample web app on a web container:
21+
22+
1. Copy the application's downloaded `.war` file into the `webapps` directory of the Tomcat folder.
23+
24+
2. Start the Tomcat server.
25+
26+
### Configure sample properties
27+
28+
To configure additional properties for the sample application:
29+
30+
1. Add the following configurations to the `web.xml` file in `<TOMCAT_HOME>/apache-tomcat-<version>/webapps/PassiveSTSSampleApp/WEB-INF`.
31+
- Specify `idpUrl` as the Identity Server's Passive STS URL.
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+
``` xml
41+
<init-param>
42+
<param-name>replyUrl</param-name>
43+
<param-value>http://localhost:8080/PassiveSTSSampleApp/index.jsp</param-value>
44+
</init-param>
45+
```
46+
47+
- Specify the ` realm ` as a unique identifier for the web app.
48+
``` xml
49+
<init-param>
50+
<param-name>realm</param-name>
51+
<param-value>PassiveSTSSampleApp</param-value>
52+
</init-param>
53+
```
54+
55+
2. Restart the tomcat server.
56+
57+
## Configure the service provider
58+
59+
1. On the WSO2 Identity Server Console, go to **Applications**.
60+
61+
2. Click **New Application** and select **Standard-Based Application**.
62+
63+
3. Enter the following details:
64+
65+
![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;"}
66+
67+
<table>
68+
<tr>
69+
<td>Name</td>
70+
<td>
71+
Give a unique name to identify your application.
72+
<p>e.g.:<code>PassiveSTSSampleApp</code></p>
73+
</td>
74+
</tr>
75+
<tr>
76+
<td>Protocol</td>
77+
<td>Select <b>WS-Federation</b>.</td>
78+
</tr>
79+
<tr>
80+
<td>Realm</td>
81+
<td>
82+
This should be a unique identifier for the web app. Provide the same realm name given to the web app you are configuring WS-Federation for.
83+
<p>e.g.:<code>PassiveSTSSampleApp</code></p>
84+
</td>
85+
</tr>
86+
<tr>
87+
<td>Reply URL</td>
88+
<td>
89+
Provide the URL of the web app you are configuring WS-Federation for. This endpoint URL will handle the token response.
90+
<p><code>http://localhost:8080/PassiveSTSSampleApp/index.jsp</code></p>
91+
</td>
92+
</tr>
93+
</table>
94+
95+
4. Click **Register** to complete the registration.
96+
97+
5. Go to the **Protocol** section of the application, configure the following and click **Update** to save the changes.
98+
99+
<table>
100+
<tr>
101+
<td>Reply Logout URL</td>
102+
<td>
103+
This endpoint in your application handles the logout response from {{product_name}}.
104+
<p><code>http://localhost:8080/PassiveSTSSampleApp/index.jsp</code></p>
105+
</td>
106+
</tr>
107+
</table>
108+
109+
6. Go to the **User Attributes** tab and click **Add User Attribute**, and add the following attributes:
110+
111+
- `http://wso2.org/claims/username`
112+
- `http://wso2.org/claims/emailaddress`
113+
114+
7. Select `http://wso2.org/claims/emailaddress` as the **Subject attribute**.
115+
116+
8. Click **Update** to save your configurations.
117+
118+
## Try it out
119+
120+
!!! info
121+
When redirecting your users to {{product_name}} Passive STS endpoint, the following (optional) parameters are sent in the request from the sample application.
122+
123+
- **wa=wsignin1.0**: specifies whether {{product_name}} should issue a token for the relying party (this is the default action).
124+
- **wa=wsignout1.0**: specifies whether {{product_name}} should log the user out.
125+
- **wreply={replyUrl}**: specifies where the response should be sent.
126+
127+
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}}.
128+
129+
1. Access one of the following links on your browser and click **Login**.
130+
- To get a SAML 1.1 token: <http://localhost:8080/PassiveSTSSampleApp/index.jsp>
131+
- To get a SAML 2.0 token: <http://localhost:8080/PassiveSTSSampleApp?samlv=2-0>
132+
133+
2. Login using your credentials.
134+
135+
3. Provide the required consent. You will be redirected to the {{product_name}} WS-Federation Service and then redirected back to the configured `replyUrl`.
136+
137+
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/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)