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.
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.
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 auth.properties, with your:
AppID instance’s clientId and secret
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:
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.