Configuring an OpenID Connect Provider in Liberty
You can configure a Liberty server to function as an OpenID Connect Provider, or authorization server, to take advantage of web single sign-on.
About this task
You can configure a Liberty server to act
as an OpenID Connect Provider by enabling the openidConnectServer-1.0
feature in
Liberty, and in addition to other
configuration information.
Procedure
-
Add the
openidConnectServer-1.0
Liberty feature and any other needed features to the server.xml file. ThetransportSecurity-1.0
feature is also required for theopenidConnectServer-1.0
feature.<feature>openidConnectServer-1.0</feature> <feature>transportSecurity-1.0</feature>
-
Define an OAuth service provider. OpenID Connect is built on top of the OAuth 2.0 protocol and
you must configure a valid OAuth service provider. The configuration of an OAuth service provider
includes the appropriate
oauth-roles
,oauthProvider
, and user registry elements. Any user that is authorized to use OpenID Connect must also be mapped to theauthenticated oauth-role
. For more information, see Defining an OAuth service provider.The OAuth metadata is updated for OpenID Connect, and the main additions are in the client metadata. If you use the
persistent
mode for client registration, see Configuring an OpenID Connect Provider to accept client registration requests. It is suggested that you follow the document to manage clients. For more information, see Configuring persistent OAuth services. If you use thenon-persistent
mode for client registration, you can register thescope
,preAuthorizedScope
,grantTypes
,responseTypes
,introspectTokens
, andfunctionalUserId
, as well as other attributes. -
Add an
openidConnectProvider
element whoseoauthProviderRef
attribute references the configuredoauthProvider
. EachoauthProvider
can be referenced only by oneopenidConnectProvider
, and two or moreopenidConnectProvider
elements cannot reference to the sameoauthProvider
. Thename
attribute and thesecret
attribute of the client element must match theclient ID
and theclient secret
of the corresponding OpenID Connect Client. This example works with the default Liberty server OpenID Connect Client.Note: In this example, the OP expects the client's SSL port to be set to 443.<openidConnectProvider id="OidcConfigSample" oauthProviderRef="OAuthConfigSample" /> <oauthProvider id="OAuthConfigSample"> <localStore> <client name="client01" secret="{xor}LDo8LTor" displayname="client01" scope="openid profile email"> <redirect>https://server.example.com:443/oidcclient/redirect/client01</redirect> <redirect>https://server2.example.com:443/oidcclient/redirect/client01</redirect> </client> </localStore> </oauthProvider>
Note: A valid client must register its name, redirect, scope, and secret forauthorization_code
grant type. - Configure the truststore of the server to include the signer certificates of the OpenID Connect Relying Parties, or clients, that are supported. For information about keystores, see Enabling SSL communication in Liberty
-
Modify the SSL configuration of the server to use the configured truststore.
<sslDefault sslRef="DefaultSSLSettings" /> <ssl id="DefaultSSLSettings" keyStoreRef="myKeyStore" trustStoreRef="myTrustStore" /> <keyStore id="myKeyStore" password="{xor}Lz4sLCgwLTs=" type="jks" location="${server.config.dir}/resources/security/BasicKeyStore.jks" /> <keyStore id="myTrustStore" password="{xor}Lz4sLCgwLTs=" type="jks" location="${server.config.dir}/resources/security/BasicTrustStore.jks" />
OpenID Connect is configured to use the default SSL configuration that is specified by the server. Therefore, the default SSL configuration for the server must use the truststore that is configured for OpenID Connect.
The user consent form in OpenID Connect is pluggable, which allows providers to create and maintain their own consent form. Because this form is retrieved over SSL, you must configure the truststore to include the signer certificate of the server on which the consent form is hosted. If the default consent form is used and the truststore used for OpenID Connect is configured to be different from the keystore used by the Liberty server, you must import the Liberty server's signer certificate into the OpenID Connect truststore.
In addition to using the SSL default configuration as shown in the example, an outbound default SSL configuration can be configured on the sslDefault element with the outboundSSLRef attribute. If the outbound default attribute is specified, then the SSL configuration that is specified by the outboundSSLRef attribute is used for outbound connections. You can override the default and specify the host and port to use for an outbound connection by using outbound SSL filters in the SSL configuration. For more information, see Outbound filters for SSL configurations and Configuring SSL settings for outbound communications.
Note: To use OpenID Connect, thescope
attribute must includeopenid
in the scope list.For more OpenID Connect Provider configuration options, see OpenID Connect Provider.
For more OAuth configuration options, see Oauth.
- Optional:
Configure your Liberty OpenID Connect
Provider to issue JSON Web Token (JWT) tokens as
access_token
tokens.By default, Liberty issues opaque
access_token
tokens. Opaque tokens require that the token recipient call back to the server that issued the token. You can configure the Liberty OpenID Connect Provider to instead issue JWT tokens asaccess_token
tokens, which include the token verification mechanism within the token, by settingjwtAccessToken="true"
on theoauthProvider
configuration element or implementing thecom.ibm.wsspi.security.oauth20.JwtAccessTokenMediator
service programming interface (SPI).For more information about the interface, see WebSphere OAuth 2.0 web single sign-on SPI or the Java documentation that is provided with the product in the ${wlp.install.dir}/dev/spi/ibm/ directory.
- Optional: Customize the contents
of the
id_token
token that the Liberty OpenID Connect Provider sends.By default, the Liberty OpenID Connect Provider issuesid_token
tokens that contain user name and group membership information. You can customize the token contents in the following ways:- Fully customize the
id_token
contents by implementing thecom.ibm.wsspi.security.openidconnect.IDTokenMediator
SPI. The SPI provides the most flexibility, so you can build your own custom token.For more information about the interface, see WebSphere OAuth 2.0 web single sign-on SPI or the Java documentation that is provided with the product in the ${wlp.install.dir}/dev/spi/ibm/ directory.
- Fetch additional user attributes from the Federated User Registry by listing the additional
claims on the
customClaims
attribute of theopenidConnectProvider
element in the server configuration. If the claim name is different from the attribute name in the Federated User Registry, map the claim name to the attribute on theclaimToUserRegistryMap
element.For example, the following configuration adds several claims and maps thealias
claim to theseeAlso
registry attribute and thelastName
claim to thesn
attribute:<openidConnectProvider id="MyOP" oauthProviderRef="MyOauth" customClaims= "alias, email, lastName, employeeType, office"> <claimToUserRegistryMap alias="seeAlso" lastName="sn"/> ... </openidConnectProvider>
For more information, see Configuring claims returned by the UserInfo endpoint.
- Fully customize the
- Optional: Configure your Liberty OpenID Connect Provider to delegate user
authentication to social login, so users can log in with their social media account.
When social login is configured for your Liberty OpenID Connect Provider, users can log in by using their social media accounts rather than needing to create an account for the Liberty provider. For more information, see Configuring social login in Liberty.
- Optional: Configure your Liberty OpenID Connect Provider to use regular
expressions in client redirect Uniform Resource Locators (URLs).
- To enable the use of regular expressions, set the
allowRegexpRedirects
client attribute to true. - Add a prefix to the
regexp:
string to evaluate URLs as regular expressions.URLs without regular expressions are checked first. - Replace backslashes (\) in your regular expression with exclamation points (!) when you register clients through the registration endpoint.
Note: Allowing redirection to unintended URLs can be a security exposure. If you use regular expressions, be sure that they do not match any URLs that you do not want to allow.In the following example, redirection to the
https://apphost043.example.com
URL is allowable because the URL matches the regular expression:
Exclamation marks (!) can be substituted for backslashes (\) in the regular expression if the backslash causes a parsing error.<openidConnectProvider id="OidcConfigSample" oauthProviderRef="OAuthConfigSample" /> <oauthProvider id="OAuthConfigSample"> <localStore> <client name="client01" secret="{xor}LDo8LTor" displayname="client01" scope="openid profile email" allowRegexpRedirects="true"> <redirect>https://apphost.example.com:443/oidcclient/redirect/client01</redirect> <redirect>regexp:https://apphost\d\d\d\.example\.com:443/oidcclient/redirect/client01</redirect> </client> </localStore> </oauthProvider>
- To enable the use of regular expressions, set the
- Optional: Configure your Liberty OpenID Connect Provider to delegate user
authentication to Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) authentication, so
that users can use SPNEGO Single Sign-On (SSO). When SPNEGO authentication is configured for a Liberty OpenID Connect Provider, users can log in
to the Microsoft Domain Controller and use the SPNEGO SSO.
To enable SPNEGO authentication for OpenID Connect Provider, enable the
spnego-1.0
feature, enable theallowSpnegoAuthentication
attribute of theoauthProvider
element, and configure SPNEGO as needed in the server.xml file. See the following code block for an example.<featureManager> <feature>openidConnectServer-1.0</feature> <feature>spnego-1.0</feature> ..... </featureManager> <oauthProvider id="OAuthConfigSample" allowSpnegoAuthentication="true".....> ..... </oauthProvider> .....
For more information about how to configure SPNEGO authentication, see Configuring SPNEGO authentication in Liberty.