Configure Ory to use your UI
To define the paths where Ory calls your custom UI, go to Ory Console → User Interface. 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 check your SDK Configuration URL, go to Ory Console → Access & APIs.
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 for 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 for custom UI and define the paths for UI views, go to Ory Console → User Interface
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.
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 for 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 of the storefronts are managed and developed by one company, they all serve their UI at the same path, which is
/acme/ui/{flow_name}. However, 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 Scale 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 for development purposes only. When you go to production, always add a custom domain to your project.
Reference implementations and examples
There are several reference implementations and guides available for building your own user interface and forms on top of Ory's APIs: