Configuring WebSphere admin console to login with OIDC

Steps

1. Make sure that you are running the latest version of the OIDC TAI.  See Obtaining WebSphere OpenID Connect (OIDC) latest version. 
2. If you are running in a Network Deployment cell, perform the following actions:
   1. Download the deployOidc.py script from the sample.wsadmin.websphere-traditional Github project.
   2. On the DMgr, run the deployOidc.py script: 

      wsadmin -f deployOidc.py install

      
       When you deploy the OIDC application as an admin app with deployOidc.py, the port that you configure in your callback URL on your OP is the admin port.
3. Configure the OIDC TAI.  See Configuring an OpenID Connect Relying Party
   1. Unless you plan to protect other applications with the TAI, do not perform step 1. 
      • You installed the OIDC application as an admin app in the previous step.
   2. Start with these settings:
       If provider_1 is already in use in your configuration, substitute provider_1 with a provider number that you are not using.
      • If your provider has a discovery endpoint: 
        • Instead of hardcoding other URLs, set provider_1.discoveryEndpointUrl to your OP's discovery endpoint.
      • Set provider_1.filter to request-uri~=/ibm/console(?!/images/)(.*).*
      • Do not set provider_1.signatureAlgorithm
      • If your users are in the local registry:
        • Set provider_1.mapIdentityToRegistryUser to true so that your SSO users get the groups from the registry.
      • If your users and groups are not in the local registry:
        • You need to perform the steps in WebSphere application security role mapping to external groups later.
      • If you are running in a cluster:
        • set provider_1.createSession to true
      • Prevent race conditions:
        • set provider_1.refreshExpiredAccessToken to true (default)
        • set provider_1.refreshBeforeAccessTokenExpiresTime to 30
        • set provider_1.sessionCacheTimeoutMinutes to 0 

          Note: If your OP sends an access token, but no refresh token, despite setting sessionCacheTimeoutMinutes to 0, you are required to re-login to your OP when your access token expires.
      • The port for the redirect URI is the admin secure port.
      • DO NOT set provider_1.useRealm to WAS_DEFAULT
        • Map users to the WebSphere registry or configure your OP's realm as a trusted realm instead.
        • If you use the useRealm property with the console, node synchronization might not work.
4. (Optional) Configure RP-Initiated logout (requires 8.5.5.23 or 9.0.5.14 or later):
   If you want to logout of the OpenID Connect provider when you click logout on the console, follow the instructions on Configuring the OIDC TAI to perform RP-initiated logout.

Further console tuning to avoid user experience issues

1. When the console times out, it reverts to its own login screen that requires WebSphere registry credentials.  Prompting for WebSphere registry credentials is not desirable in a single sign-in scenario.  The only way to prevent this behavior is to disable console timeout:
   • Follow the instructions at How do I disable the console timeout? in the administrative console troubleshooting guide.
     If you do not disable console timeout, if you don't set either the adminconsole.certLogin or adminconsole.ssoLogin JVM property to true as described in the next step, a WebSphere login panel displays when the console times out. 
2. Sometimes when you log in to the console, you might see this page:
   
   Unless you make a configuration change to the console, if you click the second radio button, Return to the Login page and enter a different user ID, the console presents its login page that requires WebSphere credentials.  The only way to circumvent this behavior currently is to set a console custom property that is intended for a different login type: 
   
   The "Client certificate..." sentence is inaccurate, but Use https://{host_name}:{port}/ibm/console is the correct action to take. 
   
    In fix packs 8.5.5.25 and 9.0.5.18, a new custom property called adminconsole.ssoLogin is introduced that, when set to true, displays this message instead: 

   Use https://{host_name}:{port}/ibm/console to login. The application server is configured to use an alternate form of authentication.

    
   1. Navigate to the JVM custom properties page in the administrative console.  Perform one of the following actions:
      • If you are running in a Network Deployment cell, click System administration > Deployment manager > Java and Process Management > Process definition > Java Virtual Machine > Custom properties
      • Otherwise, click Servers > Server Types > WebSphere Application Servers > (serverName) > Expand Java and Process Management (under Server Infrastructure) > Process definition > Java Virtual Machine > Custom properties
   2. On the Custom properties page, click New.
   3. For fix packs 8.5.5.25 and 9.0.5.18 and later, set the name to (the name is case-sensitive):
      • adminconsole.ssoLogin
   4. Otherwise, set the name to:
      • adminconsole.certLogin
   5. Set Value to true.
   6. Click Apply and then Save to save the changes.
3. If you did not configure RP-Initiated logout and you set either the adminconsole.certLogin or adminconsole.ssoLogin properties to true, when you click logout in the console, the Client certificate authentication is enabled panel that is shown in the previous step displays.  This panel can be confusing to users and can be circumvented by configuring the console with a logout exit page.
   • Follow the steps at How do I change the console's logout exit page? on the administrative console troubleshooting guide.

Next steps

• If your users and groups are not in the local registry:
  • Perform the steps in WebSphere application security role mapping to external groups.
• The WebSphereOIDCRP_Admin app that is installed by depolyOidc.py cannot be mapped to application servers.  
  • If you want to use the OIDC TAI to protect other applications in your cell,  install the WebSphereOIDCRP.ear EAR file from the (WAS_HOME)/installableApps directory and map it to your application servers. 
•  The TAI configuration for your "normal" apps is combined with your admin console TAI config; you do not add another RelyingParty interceptor.

Troubleshooting