This end-to-end example helps you get familiar with configuring OpenID Connect (OIDC) in
Liberty since it takes you from installing Liberty through configuring OpenID Connect. The result is
that client applications can verify the identity of a user by relying on authentication from an
OpenID Connect Provider.
About this task
You can set up an OpenID Connect Provider and OpenID Connect Relying Party by completing these
steps in the following procedure:
- Install Liberty.
- Create two servers.
- Download and install an IBM®-provided test application that
includes the Snoop servlet.
- Configure the OpenID Connect Provider and OpenID Connect Relying Party to communicate with each
other by using the localhost host name.
- Log in.
- Edit the OpenID Connect Provider and OpenID Connect Relying Party configurations to use your
real host name.
- Log in.
The following points explain what is happening in the procedure:
- The OpenID Connect Relying Party server and the OpenID Connect Provider server both run on the
same system.
- The OpenID Connect Relying Party server and the OpenID Connect Provider server start with the
localhost host name. They do so to overcome issues that your system might have with a host that
allows outside connections to itself.
- A file-based registry is hardcoded in the server.xml file for the OpenID
Connect Provider server. It contains two entries for the user name and password. One is for the
Jackson
user name and the Password
password. The other is for the
Andrea
user name and the Password
password. In a production
environment, you might instead, for instance, use the LDAP User Registry since users authenticate to
an OpenID Connect Provider. An OpenID Connect Provider is required to have a registry. The OpenID
Connect Relying Party does not need a registry because it trusts the user artifacts, for instance
tokens, that it gets from the OpenID Connect Provider.
- The default keystores use plain text passwords. You can generate an encoded and encrypted
password by using the securityUtility command.
- The HS256 signature algorithm is used for simplicity. Support for the HS256 signature algorithm
is not mandatory in the OpenID Connect specification. Many OpenID Providers do not support the HS256
signature algorithm.
- You put the test application in the dropins directory for expedience, but
avoid this practice in a production environment.
- The OIDC trace is enabled so that you can view the trace.log file of the
server if you encounter errors.
Procedure
-
Install a Liberty Server.
- Download the WebSphere® Application Server Liberty
.zip file.
If you have an IBM login
with
entitlement, you can download
Liberty
from IBM Fix Central. Alternatively, you can download
Liberty for developers. Choose one of the
following options:
- Option 1: Obtain Liberty from IBM Fix
Central with your IBM login.
-
- Navigate to Fix Central.
- In the Filter your content section, under the And Fix
type filter criteria, select fix pack. This section includes
options for both fix pack, in lowercase, and for Fix
Pack. Select the lowercase fix pack option, not Fix
pack.
- Under And Applies to filter criteria, scroll to the end of the list and
click the highest fix pack number. For example.23.0.0.3.
- Click Submit.
- In the Filter fix details field, specify the following
content.
wlp-webprofile8
- From the resulting list of packages, select and download into a new directory the appropriate
package for your workstation, for example
wlp-webProfile8-23.0.0.3
or
wlp-webProfile8-java8-win-x86_64-23.0.0.3
.If you are not already logged in, you
are prompted for your IBM ID credentials.
- Option 2: Obtain Liberty for
developers
-
- Navigate to WebSphere Liberty for developers.
- Find the Download Package section at the end of the page.
- Download the package that most closely matches your system.
- Extract the downloaded file.
For example, run the following
command:
unzip wlp-webProfile8-23.0.0.3
- Run the following commands from the
wlp/bin
directory:
featureUtility installFeature openidConnectClient-1.0
featureUtility installFeature openidConnectServer-1.0
-
Download the sample Liberty default application.
This default application is in the libertyDefaultApplication.ear file and
contains the Snoop servlet that you use in this example procedure.
If clicking the download link in this step does not download the file to your computer,
right-click the link and select a Download or Save
option for your browser. Alternatively, navigate to the parent directory, right-click the
libertyDefaultApplication.ear file and select a
Download or Save option for your browser.
-
Create the Liberty servers.
-
Create the OpenID Connect Relying Party server.
Run the following command from the
wlp/bin
directory:
server create Liberty_RP
-
Create the OpenID Connect Provider server.
Run the following command from the
wlp/bin
directory:
server create Liberty_OP
-
Create the server.xml file for the OpenID Connect Relying Party
server.
-
Change to the wlp/usr/servers/Liberty_RP directory.
-
Replace the content of the server.xml file with the following
content:
<server description="Liberty_RP">
<featureManager>
<feature>openidConnectClient-1.0</feature>
<feature>appSecurity-2.0</feature>
</featureManager>
<!-- To access this server from anything other than localhost or the loopback address, add a host attribute to the following element, e.g. host="*" -->
<httpEndpoint httpPort="9081" httpsPort="9444" id="defaultHttpEndpoint"/>
<keyStore id="defaultKeyStore" password="Password"></keyStore>
<openidConnectClient id="RP"
clientId="oidcclient"
clientSecret="password"
authorizationEndpointUrl="https://localhost:9443/oidc/endpoint/OP/authorize"
tokenEndpointUrl="https://localhost:9443/oidc/endpoint/OP/token" >
</openidConnectClient>
<logging traceSpecification="*=info:
com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all:com.ibm.wsspi.security.oauth20.*=all:com.ibm.ws.transport.http.*=all:org.apache.http.client.*=all" traceFileName="trace.log" maxFileSize="20" maxFiles="10" traceFormat="BASIC" />
</server>
-
Create the server.xml file for the OpenID Connect Provider.
-
Change to the wlp/usr/servers/Liberty_OP directory.
-
Replace the content of the server.xml file with the following
content:
<server description="Liberty_OP">
<featureManager>
<feature>openidConnectServer-1.0</feature>
<feature>appSecurity-2.0</feature>
</featureManager>
<!-- To access this server from anything other than localhost or the loopback address, add a host attribute to the following element, e.g. host="*" -->
<httpEndpoint httpPort="9080" httpsPort="9443" id="defaultHttpEndpoint"/>
<keyStore id="defaultKeyStore" password="Password"/>
<basicRegistry>
<user name="Jackson" password="Password"/>
<user name="Andrea" password="Password"/>
</basicRegistry>
<openidConnectProvider id="OP" oauthProviderRef="oauth"/>
<oauthProvider id="oauth">
<localStore>
<!-- The default redirect URL pattern is: https://<hostname>:<sslport>/oidcclient/redirect/<openidConnectClientID> -->
<client name="oidcclient" secret="password" scope="openid" redirect="https://localhost:9444/oidcclient/redirect/RP" />
</localStore>
</oauthProvider>
<!-- To grant all authenticated users access to the OIDC protected resource, grant them the oauth-role authenticated -->
<oauth-roles>
<authenticated>
<special-subject type="ALL_AUTHENTICATED_USERS"/>
</authenticated>
</oauth-roles>
<logging traceSpecification="*=info:
com.ibm.ws.security.*=all:com.ibm.ws.webcontainer.security.*=all:com.ibm.oauth.*=all:com.ibm.wsspi.security.oauth20.*=all:com.ibm.ws.transport.http.*=all:org.apache.http.client.*=all" traceFileName="trace.log" maxFileSize="20" maxFiles="10" traceFormat="BASIC" />
</server>
-
Create the default keystores and keys.
Run the following commands from the
wlp/bin
directory:
server start Liberty_RP
server stop Liberty_RP
server start Liberty_OP
server stop Liberty_OP
-
Add the signer certificate for the Liberty_OP server to the Liberty_RP server as a trusted
certificate.
-
Export the personal certificate from the keystore of the Liberty_OP server.
- Change the directory to wlp/usr/servers/Liberty_OP/resources/security.
- Export the default personal certificate of the Liberty_OP
server:
keytool -exportcert -keystore key.p12 -storepass Password -alias default -file libertyOP.cer
If
you are using the JKS keystore in version 19.0.0.2 and earlier, use your default keystore file, for instance, the
key.jks
file.keytool -exportcert -keystore key.jks -storepass Password -alias default -file libertyOP.cer
This default personal certificate for the Liberty_OP server is a signer certificate.
-
Import the signer certificate from the Liberty_OP server into the keystore of the Liberty_RP
server.
- Copy the libertyOP.cer file to the
wlp/usr/servers/Liberty_RP/resources/security directory.
- Change the directory to wlp/usr/servers/Liberty_RP/resources/security.
- Run the following command to do the import:
keytool -importcert -keystore key.p12 -storepass Password -alias libertyop -file libertyOP.cer -noprompt
If
you are using the JKS keystore in version 19.0.0.2 and earlier, use your default keystore file, for instance, the
key.jks
file.keytool -importcert -keystore key.jks -storepass Password -alias libertyop -file libertyOP.cer -noprompt
- Optional:
View the keystore of the Liberty_RP server:
keytool -list -v -keystore key.p12 -storepass Password
If
you are using the JKS keystore in version 19.0.0.2 and earlier, use your default keystore file, for instance, the
key.jks
file.
keytool -list -v -keystore key.jks -storepass Password
-
Install the Liberty default application onto the Liberty_RP server.
Copy the libertyDefaultApplication.ear file that you downloaded in a
previous step to the wlp/usr/servers/Liberty_RP/dropins directory.
-
Start the Liberty_OP server and the Liberty_RP server.
Run the following commands from the
wlp/bin
directory:
server start Liberty_RP
server start Liberty_OP
-
Open the login page of the Liberty_RP server.
-
In the address bar of your browser, enter the URL of the Liberty_RP server:
http://localhost:9081/snoop
-
Press Enter.
A login window displays.
Important: If you get a browser warning that the connection is not secure, go through
steps in your browser to allow the connection.
-
Log in to the Liberty_OP server and authorize the Liberty_RP server.
-
Authenticate the user to the Liberty_OP server.
- Log in with
Jackson
as the user name and Password
as the
password.
- Click Login.
The Allow client to access the following
data page displays with the openid entry checked.
-
Authorize the Liberty_OP server to allow the Liberty_RP server access to the user's personal
information.
Click Allow once or Allow, remember my
decision.
Important: If you get a browser warning that the connection is not secure, go through
steps in your browser to allow the connection. You might receive this warning because the keystores
used by the httpEndpoint element on both the Liberty_RP server and the Liberty_OP server contain
only self-signed certificates.
If you successfully log in, the Snoop servlet displays on the
Snoop Servlet -
Request/Client Information page.
Important: To log in again, complete at least
one of the following options:
- Log in from a different browser product.
- Clear your cookies in the current browser and follow the previous steps about logging in.
- Close all windows of the browser that you used to log in, reopen the browser, and log in.
- Restart the Liberty_RP server and then follow the previous steps about logging in.
-
Fully qualify your server names.
-
Change the localhost host name in the server.xml file of the Liberty_RP
server to its fully qualified name.
- Edit the wlp/usr/servers/Liberty_RP/server.xml file.
- Add the following attribute to the httpEndpoint element:
host="*"
.
- Change the authorizationEndpointUrl and tokenEndpointUrl attributes of the openidConnectClient
element to use your server host name instead of the localhost host name.
The following example
code specifies the fully qualified server host
name:
<openidConnectClient id="RP"
clientId="oidcclient"
clientSecret="password"
authorizationEndpointUrl="https://wks1.acme.com:9443/oidc/endpoint/OP/authorize"
tokenEndpointUrl="https://wks1.acme.com:9443/oidc/endpoint/OP/token" >
</openidConnectClient>
- Save the file.
When you save the file, a Liberty configuration change is triggered so that you
do not have to restart the server.
-
Change the localhost host name in the server.xml file of the Liberty_OP
server to its fully qualified name.
- Edit the wlp/usr/servers/Liberty_OP/server.xml file.
- Add the following attribute to the httpEndpoint element:
host="*"
.
- Change the redirect attribute of the client element (oauthProvider/localStore/client) to use
your fully qualified server host name instead of the localhost host name.
The following example
code specifies the full-qualified server host
name:
<client name="oidcclient" secret="password" scope="openid" redirect="https://wks1.acme.com:9444/oidcclient/redirect/RP" />
- Save the file.
When you save the file, a Liberty configuration change is triggered so that you
do not have to restart the server.
-
Open the login page by using the fully qualified host name.
- In the address bar of a browser, enter the URL that includes the Liberty_RP
server:
http://<host_name>:9081/snoop
- Press Enter.
A login window displays.
Important: If you
get a browser warning that the connection is not secure, go through steps in your browser to allow
the connection.
-
Log in to the Liberty_OP server and authorize the Liberty_RP server.
-
Authenticate the user to the Liberty_OP server.
- Log in with
Jackson
as the user name and Password
as the
password.
- Click Login.
The Allow client to access the following
data page displays with the openid entry checked.
-
Authorize the Liberty_OP server to allow the Liberty_RP server access to the user's personal
information.
Click Allow once or Allow, remember my
decision.
Important: If you get a browser warning that the connection is not secure, go through
steps in your browser to allow the connection. You might receive this warning because the keystores
used by the httpEndpoint element on both the Liberty_RP server and the Liberty_OP server contain
only self-signed certificates.
If you successfully log in, the Snoop servlet displays on the Snoop Servlet -
Request/Client Information page.
Results
You have a Liberty server that contains the Snoop servlet that is protected by an OpenID Connect
Relying Party. The OpenID Connect Relying Party uses your OpenID Connect Provider for
authentication.
Table 1. Question about the results
Question |
Answer |
Why was the test application protected by the OpenID Connect Relying Party even though the
Snoop servlet and the libertyDefaultApplication test application are not mentioned in the OpenID
Connect configuration? |
The test application was protected because its web.xml file contains a
security constraint that any Java™ EE security-enabled
container supports. When the OpenID Connect Relying Party is running on Liberty, by default the
Relying Party attempts to authorize all requests to any URL that has security constraints. Since the
test application has security constraints on the URL that is being used, the Relying Party
authorizes the requests. |