Skip to main content
This topic provides general guidelines on how to set up your own Identity Provider (IdP) app. An Identity Provider service is the primary onboarding and authentication entry point for end users. In order to fully implement your Single Sign-On (SSO) capabilities, you configure the primary Identity app to which all of your registered Relying Parties (RPs) will redirect when they need to onboard or authenticate an anonymous user. You have the below options to do this:
  • Write your own custom Identity app service using Digital Identity Management’s Processes and REST APIs.
  • Leverage Digital Identity Management’s proprietary Identity app that comes with a responsive design layout for web and mobile devices.
The Digital Identity Management Identity app is used as the login page whenever a user is trying to authenticate to your RP application. This Identity app allows end users to sign up according to the system you or your administrator has configured in the Digital Identity Management Admin, such as using onboarding and authenticating with third-party social identity provider (for example, Google, Facebook), or requiring that only certain kinds of email addresses can be used. However, if you want full control over the behavior and design of the login and sign-up experience, you may write your own Identity app. Once it is configured and set up, Digital Identity Management will redirect to your Identity app URL whenever a request for SSO comes in without authentication. The Device Authorization Grant endpoint can also be configured to point to your URL instead of the Digital Identity Management Identity app.

​
Implementing your Identity App

If you are writing your own custom Identity app using Digital Identity Management APIs, you will need to, at the very minimum, implement the following:
  1. Construct a login page that accepts an authentication identifier (that is, their email address or mobile number) and password, and calls Digital Identity Management’s POST /session/start API with those credentials. The following conditions apply:
    • The session/start API initializes the Authenticate User Process. This Process handles standard user sign-in flow.
    • Your portal can also leverage the Onboard User with Email and Mobile Process to sign up new users directly into Digital Identity Management data store. Additionally, Digital Identity Management’s Onboard and Authenticate User with Social Account Process enables end users to sign up and sign in with their preferred social identity provider. For more information on how Digital Identity Management API-based Processes work, refer to the Digital Identity Management API Processes guide.
    • You must configure a Google reCAPTCHA v2 site secret and configure the value in the Digital Identity Management Admin console, on the Security Settings UI. Your UI must pass in the reCAPTCHA value when calling the /session/start API. This is critical to prevent brute-force attacks against your end users.
    • Digital Identity Management provides API-based Processes to support Multi-Factor Authentication (for example, SMS/email confirmations, Google Authenticator, FIDO2 devices), though it is up to you as to whether you want to enable that functionality for your end users. If you do, then you will need to write your UI to handle entering these secondary authentication codes.
    • If the final response from the session/start API includes an X-Redirect-Location header, then you must redirect the user’s browser to that location to continue an OIDC-based flow.
    • You must configure Digital Identity Management to construct the confirm-your-email-address link URL pointing to your custom Identity app’s email confirmation page. You can set this URL in the Digital Identity Management Admin console, on the Security Settings UI.
    • If you allow your end users to sign up on their own, you must configure Digital Identity Management to construct the onboard-confirmation link URL (sent to the user’s email or mobile for verification) that points to your custom Identity app’s onboard-confirmation page. This setting is configured in the Digital Identity Management Admin console, on the Security Settings UI.
  2. Your login page should provide a forgot password? button that allows end users to initiate Digital Identity Management’s Recover ID Process. Otherwise, end users will have to call customer support to reset their passwords. You must configure Digital Identity Management to construct the forgot-password email or text messages with URLs pointing to your custom Identity app’s forgot-password continuation page. You can add your desired redirect URLs for all the relevant Processes in Digital Identity Management Admin console, on the Security Settings UI.
  3. If you support 10’/3m Devices (Smart TVs, Set-Top Boxes) using the Device Authorization Grant (DAG) flow, you must write a DAG approval UI which will call Digital Identity Management’s /oidc/device/verify and /oidc/device/approve APIs. You must configure Digital Identity Management to construct the DAG approval link to point to your custom Identity app DAG approval page.

​
Handling Cookies and Requests

Your instance of Digital Identity Management resides at {your-tenant-name}.m1amdocs.com. When you write your own custom Identity app, it will reside on a host of your choice. This creates a problem as the JavaScript-initiated calls to Digital Identity Management endpoints like /session/start and others will be blocked from using cookies according to browser Cross-Origin Resource Sharing (CORS) rules. There are two ways around this issue:
  • Run a Digital Identity Management Proxy – You may run a proxy to Digital Identity Management hosted adjacent to your UI. This proxy will forward all requests to the real Digital Identity Management. It will also modify any cookie hostnames as appropriate. As far as the browser knows, it will be communicating only with your hostnames, and not the true Digital Identity Management hostname.
  • Open a CORS Configuration Request – If you are unable to run a Digital Identity Management Proxy, then you must submit a request to Digital Identity Management support to add your Identity app’s hostname to the Digital Identity Management CORS preflight response headers for your tenant domain.
Parent topic:Single Sign-On