Determining links available to ACUL screens

Get Help
,
1

Hello,

I am working on multiple ACUL pages and have had success with configuring most pages. I am currently running into issues with the reset-password screens and determining what links are available to these screens.

Some screens have explicitly named and exported links (like the signup and reset_password links in the login-id screen interface here) as well as explicitly named and exported link variables (like the signupLink and resetPasswordLink in the login-id screen interface here).

I do not see any such links being explicitly named or exported in the reset-password-success interface here. The reset-password-success example md here makes reference to resetPasswordSuccessManager.screen.links.back_to_app, but I don’t know where/how that back_to_app link is known, exported, declared, etc.

I see that the reset-password-request screen interface doesn’t have extra links exported, but it does export a backToLogin function here. I am relatively new to React/Node development and I don’t see where this function is actually declared and what it does under-the-hood, but I do understand that it references some private function that gets declared elsewhere (but not sure where/how) and sends the user back to the application’s login page.

Any information on determining what links are available to a given screen (specifically the reset-password suite of screens in my case) would be greatly helpful.

Thanks!

3

Ok, so I worked with a colleague to dig into this some more and we found out some useful information. There’s still a bit of a black-box situation going on, but we got further along.

Buckle up for the journey:

  • After you run npm build for the ACUL pages, you can look into the root-level index.html.
  • Inside index.html, it runs/loads the app as a module at /src/main.tsx.
  • Inside /src/main.tsx it has a function call to await loadAndSetMockContext().
  • Inside /src/utils/screen/mockContextLoader.ts is the function declaration export async function loadAndSetMockContext(): Promise<void> {….
  • Inside loadAndSetMockContext, it loads window.universal_login_context = mockDataModule.default;.
    • When running locally, it will set the mock data to be const mockDataModule = await import(`../../mock-data/${screenName}.json`);
    • This is actually a trap when running/debugging locally because the mock data files that you use can be manually customized to be whatever you want, but might not reflect what is presented in the live/published page.
  • You have to actually publish and run the whole bloody ACUL page set, navigate to the screen that you want to know more about, open up the browser inspector/console panel, and actually console.log(window.universal_login_context).
    • This will display the context that the window is using which includes the screen.links that it has available to it.

My question is: this information is obviously “known” within Auth0 because it is being fed to the webpage by Auth0 when the screen renders, but where is it defined? Is there a way to find this information within Auth0 itself via the dashboard or an API endpoint?

I saw and used the Management API endpoints for prompts in my initial investigation and the closest one is Get render settings for a screen, but it only gives you the screen.text, not the screen.links.

There must be a way to know what the screen links are for a given page/screen (at least the keys of the possible links). Is there any way to get these values programmatically? Is there a way to force/set the links to be something we know/control via API, Terraform, CLI, dashboard, etc.? Could we set a certain screen.link name and/or value and so we could then account for it in the node file for the ACUL screen/hook/component?

We have local mock data files that can inject screen links, but this is actually a trap when running/debugging locally because the mock data files that we use can declare whatever you want, but might not (and likely will not) reflect what is actually being provided to/presented in the live/published page.

image
image958×249 49.3 KB

4

Hi @nunya-business

Welcome to the Auth0 Community!

To answer your first questions directly: There is no static API endpoint, Terraform resource, or Dashboard setting to fetch, force, or inject custom values into screen.links .

The reason you cannot find this in the Management API is that screen.links is not a static configuration; it is runtime state . Auth0’s internal Identity Engine generates these links dynamically split-second by split-second based on the specific user, the specific application (client_id ), the protocol, and the active database connection. Because these links represent secure, cryptographically bound state transitions, Auth0 strictly prohibits injecting custom external links into this object to prevent open-redirect vulnerabilities.

Since you cannot manipulate the Auth0 context payload, I would suggest to get the real links locally without deploying, and add custom links to your page.

You do not need to publish the page to production just to console.log the real context. You simply need to use the Auth0 CLI proxy correctly.

Instead of running your local React server directly, you must run:
auth0 acul dev

Here is what that CLI command actually does under the hood:

When you use the CLI, mockContextLoader.ts detects the real context and completely ignores your local JSON files. You can open your local browser console and console.log(window.universal_login_context) to see exactly what Auth0 will provide in production.

If you need to add your own links to the page, do not try to inject them into the Auth0 Context object.

Instead, simply hardcode them (or load them from your own custom .env files) directly in your React components. The code should look something like this:

export const ResetSuccessScreen = () => {
  const backToAppDynamic = manager.screen.links.back_to_app;
  
  const myCustomSupportLink = "https://mycompany.com/support";

  return (
    <div>
       <a href={backToAppDynamic}>Return to your app</a>
       <a href={myCustomSupportLink}>Contact Support</a>
    </div>
  )
}

Otherwise, I can see that you have also opened a support ticket on the matter, I would highly advise you to continue receiving support on that specific communication channel regarding the matter. I will be providing updates for everybody else on this end whenever possible.

If I can help you out with any other questions, let me know!

Kind Regards,
Nik

5

Hey @nik.baleca , thanks for the response.

To clarify: I’m not necessarily looking for, or wanting to set, the actual value of the links themselves. I am more interested in understanding how the key names of the screen links is determined, set, exported, etc.

Example: the reset-password-success apparently has a screen.link.back_to_app variable (the actual key of back_to_app), but that isn’t declared or exported anywhere in the code base. I had to do the console.log of the live window to see any reference to back_to_app to know that was even a key that I could use as a reference.

A little more explanation of what I did in my investigation:

/auth0-acul-js/dist/types/interfaces/models/screen.d.ts has an exported interface which sets links as a generic Record object with a string key and string value (link).

export interface ScreenContext {
    name: string;
    links?: Record<string, string>;
    captcha?: CaptchaContext;
    data?: ScreenData;
    texts?: Record<string, string>;
}

Some screens then explicitly extend ScreenContext and export screen links like /auth0-acul-js/dist/types/interfaces/screens/login-id.d.ts with signup and reset_password links (link).

export interface ExtendedScreenContext extends ScreenContext {
    links: {
        signup: string;
        reset_password: string;
    };
    data?: {
        passkey?: PasskeyRead;
    };
}

However, /auth0-acul-js/dist/types/interfaces/screens/reset-password-success.ts (link) does not extend ScreenContext and there is no way to know that back_to_app is even a key you can reference without running console.log(window.universal_login_context).

Is there any way, outside of running the acul screens, to determine what link keys are available to the screens since apparently not all of them are exported or named in the code itself?

Thanks,

Mike

6

Hi again!

As far as I have investigated, there is currently no external API, dashboard tool, or official documentation page that provides an exhaustive list of all possible screen.links keys for every screen.

The reason you cannot find back_to_app explicitly declared for reset-password-success in the SDK code is simply that the @auth0/auth0-acul-js TypeScript definitions appear to be currently incomplete. The SDK relies on a generic Record<string, string> fallback for screens where the engineering team hasn’t explicitly mapped the extended context yet.

Since there isn’t a programmatic API to query these keys, you have two reliable strategies:

->While you noted that local mock data can be manipulated, the default mock-data JSON files provided inside the official Auth0 auth0-acul-samples repository are generated by the Auth0 engineering team.
These files represent the most accurate, baseline snapshot of what the backend state machine actually outputs for each screen. If you look at the reset-password-success.json in the official repo, you will see "links": { "back_to_app": "..." } is present. Until official documentation is published, treating this specific GitHub folder as your “key dictionary” is your safest bet.

→ Since you know back_to_app exists, you don’t have to live with the weak Record<string, string> typing in your project. You can use TypeScript Module Augmentation to force your local environment to recognize the key, restoring your autocomplete and type safety.

Create a auth0-acul-overrides.d.ts file in your project:

import { ScreenContext } from '@auth0/auth0-acul-js/interfaces/models/screen';

declare module '@auth0/auth0-acul-js/interfaces/screens/reset-password-success' {
  export interface ResetPasswordSuccessContext extends ScreenContext {
    links: {
      back_to_app: string;
      // Add any other keys you discover here
    };
  }
}

If I can help with anything else, let me know!

Kind Regards,
Nik