Configure Ory to use your UI
To define the paths where Ory calls your custom UI, go to Branding → UI URLs in the Ory Console. This view allows you to define the URLs of UI views for every self-service flow. To point to the desired UI, you can use relative or absolute paths.
Unless you set a custom UI base URL, relative links always use your SDK Configuration URL as the base. To get your project's SDK Configuration URL, go to Project settings → Overview in the Ory Console, and copy the URL from the API Endpoints field.
By default, self-service flows use Ory Account Experience, which is a
part of every Ory Network project. In the default setup, the system uses relative paths to point to the appropriate UI for every
screen. The relative links that point to the Ory Account Experience follow the /ui/{flow_name} format.
Custom domain setup
All paid Ory Network plans allow to add a custom domain to your project. After adding a custom domain, you can also set up a base URL of all custom UI views. This is a great way to make Ory work with your existing deployment without adjustments, as you can use the combination of the base URL and relative URLs to point Ory to UI screens for operations such as login or registration you are already hosting.
To set the base URL of custom UI and define the paths for UI views, go to Branding → UI URLs in the Ory Console.
When you define a custom UI base URL, you lose access to the Ory Account Experience. The custom UI base url takes precedence over SDK Configuration URL.
You can toggle the "Enable the Account Experience welcome page" setting to hide the default "welcome" screen that isn't intended for end-users.
Multiple custom domains setup
Ory Network projects starting with the Scale plan can have multiple custom domains registered. You can add a different custom UI base URL of each of the custom domains registered in the project. This allows for a high degree of flexibility, where each of the domains serves its own set of UI views that have a common path makeup but different base URL.
In the real world, this means that you can serve different UI views to customers that interact with different parts of your business, while still allowing them to conveniently use one account that's managed by your Ory Network project.
For example, the ACME Car Parts company has three online storefronts for three different types of automotive products:
- mufflers.com
- carseats.com
- wipers.com
Since all the storefronts are managed and developed by one company, they all serve their UI at the same path, which is
/acme/ui/{flow_name}. But as the apps were developed at different points in time, the team's approach to hosting changed and
influenced the base paths used for serving UI:
- mufflers.com uses
mufflers.com/auth - carseats.com uses
carseats.com - wipers.com uses
wipers.com/self-service/
Using their Growth plan Ory Network project, ACME creates this setup using the User Interface view in the Ory Console:
| Site | Domain | Base URL |
|---|---|---|
| mufflers.com | acme-auto-mufflers.store.prod | mufflers.com/auth |
| carseats.com | acme-carseats.store.prod | carseats.com |
| wipers.com | acme-wipers.store.prod | wipers.com/self-service/ |
This way, ACME users who create an account in one of these stores can use it to shop in the other stores as well. The UI ACME serves changes depending on the store the user visits which allows for consistency with the established visual identity of each of ACME's brands. Since these stores are hosted on different domains, the users must sign in and get an Ory Session issued for the store's domain when they switch between the storefronts.
Development
When developing locally, you can configure Ory Network to use UI views hosted on local machine, for example
http://localhost:1234/login.
To do that, use Ory Tunnel to create a connection between your local environment and
Ory Network and configure the system to accept http://localhost:1234/ as part of the same domain as your project.
Use Ory Tunnel just for development purposes. When you go to production, always add a custom domain to your project.
Reference implementations and examples
Several reference implementations and guides are available for building your own user interface and forms on top of Ory's APIs: