Jazz Authorization
Server supports security assertion markup language (SAML) web browser
single sign-on (SSO) in the IBM WebSphere Liberty, which enables web applications to delegate user
authentication to a SAML identity provider instead of a configured user registry.
Before you begin
If you have not already done so, copy the files in the
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/defaults
directory up one level to the jazzop directory as described in Managing users on Jazz Authorization Server.Restriction: SAML is supported
for web clients authentication through
Jazz Authorization
Server.
A LDAP user registry is required
for Jazz® Team Server to check the repository permissions of users and user synchronization, such as
JazzAdmins, JazzUsers. The LDAP registry must either be same or identical to the LDAP registry used
by the SAML IDP. For non-web clients, such as repotools, Eclipse client, configure the same LDAP
registry within the Jazz Authorization
Server. For more information on configuring a user registry
with Jazz Authorization
Server, see Configuring the Jazz Authorization Server to use an LDAP user registry.
About this task
Jazz Authorization
Server supports SAML web browser SSO in the IBM WebSphere Liberty. SAML is an OASIS
open standard for representing and exchanging user identity, authentication, and attribute
information. A SAML assertion is an XML formatted token that is used to transfer user identity and
attribute information from the identity provider (IdP) of a user to a trusted service provider (SP)
as part of completing an SSO request. For more information, see SAML web single sign-ons.
To configure the Jazz Authorization
Server as a SAML SSO
service provider (SP), complete the next steps.
Procedure
-
Enable the Jazz Authorization
Server to support
SAML 2.0.
-
Open the
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/server.xml
file in an editor.
-
Locate the SAML xml section and follow the instructions between the
<!--
SAML>
and <!-- end of SAML>
comments to enable the SAML and SSL
features.
-
Open the
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/appConfig.xml
file in an editor.
-
Locate the SAML xml section between the
<!-- SAML>
and <!-- end
of SAML>
comments. Uncomment the <samlWebSso2.0>
and
<authFilter>
elements.
Note:
The EWM Eclipse client and other non-browser clients (such as repotools commands) do not directly
support the SAML protocol, so this configuration excludes them from using the SAML identity provider
for authentication. Instead, the Jazz Authorization Server uses its configured user registry to
authenticate such clients. However, it is possible to use the configuration described in Application Passwords for Native Client Authentication with OpenID Connect to enable the EWM Eclipse client and some other non-browser clients to indirectly
authenticate with the SAML identity provider by using application passwords that are obtained using
SAML authentication.
Example: The following sample code shows the SAML section of an
appConfig.xml file that is edited to support SAML
2.0.
<samlWebSso20
id="defaultSP"
spCookieName="jazzop_sso_cookie_idp"
forceAuthn="true"
authFilterRef="samlAuthFilter">
</samlWebSso20>
<authFilter id="samlAuthFilter">
<requestUrl id="samlRequestUrl" urlPattern="/authorize" matchType="contains" />
<userAgent id="samlUserAgent" agent="Mozilla|Opera" matchType="contains" />
</authFilter>
-
Save your changes and close the file.
-
Export the spmetadata.xml file from the Jazz Authorization
Server (SAML SP) by
following the instructions in step 2 of Configuring SAML web browser SSO in the IBM WebSphere Liberty.
Tip: The spmetadata.xml file contains the keystore pairs that allow
secure communication between the SAML IdP and the Jazz Authorization
Server (SP).
- In a browser window, export the spmetadata.xml file by using the following
URL:
https://host_name:ssl_port/ibm/saml20/defaultSP/samlmetadata
Note: The
port number is defined in the appConfig.xml file.
- Save the file and record the location.
Important: If you are not prompted to save
the file, then there is a problem with the SAML configuration in the Jazz Authorization
Server and the
spmetadata.xml file is not exported. Check the SAML settings in the
appConfig.xml and server.xml files.
-
For the Jazz Authorization
Server to communicate
with the SAML IdP, the server must be registered as a partner in the IdP. Registering and enabling a
partner depends on the SAML implementation in your IdP. Follow the SAML documentation to register
and enable the partner.
-
Export the SAML IdP metadata file so that you can add it to the Jazz Authorization
Server. Follow the
steps to export the metadata file for the IdP.
-
Copy the metadata file that you exported in step 4 to the following
location:
JazzAuthServer_install_dir/wlp/usr/servers/jazzop/resources/security/idpMetadata.xml
-
Test the Jazz Authorization
Server connection to the SAML IdP by using the following URL:
https://JazzAuthServer:port/oidc/endpoint/jazzop/authorize
Note: The port number is defined in the appConfig.xml file.
If you configured the Jazz Authorization
Server correctly, the SAML IdP login window opens or if
the user is already authenticated through SSO it redirects back to JAS.
Note: You can ignore the following error message that you get when you are redirected back to JAS,
A required runtime parameter was missing: client_id
. The purpose of this step is to ensure
that JAS delegates authentication to the SAML IdP and is redirected back to JAS post
authentication.
-
Configure Jazz Authorization
Server to support lightweight directory access protocol (LDAP)
server. This step provides a mechanism for non-web clients to authenticate.
-
Start the Jazz Authorization
Server, as described
in Managing users on Jazz Authorization Server.
-
Validate the Jazz Authorization
Server
configuration.
-
Open a browser window outside the Jazz Authorization
Server host
environment and go to the following URL:
host_name:ssl_port/oidc/endpoint/jazzop/.well-known/openid-configuration
-
Verify that the user registry is configured correctly by going to the following URL:
host_name:ssl_port/oidc/endpoint/jazzop/registration