You can configure a WebSphere® Application Server to function
as an OpenID Connect (OIDC) Relying Party (RP, or client) to take advantage of web single sign-on
using an OpenID Connect Provider as an identity provider.
Read OpenID Connect overview for more information on OpenID Connect.
Review the properties that you must configure for OpenID Connect Relying Party configuration
options. Read OpenID Connect Relying Party custom properties for more information.
Avoid trouble:
-
If you are running in a cluster environment, the OpenID Connect Relying Party (RP) Trust
Association Interceptor (TAI) requires session affinity.
- If you are using an outbound proxy, the OpenID Connect RP does not provide a means to route
requests through a proxy host automatically.
If you must use a proxy to access the OpenID Connect
Provider (OP), the value that you enter for any OP-related URL property must contain the proxy host
and port. The value that you enter for any OP-related URL property must not contain the external OP
host and port.
Usually, you can replace the OP host and port with the proxy host and port. The
URL that you enter must be visible to both the RP and client (browser or application). For further
guidance on how to determine the correct URL to use, contact your proxy administrator.
About this task
To configure a WebSphere Application Server to act as an OpenID
Connect Relying Party, follow these steps:
- Make sure that your OIDC runtime is up to date.
-
Install the OpenID Connect application.
Avoid Trouble:
If you intend to use OIDC in multiple clusters load-balanced by IBM HTTP Server with the web
server plug-in, install the application to each cluster with a unique application name and context
root.
- The web server plug-in requires unique context roots to maintain session affinity in a multiple
cluster environment.
- While an application can be mapped to multiple clusters in the administrative console, the web
server plug-in maps the context root for the application to a single cluster.
- When a context root is mapped to a single cluster, the web server plug-in sends requests with
that context root to that cluster only.
- Requests with that context are also not sent to other clusters even when the mapped cluster is
deactivated.
- If you are using another product for load balancing, consult that product's documentation to
determine whether unique context roots are needed for session affinity.
Avoid Trouble: If you intend to use OIDC in multiple clusters
load-balanced by IBM HTTP Server (IHS) with the web server plug-in, install the application to each
cluster with a separate application name and context root.
- The web server plug-in requires distinct context roots to maintain affinity with back-end
servers in each cluster.
- If you are using another product for load balancing, consult that product's documentation to
determine whether distinct context roots are needed for session affinity.
Choose one of the following approaches:
- Using the administrative console, install the
app_server_root/installableApps/WebSphereOIDCRP.ear
file to your application server
or cluster.
- Install the OpenID Connect application by using the python script.
- Navigate to the app_server_root/bin directory.
- Run the script installOIDCRP.py for each profile on which the OpenID
Connect RP is to be installed.
cd <install_root>/bin
wsadmin -f installOIDCRP.py install nodeName serverName
or
wsadmin -f installOIDCRP.py install clusterName
where
nodeName
is the node name of the target application server,
serverName
is the server name of the target application server, and
clusterName
is the name of the cluster on which OpenID Connect RP is to be
installed.
- Import the OpenID connect provider's SSL signer certificate to the WebSphere Application Server truststore.
-
In the administrative console, click Security > SSL certificate and key
management > Key stores and certificates > NodeDefaultTrustStore > Signer
certificates.
Use CellDefaultTrustStore instead of NodeDefaultTrustStore for a deployment manager.
-
Complete one of the following actions.
- Retrieve the signer certificate of the OP from its SSL port.
- Click Retrieve from the port.
- Enter the information that is required to retrieve the OP's signer certificate.
- In the Host field, enter the hostname of your OP.
- In the Port field, enter the SSL port of your OP.
- In the Alias field, enter an alias that is associated with the OP's
signer certificate in your truststore.
- Click Retrieve signer information.
- Click Ok.
- Retrieve the signer certificate of the OP from a file.
- Click Add.
- Enter the certificate information:
- In the File name field, enter the path to the file that contains the
signer certificate of your OP.
- In the Alias field, enter an alias that is associated with the signer
certificate of the OP in your truststore.
- Click OK.
- Recommended: Add the OpenID Connect Relying Party TAI class to
com.ibm.websphere.security.InvokeTAIbeforeSSO
.
For more information, see the Important
note in the Before you begin section for information on how the
com.ibm.websphere.security.InvokeTAIbeforeSSO
property works.
- Click Security > Global security and then click
Custom properties.
- Check the list for
com.ibm.websphere.security.InvokeTAIbeforeSSO.
- If the
com.ibm.websphere.security.InvokeTAIbeforeSSO
property does not exist,
click New, and define the following custom property information:
- Name:
com.ibm.websphere.security.InvokeTAIbeforeSSO
- Value:
com.ibm.ws.security.oidc.client.RelyingParty
- If
com.ibm.websphere.security.InvokeTAIbeforeSSO
exists:
- Click
com.ibm.websphere.security.InvokeTAIbeforeSSO
.
- Add a comma to the end of the existing value.
- Add
com.ibm.ws.security.oidc.client.RelyingParty
to the end of the existing
value.
- Click OK.
- Enable trust association.
- In the administrative console, click Security > Global security > Web and SIP
security > Trust association.
- If Enable trust association is not checked, check it, then click
Apply.
- Add the OIDC interceptor.
- Click Interceptors.
- Click New to add an interceptor.
- Enter the interceptor class name of
com.ibm.ws.security.oidc.client.RelyingParty.
- Add custom properties for the OIDC interceptor.
The following tables list required and recommended OIDC TAI properties for the OIDC
interceptor:
Table 1. Required OIDC TAI properties
Property |
Value |
Comments |
provider_1.identifier |
|
You create this identifier and it is used to build the redirect URL that is registered with
the OP. |
provider_1.clientId |
|
|
provider_1.clientSecret |
|
|
One of the following properties:
- provider_1.interceptedPathFilter
- provider_1.filter
|
|
If a request matches the filter conditions for more than one provider, the provider
configuration that the TAI chooses is indeterminate. |
Table 2. Recommended OIDC TAI properties
Property |
Value |
Comments |
provider_1.discoveryEndpointUrl |
|
When you configure the discovery endpoint for your OP, you do not have to hardcode the values
for many other properties. The hardcoded properties much match the OP's configuration. Therefore, it
is recommended to obtain the settings directly from the OP. OIDC discovery URLs end with
/.well-known/openid-configuration . |
provider_1.useRealm |
WAS_DEFAULT |
This property and value designates your user and groups from your idToken or JWT to the
WebSphere realm instead of the OP's external realm. When you use this setting, you are not required
to add the OP's realm as an external trusted realm or map the trusted realms to your
applications. |
provider_1.signatureAlgorithm |
HEADER |
The signature algorithm is obtained from the header of each inbound token. |
Table 3. Required OIDC TAI properties for cluster
members
Property |
Value |
Comments |
provider_1.createSession |
true |
|
provider_1.callbackServletContext |
|
Use the context name that you chose in step 2. The context root for the OIDC application is
unique for each cluster. |
The following table lists OIDC TAI properties to consider to use for the OIDC interceptor:
Table 4. OIDC TAI properties to consider
Property |
Value |
Comments |
provider_1.mapIdentityToRegistryUser |
|
When this property is set to true , the user (by shortname) must be in the
WebSphere registry, and group memberships are applied to the user. The default for this property is
false . |
-
Click Apply.
- Recommended: To make your application trust your OpenID provider's realm, complete one of
the following actions:
- Click Save
-
Restart WebSphere Application Server.
The WebSphere Application Server can now communicate with an OpenID
Connect provider as an OpenID Connect Relying Party. See related information for custom
configurations.