Custom login page for App ID integration

5 min read

Custom login page for App ID integration

When developing an application that integrates with App ID, the standard hosted login page has a few options to change the colours or logo. In some cases, this isn’t enough and direct customisation is necessary. There exists a handy guide for a custom App ID login screen in mobile applications, however for web applications a little more effort is required.

Prerequisites & foreword

The following guide implements a custom App ID login page for web applications, leveraging the standard authorization_code OAuth2 flow.  This guide has the following high level prerequisites:

  • An existing AppID instance that you’ve already configured with generated credentials (clientId and secret)

  • A protected application running on Liberty with an existing openidConnectClient configuration

With instructions on:

  • Deployment of a custom configured authentication webapp

  • Additional modifications to Liberty’s openidConnectClient (OIDC) configuration

If your protected application is running on a different application server product other than Liberty, you will need to interpret this guide in a context equivalent to that application server.


Overview of the authorization flow

The default authorization_code flow with AppID works as follows, with the application server redirecting to the hosted AppID login page in order to request credentials.

Overview of the authorization flow

Default authorization flow with AppID

A new authentication application, OpenidAuth, will position itself between Liberty and the AppID instance. On completion of this guide, the flow therefore becomes the following.

Overview of the authorization flow

Custom authorization flow with AppID

From the viewpoint of the end-user’s browser, OpenidAuth performs exactly the same function as the hosted AppID login page. Behind the scenes however, OpenidAuth automatically performs additional work to to facilitate authentication, by obtaining the AppID tokens and generating a corresponding authorization code.


Get started – deploying the sample OpenidAuth webapp

You can find a copy of the sample OpenidAuth application on Github. This application contains a basic customisable login page, as well as an implementation that integrates with AppID’s /token and/forgot_password endpoints. Prior to deployment the application requires some minor updates to its, with your:

After building and copying the EAR into the <liberty_profile>/servers/<server_name>/dropins directory (which you may have to create yourself), you should see the application deployed:


Expected response: 400 bad request (TenantId is required)

At this point, it’s time to reconfigure your application server to utilize the OpenidAuth application.

Update your OIDC configuration

Liberty’s openidConnectClient configuration must be updated to utilize the new OpenidAuth application you just deployed. Specifically,

  • authorizationEndpointUrl must be updated to https://<appserverhost>:<port>/OpenidAuth/<tenantId>/authorization

  • tokenEndpointUrl must be updated to https://<appserverhost>:<port>/OpenidAuth/<tenantId>/token

You must also ensure that your OIDC configuration does not apply to the OpenidAuth application; this will interfere with the authentication flow. To do so, you must configure an applicable authFilter and supply an authFilterRef to the OIDC configuration element, for example a webapp name pattern:

<authFilter id=”myAuthFilter”>
      <webApp id=”myWebApp” name=”myApp” matchType=”contains”/>

Testing the new flow

When you access any URI in your protected application, unauthenticated users should be directed to the new custom login page, rather than the hosted AppID login page. Ensure that:

  • When entering correct credentials, users are redirected seamlessly to your application

  • When entering incorrect credentials, users are prompted with the login page again

  • When logging out, users are redirected to the login page

  • Users can issue password reset requests from the login page

If any of the above are not successful, this likely suggests that your API key or other configured credentials may not be correct. Check your application server logs for details.

After successful test completion, you may proceed with customizing the look and feel of the OpenidAuth application, specifically login.jsp.


With contributions from Anton Aleksandrov and the AppID team.

Be the first to hear about news, product updates, and innovation from IBM Cloud