Skip to content

Commit 47aadd2

Browse files
himeshsiriwardanahimeshsiriwardana
authored
Merge pull request #5163 from Avarjana/master
Add enable mutual SSL doc from IS 6.0 onwards
2 parents 95bdbcc + db6b34d commit 47aadd2

18 files changed

Lines changed: 314 additions & 2 deletions

File tree

‎en/identity-server/6.0.0/docs/assets/img/deploy/security/certificate-exchange-flow.jpg‎

42.6 KB
Loading

‎en/identity-server/6.0.0/docs/deploy/security/enabling-mutual-ssl.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# Enabling Mutual SSL
2+
3+
### How it works
4+
5+
In contrast to the usual one-way SSL authentication where a client
6+
verifies the identity of the server, in mutual SSL the server validates
7+
the identity of the client so that both parties trust each other. This
8+
builds a system that has a very tight security and avoids any requests
9+
made from the client to provide the username/password, as long as the
10+
server is aware of the certificates that belong to the client.
11+
12+
Before the process begins, the client and servers certificates are stored
13+
in there relevant `keystores` . In the case of JAVA
14+
they are `jks` files. Let's take a look at where the
15+
JKS files are saved:
16+
17+
- WSO2 Identity Server certificates are stored in the
18+
`<IS-HOME>/repository/resources/security/wso2carbon.jks` file.
19+
- Server side certificates are stored in the
20+
`<IS-HOME>/repository/resources/security/clienttruststore.jks` file.
21+
22+
These certificates are signed and issued by a certificate authority that
23+
allows both the client and server to communicate freely. Now let's look
24+
at how it works:
25+
26+
![Certificate exchange flow](../../assets/img/deploy/security/certificate-exchange-flow.jpg)
27+
28+
1. The Client attempts to access a protected resource and the SSL/TSL
29+
handshake process begins.
30+
2. The Server presents its certificate, which is the
31+
`server.crt` according to our example as shown
32+
above.
33+
3. The Client takes this certificate and asks the certificate issued
34+
authority for the authenticity and validity of the certificate.
35+
4. If the certificate is valid, the client will also provide its
36+
certificate to the server.
37+
5. The Server takes this certificate and asks the certificate issued
38+
authority for the authenticity and validity of the certificate.
39+
6. The Client is granted access to the resource it was trying to access
40+
earlier.
41+
42+
### Enabling Mutual SSL in the WSO2 IS
43+
44+
1. Open the
45+
`<IS_HOME>/repository/conf/tomcat/catalina-server.xml`
46+
file and ensure that the `certificateVerification` attribute
47+
in the `SSLHostConfig` tag under `https` connector is set to
48+
`want` as shown below. This is done to
49+
disable the certificate authentication on certain occasions (like
50+
when working on mobile apps). This makes two-way SSL authentication
51+
optional. Set the value as `require` to make two-way SSL authentication mandatory.
52+
53+
``` java
54+
certificateVerification="want"
55+
```
56+
If not add the following configuration to `<IS_HOME>/repository/conf/deployment.toml`
57+
58+
```toml
59+
[transport.https.sslHostConfig.properties]
60+
certificateVerification = "want"
61+
```
62+
63+
2. Open the
64+
`deployment.toml`
65+
file and add the following configuration to enable the
66+
Mutual SSL Authenticator.
67+
68+
``` toml
69+
[admin_console.authenticator.mutual_ssl_authenticator]
70+
enable = true
71+
72+
[admin_console.authenticator.mutual_ssl_authenticator.config]
73+
WhiteList = ""
74+
```
75+
76+
3. For mutual SSL authentication, the public certificate of the WSO2
77+
Identity Server has to be imported to the truststore of the client
78+
and the public certificate of the client has to be imported to the
79+
client-truststore of Identity Server.
80+
81+
!!! example "Sample commands"
82+
83+
The following two commands are examples if you are using the
84+
keystore and client-truststore of the Identity Server itself for the
85+
client. This is executed from the
86+
`<IS_HOME>/repository/resources/security`
87+
directory.
88+
89+
``` java
90+
keytool -export -alias wso2carbon -file carbon_public2.crt -keystore wso2carbon.jks -storepass wso2carbon
91+
```
92+
93+
``` java
94+
keytool -import -trustcacerts -alias carbon -file carbon_public2.crt -keystore client-truststore.jks -storepass wso2carbon
95+
```

‎en/identity-server/6.0.0/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -442,6 +442,7 @@ nav:
442442
- Enable HTTP Strict Transport Security (HSTS) Headers: deploy/security/enable-hsts.md
443443
- Configure Transport Level Security: deploy/security/configure-transport-level-security.md
444444
- Enable Java Security Manager: deploy/security/enable-java-security-manager.md
445+
- Enable Mutual SSL: deploy/security/enabling-mutual-ssl.md
445446
- Security Guidelines:
446447
- Overview: deploy/security/security-guidelines-for-production-deployment.md
447448
- Product-Level: deploy/security/product-level-security-guidelines.md

‎en/identity-server/6.0.0/requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
mkdocs>=1.1
22
mkdocs-material==4.2.0
33
markdown-include>=0.5.1
4-
pymdown-extensions==5.0.0
4+
pymdown-extensions==10.3.1
55
mkdocs-redirects==1.0.0
66
mkdocs-markdownextradata-plugin==0.2.5

‎en/identity-server/6.1.0/docs/assets/img/deploy/security/certificate-exchange-flow.jpg‎

42.6 KB
Loading

‎en/identity-server/6.1.0/docs/deploy/security/enabling-mutual-ssl.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Enabling Mutual SSL
2+
3+
### How it works
4+
5+
In contrast to the usual one-way SSL authentication where a client
6+
verifies the identity of the server, in mutual SSL the server validates
7+
the identity of the client so that both parties trust each other. This
8+
builds a system that has a very tight security and avoids any requests
9+
made to the client to provide the username/password, as long as the
10+
server is aware of the certificates that belong to the client.
11+
12+
Before the process begins the client and servers certificates are stored
13+
in there relevant ` keystores ` . In the case of JAVA
14+
they are ` jks ` files. Let's take a look at where the
15+
JKS files are saved:
16+
17+
- WSO2 Identity Server certificates are stored in the
18+
` <IS-HOME>/repository/resources/security/wso2carbon.jks ` file.
19+
- Server side certificates are stored in the
20+
` <IS-HOME>/repository/resources/security/clienttruststore.jks ` file.
21+
22+
These certificates are signed and issued by a certificate authority that
23+
allows both the client and server to communicate freely. Now let's look
24+
at how it works:
25+
26+
![Certificate exchange flow](../../assets/img/deploy/security/certificate-exchange-flow.jpg)
27+
28+
1. The Client attempts to access a protected resource and the SSL/TSL
29+
handshake process begins.
30+
2. The Server presents its certificate, which is the
31+
` server.crt ` according to our example as shown
32+
above.
33+
3. The Client takes this certificate and asks the certificate issued
34+
authority for the authenticity and validity of the certificate.
35+
4. If the certificate is valid, the client will also provide its
36+
certificate to the server.
37+
5. The Server takes this certificate and asks the certificate issued
38+
authority for the authenticity and validity of the certificate.
39+
6. The Client is granted access to the resource it was trying to access
40+
earlier.
41+
42+
### Enabling Mutual SSL in the WSO2 IS
43+
44+
1. Open the
45+
` <IS_HOME>/repository/conf/tomcat/catalina-server.xml `
46+
file and ensure that the ` certificateVerification ` attribute
47+
in the ` SSLHostConfig ` tag under `https` connector is set to
48+
` want ` as shown below. This is done to
49+
disable the certificate authentication on certain occasions (like
50+
when working on mobile apps). This makes two-way SSL authentication
51+
optional. Set the value as `require` to make two-way SSL authentication mandatory.
52+
53+
``` java
54+
certificateVerification="want"
55+
```
56+
If not add the following configuration to ` <IS_HOME>/repository/conf/deployment.toml `
57+
58+
```toml
59+
[transport.https.sslHostConfig.properties]
60+
certificateVerification = "want"
61+
```
62+
63+
64+
2. Open the
65+
` deployment.toml `
66+
file and add the following configuration to enable the
67+
Mutual SSL Authenticator.
68+
69+
``` toml
70+
[admin_console.authenticator.mutual_ssl_authenticator]
71+
enable = true
72+
73+
[admin_console.authenticator.mutual_ssl_authenticator.config]
74+
WhiteList = ""
75+
```
76+
77+
3. For mutual SSL authentication, the public certificate of the WSO2
78+
Identity Server has to be imported to the truststore of the client
79+
and the public certificate of the client has to be imported to the
80+
client-truststore of Identity Server.
81+
82+
!!! example "Sample commands"
83+
84+
The following two commands are examples if you are using the
85+
keystore and client-truststore of the Identity Server itself for the
86+
client. This is executed from the
87+
`<IS_HOME>/repository/resources/security`
88+
directory.
89+
90+
``` java
91+
keytool -export -alias wso2carbon -file carbon_public2.crt -keystore wso2carbon.jks -storepass wso2carbon
92+
```
93+
94+
``` java
95+
keytool -import -trustcacerts -alias carbon -file carbon_public2.crt -keystore client-truststore.jks -storepass wso2carbon
96+
```

‎en/identity-server/6.1.0/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -442,6 +442,7 @@ nav:
442442
- Enable HTTP Strict Transport Security (HSTS) Headers: deploy/security/enable-hsts.md
443443
- Configure Transport Level Security: deploy/security/configure-transport-level-security.md
444444
- Enable Java Security Manager: deploy/security/enable-java-security-manager.md
445+
- Enable Mutual SSL: deploy/security/enabling-mutual-ssl.md
445446
- Security Guidelines:
446447
- Overview: deploy/security/security-guidelines-for-production-deployment.md
447448
- Product-Level: deploy/security/product-level-security-guidelines.md

‎en/identity-server/6.1.0/requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
mkdocs>=1.1
22
mkdocs-material==4.2.0
33
markdown-include>=0.5.1
4-
pymdown-extensions==5.0.0
4+
pymdown-extensions==10.3.1
55
mkdocs-redirects==1.0.0
66
mkdocs-markdownextradata-plugin==0.2.5

‎en/identity-server/7.0.0/docs/assets/img/deploy/security/mutual-ssl.png‎

5.52 MB
Loading

‎en/identity-server/7.0.0/docs/deploy/security/enable-mutual-ssl.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{% include "../../../../../includes/deploy/security/enable-mutual-ssl.md" %}

0 commit comments

Comments
 (0)