Oracle by Example brandingCustomize the Oracle Identity Cloud Service Sign-In Page Using the Authentication API

section 0Before You Begin

This tutorial uses a custom sign-in application deployed to your local machine to demonstrate how to customize the Oracle Identity Cloud Service sign-in page using the Authentication (REST) API.

Background

By default, Oracle Identity Cloud Service comes with an embedded Sign-In page that you can customize using the Branding feature (in the console, expand the Navigation Drawer , click Settings, and then click Branding.)

The Branding feature allows you to change the Company Name and the Login Text values, as well as upload logo images to replace the defaults. The position of the text and images, and the colors and fonts, remains the same.

If you need to personalize the look-and-feel of the Sign-In page provided by Oracle Identity Cloud Service beyond what the Branding feature supports, Oracle Identity Cloud Service provides an Authentication API that enables you to develop your own customized sign-in page.

This tutorial uses a sample sign-in application as a reference to understand how to use the Authentication API. This sample sign-in application is a single-page application, which consists mainly of a JavaScript file that wraps the necessary calls to the Authentication API endpoints. You can use this application to customize your Oracle Identity Cloud Service sign-in experience.

The application implements the following Oracle Identity Cloud Service use cases:

  • Basic User Name and Password Authentication
  • Muti-Factor Authentication Enrollment
  • 2nd-Factor Authentication
    • Security Question
    • OTP via Email
    • OTP via SMS
    • TOTP
    • Push Notification
  • Social Log In
  • Self Registration
  • I Forgot My Password

The sample sign-in application is localized to support multiple languages such as English, Brazilian Portuguese, Spanish, German, Italian, Danish, Hindi, and Norwegian. See How to Modify the Sample Sign-In Application.

What Do You Need?

To accomplish the tasks described in this tutorial, make sure that you have the following:


section 1Register a Client Credentials Application

Register a client credentials application in Oracle Identity Cloud Service so that the custom sign-in application can perform calls to the Oracle Identity Cloud Service Authentication REST API to sign in users.

  1. In the Identity Cloud Service console, expand the Navigation Drawer, and then click Applications.
  2. In the Applications page, click Add.
  3. In the Add Application dialog box, click Trusted Application or Confidential Application.
  4. Populate the Details pane as follows, and then click Next.
    • Name: My Sign-In Application
    • Description: My Sign-In Application
  5. In the Client pane, select Configure this application as a client now, and then select Client Credentials as the Allowed Grant Types.
  6. In the Client pane, scroll down, click the Add button below Grant the client access to Identity Cloud Service Admin APIs.
    Application
    Description of this image
  7. In the Add App Role dialog window, select Signin, Verify Email, Reset Password, Forgot Password, and Self Registration in the list, and then click Add.
    Application
    Description of this image
  8. Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
  9. In the Application Added dialog box, make note of the Client ID and the Client Secret values, and then click Close.
  10. To activate the application, click Activate.
    Activate the application
    Description of this image
  11. In the Activate Application? dialog box, click Activate Application.

    A success message appears.


section 2Configure an Application to Use the Custom Sign-In Page

You can configure one of your existing applications to use the custom sign-in page instead of Oracle Identity Cloud Service default sign-in page.

  1. In the Identity Cloud Service console, expand the Navigation Drawer, and then click Applications.
  2. Click on your application to access the Details tab, then update the Custom Login URL field with the following value: http://localhost:3000
  3. In the Details tab, also update the Custom Error URL field with the following value: http://localhost:3000/ui/v1/error

    Note: The Social Log In flow relies on the Custom Error URL field as a callback URL. Configure this value if you use the Social Log In use case.

  4. Click Save.
  5. Your application is now ready to use the custom sign-in application.

Note: This tutorial uses localhost:3000 to host the sample custom sign-in application. If you deploy this application to another location, update the Custom Login URL and the Custom Error URL fields with the corresponding URL for the sign-in sample application.

Note: Don't deploy the custom sign-in application in the same domain, URL and server where you host your other applications. The sign-in page needs to be deployed as a single central service accessible to all other applications and users.

Note: Oracle recommends you to use a secure communication protocol (HTTPS) for the custom sign-in application

If you don't have an application previously registered in Oracle Identity Cloud Service, use the following steps to register the Oracle Identity Cloud Service My Apps page for testing purpose.

  1. In the Identity Cloud Service console, expand the Navigation Drawer, and then click Applications.
  2. In the Applications page, click Add.
  3. In the Add Application dialog box, click Trusted Application or Confidential Application.
  4. Enter the following information in the Details pane, and then click Next.
    • Name: My App
    • Description: My App
    • Custom Login URL: http://localhost:3000
    • Custom Error URL: http://localhost:3000/ui/v1/error
  5. In the Client pane, select Configure this application as a client now, and then enter the following information:
    • Allowed Grant Types: Select Authorization Code.
    • Allow non-HTTPS URLs: Select this check box so that the sample application works in non-HTTPS mode.
    • Redirect URL: /ui/v1/myconsole
  6. In the following panes, click Next until you reach the last pane, and then click Finish.
  7. In the Application Added dialog box, make note of the Client ID and the Client Secret values, and then click Close.
  8. To activate the application, click Activate.
    Activate the application
    Description of this image
  9. In the Activate Application? dialog box, click Activate Application.

    A success message appears.


section 3Configure Cross-Origin Resource Sharing (CORS)

Configure the Cross-Origin Resource Sharing (CORS) feature because the sample web application and Oracle Identity Cloud Service are in different domains. CORS allows the sample sign-in application to make REST calls to Oracle Identity Cloud Service using the user browser.

  1. In the Identity Cloud Service console, expand the Navigation Drawer, click Settings, and then click Session Settings.
  2. On the Session Settings page, select Allow Cross-Origin Resource Sharing (CORS), add the value localhost:3000 to the Allowed CORS Domain Names, and then click Save.

section 4Provide Oracle Identity Cloud Service Information

Enter your Oracle Identity Cloud Service domain URL, the Client ID and Client Secret from the My Sign-in Application (registered in section 1), and the My App Client ID in the fields below:

  • Oracle Identity Cloud Service domain URL:
  • My Sign-In Application Client ID:
  • My Sign-In Application Client Secret:
  • My App Client ID (If you used one of your applications in section 2, use the provided the Client ID):

Note: You must update the fields above accordingly before continuing.


section 5Set Up the Custom Sign-In Application to Work with Oracle Identity Cloud Service

Configure and run the sample web application.

Note: Make sure you have provided values to the fields in the previous section, so that the following values are dynamically generated.

  1. Edit the run script file that is present in the root folder of the sample sign-in application, update the bold lines as per the followings values, and then save the file.

    Note: If you are running this application in a Linux or Mac environment, use run.sh script. If you are using Windows use run.bat instead.

    set IDCS_URL=https://MYTENNANT.identity.oraclecloud.com
    set IDCS_CLIENT_ID=mysigninapp_client_id
    set IDCS_CLIENT_SECRET=mysigninapp_client_secret
  2. Open a command prompt or terminal, navigate to the root folder of the sample sign-in application, and then enter npm install to install all of the necessary modules, which are specified in the package.json file in that same folder.

    Note: If you're behind a proxy, then set up the npm's proxy before running the npm install command.

  3. In the same command prompt or terminal window, execute the run script by typing the name of the file, and then press Enter to start the sample sign-in application.

    In the command prompt or terminal window, you see log information that helps you to understand what the sample application is doing.


section 6Test the Custom Sign-In Page

In the previous sections you configured one of your applications to use the custom sign-in page. To test the custom sign-in page, access a resource of your application that is protected by Oracle Identity Cloud Service using a fresh new browser session. This tutorial uses your Oracle Identity Cloud Service My Apps page (https://MYTENNANT.identity.oraclecloud.com/ui/v1/myconsole) for the purpose of this testing.

Note: Make sure you have provided values to the fields in section 4, so that the following values are dynamically generated.

  1. Open a browser window and access the following URL to request an authorization code for the Oracle Identity Cloud Service's My Apps page.
    https://MYTENNANT.identity.oraclecloud.com/oauth2/v1/authorize?client_id=myapp_client_id&response_type=code&redirect_uri=%2Fui%2Fv1%2Fmyconsole&scope=openid&state=1234

    The browser is redirected to the http://localhost:3000/signin.html URL and the custom sign-in application appears.

    Sample Web Application Sign In Page
    Description of this image

  2. Enter valid Oracle Identity Cloud Service user credentials in the USERNAME and PASSWORD fields, and then click SIGN IN.
  3. After Oracle Identity Cloud Service validates the user credentials, the web browser is redirected to the URL passed as a parameter in redirect_uri. In this example, your Oracle Identity Cloud Service My Apps page (https://MYTENNANT.identity.oraclecloud.com/ui/v1/myconsole).


section 7Understand the REST API Calls

As seen in the example above, your application needs to be configured to use the Custom Login URL.

The sample sign-in application works independently from the integration method used between your application and Oracle Identity Cloud Service (SAML Federation, OpenID Connect, or OAuth).

The demonstration presented in the previous section is a typical OpenID Connect flow, where the application needs to query Oracle Identity Cloud Service for an authorization code.

Oracle Identity Cloud Service receives the request for an authorization code, and instead of presenting its default sign-in page, Oracle Identity Cloud Service responds to the user browser with a POST request to the Custom Login URL. The sample sign-in application receives the POST and then it starts a sequence of Authentication API calls.

The Authentication Flow

The following sequence diagram explains the Basic User Name and Password Authentication use case flow, and all the communication that happens between the custom sign-in application and Oracle Identity Cloud Service using the Authentication API endpoints.

Basic username/password Authentication API login flow using the API
Description of the basic username/password authentication API login flow diagram

When you start the sample sign-in application, it calls Oracle Identity Cloud Service to request an access token. The sample sign-in application stores the access token, so that the token can be used as a bearer authorization header during the subsequent Authentication API calls.

The basic username/password authentication API login flow consists of the following REST calls:

  1. Instead of presenting the default sign-in page, Oracle Identity Cloud Service responds to the authorization code URL request with an HTML document that contains a hidden HTML form with two parameters: signature and loginCtx.
  2. The browser receives the HTML code, which contains JavaScript to automatically submit the form to the sample sign-in application.
  3. The sample sign-in application decrypts the loginCtx parameter. This parameter contains some important attributes:
    • requestState: The state of the authentication process. It needs to be used in future POSTs and GETs to Oracle Identity Cloud Service's Authentication API endpoints.
    • nextOp: The next operation the custom sign-in application must perform.
    • nextAuthFactors: The possible authentication factors the sign-in page must present.

    The values of these attributes define which authentication factor, identity providers, and social providers must be presented on the page.

    The sample application returns the sign-in page containing the decrypted values of the loginCtx parameter along with the access token. The sign-in page includes JavaScript that is used to perform AJAX calls to Oracle Identity Cloud Service.

  4. The browser displays the sign-in page and presents the authentication factors.
  5. After the user enters the USERNAME and PASSWORD, and clicks SIGN IN, the browser sends a POST request to the /sso/v1/sdk/authenticate endpoint with the following payload:
    • requestState: The value received in a previous response.
    • op: The operation being executed. In this example, credSubmit.
    • authFactor: The authentication factor being used. In this example, USERNAME_PASSWORD.
    • The user credentials. In this example, as values for the username and password parameters.

    The access token that was retrieved at the application's startup is sent as a Bearer Authorization header.

    Note: Before posting the data to Oracle Identity Cloud Service via AJAX, the browser sends an OPTIONS request to the /sso/v1/sdk/authenticate endpoint to verify if the browser is authorized to post data to Oracle Identity Cloud Service.

  6. The application receives a status code of 200 and an authnToken from the previous post.
  7. The application then sends a POST request to the /sso/v1/sdk/session endpoint to create the user session in Oracle Identity Cloud Service.
  8. The application receives a 302 or 303 status code and a Location response header that contains the callback URL with a valid authorization code.
  9. The browser then redirects to the specified location, so that the application can finish its authentication process with Oracle Identity Cloud Service.
    By this time, the authentication flow is finished, and the application can exchange the authorization code for an ID token, as per the OpenID Connect flow.

To learn more about the Authentication API, visit the Postman Collection repository.

section 8(Optional) Extend Validity of the requestStage Parameter

The Authentication (REST) API uses the requestState parameter to maintain state of the calls that originate from the sample sign-in application. This parameter by default is valid for 15 minutes, but you can change the validity to 12 hours.

The requestState validity is controlled by the boolean property named longLivedPreLoginRequestState. If the value is false (default), the validity is 15 minutes. When true, the validity is 12 hours minimum.

If you need to extend the validity of the the requestState parameter, then follow the procedures below:

  1. Acquire an access token by authenticating a client application against Oracle Identity Cloud Service. See Make Your First REST API Call.
  2. Make a GET request to /admin/v1/SsoSettings/SsoSettings endpoint, and then save the JSON output. Follow the example below:
    curl -k -X GET -H "Authorization: Bearer ACCESS_TOKEN" "https://MYTENTANT.identity.oraclecloud.com/admin/v1/SsoSettings/SsoSettings" -o settings.json
    
  3. Edit the settings.json file, change the value of the longLivedPreLoginRequestState parameter from false to true, and then save the file.
  4. Make a PUT request to /admin/v1/SsoSettings/SsoSettings, passing in the updated JSON file as the input body. Follow the example below:
    curl -k -X PUT -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" "https://MYTENTANT.identity.oraclecloud.com/admin/v1/SsoSettings/SsoSettings" -d '@settings.json'

    After you perform the command above, re-execute step 2, and verify the parameter value has changed.


more informationWant to Learn More?