Customizing IBM Cloud Identity

Branding the multi-factor selection and OTP input pages

Customizing the sign on and multi-factor experience of your application is something that all consumers of IBM Cloud Identity have asked for. Fortunately, you can brand almost every page, multi-factor page, and error page that end user facing. Following the steps below provides how to obtain the branding package, manipulating the template, and packaging the branding files back up for upload. We will use curl as it is cross platform but using an API program like Postman provides a better GUI for manipulating API calls.

Note: Once you upload the package, the changes are now live.

Step 1 / Create an API key

Create an API client ID and secret with the following permissions:

1. Read templates
2. Manage templates

Note: Creating an API key is performed by going into the admin portal under the Settings tab, and selecting API Access.

Step 2 / Authorize API

With your new API client ID and secret in hand, obtain an access token by running the following curl command:

curl -X POST \
  https://{tenantUrl}:443/v1.0/endpoint/default/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=openid'

You will receive a JSON respoinse with an access token. Copy this to your clip board for later use.

Step 3 / Download branding templates

With the access token you received, make the following API call to download all template files. It is important to run this command everytime you make a change to get the most up to date templates.

curl -X GET \ https://{tenantUrl}/v1.0/branding/download \ -H 'Authorization: Bearer {access_token}' \ -o branding.zip

This will download a file called branding.zip to the folder that you're terminal window is currently in.

Step 4 / Customize the templates

1. First, unzip the branding.zip file. You will see a parent folder called templates.
2. For the multi-factor selection page, navigate to templates\authsvc\combinedmfa_selection\default\default.
3. Edit the page page.html in an HTML editor.

4. In your HTML form, the following components are the only required components to be present within the HTML.

   • Form: <form id="otp" method="POST" action="@ACTION@">
   • Error message on failures @ERROR_MESSAGE@
   • Hidden input:
     • <input type="hidden" id="operation" name="operation" value="generate">\
     • <input type="hidden" name="otp.user.otp-method.id" value="" id="otp.user.otp-method.id">
   • MFA Options / for each of the enrolled methods available for choice, we need a template variable to indicate a loop.
   
   

   [RPT otpMethods] <div class="bx--form-item" style="margin-bottom:1rem;"> <a id="@OTP_METHOD_ID@" href="#" onClick="postForm('@OTP_METHOD_ID@','@ACTION@')">@OTP_METHOD_LABEL@</a> </div> [ERPT otpMethods]​

   We add in an onClick="postForm('@OTP_METHOD_ID@','@ACTION@')" function to submit the form and push the right variable to the authorization servic

5. Add the following script within the body html tags of your file.

   <script type="text/javascript"> function postForm(id, action) { var form = document.getElementById("otp"); form.setAttribute('action', action); document.getElementById('otp.user.otp-method.id').value = id; form.submit(); } </script>

6. You may add any HTML that you wish, including stylesheets and other JS that needs to be loaded to render the page.

7. For each selection option (TOTP, IBM Verify, SMS, Email, etc) there is a corresponding %method%_login and %method%_error page template. This allows you to completely customize each template brand your end user experience. As an example:

   • For TOTP, open templates/authsvc/totp_login/default/default/page.html and the following components are required.
     • Form: <form id="otp" method="POST" action="@ACTION@">
     • OTP input: <input id="otp-input" name="otp" type="text" maxlength="6" class="bx--text-input" placeholder="Enter your one time passcode.">
     • Hidden: <input name="operation" type="hidden" value="verify">
     • Error message: @ERROR_MESSAGE@

   • For IBM Verify, open templates/authsvc/ibmverify_login/default/default/page.html and the following components are required.

     • Form: <form id="otp" method="POST" action="@ACTION@">
     • Hidden input: <input type="hidden" name="operation" value="verify">
     • Hidden input: <input id="authStatus" type="hidden" name="authStatus" value="FAILED">
     • Place this javascript in the head tag:
     


     <script type="text/javascript"> if (self === top) { var antiClickjack = document.getElementById("antiClickjack"); antiClickjack.parentNode.removeChild(antiClickjack); } else { top.location = self.location; } function checkAuthStatus() { document.forms[0].submit(); } </script>

     • Place this javascript within the body tag:
     


     <script> setTimeout(function () { checkAuthStatus(); }, 3000); </script>

     
     Example IBM Verify login page:

Note: You can add styles and classes to the input fields to style the page as long as the input fields and form action are present.

Step 5 / Upload the templates

1. Zip (compress) the templates parent folder after you are done.
2. With the same access token you used, make the following API call to upload all template files.

Note: Ensure that file=@ prefixes the file path in this API call.

curl --location --request POST 'https://{tenantUrl}/v1.0/branding/upload' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'file=@/path/to/templates.zip'

You should expect a 201 Created response if all checks out.

Your templates are now immediately live in production. If you don't see your template live, then either the upload failed, or your browser has cached the older templates. Try a private browser without cache in order to test accurately.

Download Sample

Download a sample template file for the mfa-selection page as a basis for your project. You should find this file attached to this page.