When using OAuth2 grants in Ory Network, you can use your custom UI implementation in place of the default screens supplied by the Ory Account Experience.
In this example, you run the Authorization Code Grant with a sample application that provides the login and consent pages. This simple Node.js application runs on your machine and is designed to show you how to integrate your pages with OAuth2 in the Ory Network.
Before you start, prepare your environment:
- Install Ory CLI.
- Create an account and project in the Ory Network. Use Ory CLI or go to console.ory.sh.
- Create an API Key and save it in a safe place for later use.
Create OAuth2 client in Ory Network
Create a new OAuth2 client using the Ory CLI. Alternatively, use the API and sending a POST request to the
This is a protected endpoint, which means that you must include the API Key in the
Authorization header of the request.
Read Authorization with API Keys to learn more about API Keys in the Ory Network.
- Ory CLI
Remember to provide the Ory Network project ID and the client name using flags. Don't adjust other flags - they are required for this example.
ory create oauth2-client \
--project ORY_NETWORK_PROJECT_SLUG_OR_ID \
--name YOUR_CLIENT_NAME \
--grant-type authorization_code,refresh_token \
--response-type code,id_token \
--scope openid,offline \
Provide this data in the cURL request:
SDK_CONFIGURATION_URL- found in the 'Connect' section of the Ory Console. Must end with '/admin/clients'.
ORY_API_KEY: Ory API Key created in the Ory Console,
curl -X POST 'SDK_CONFIGURATION_URL/admin/clients' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ORY_API_KEY' \
"scope": "openid offline"
Learn more about creating OAuth2 clients in Ory Network by reading the API specification.
After you create the client, copy the
client_secret and save it for later use.
Run the sample application
Follow these steps to run a sample application with login and consent screens:
Clone the repository with the application and install dependencies:
git clone [email protected]:ory/hydra-login-consent-node.git
Export the API Key and the SDK URL of your project as environment variables:tip
Don't use previously existing API Keys that you use for other purposes. Create a new API Key to use exclusively with the sample application.
export ORY_PAT=ORY_API_KEY # API Key copied from the Ory Console, 'ory_pat' prefix included.
export HYDRA_ADMIN_URL=SDK_CONFIGURATION_URL # Found in the 'Connect' section of the Ory Console.
Start the application on port
When you start the application, go to
http://localhost:3000/ to see the application's welcome page.
Don't close this terminal window. The application must be running to perform the flow. When working with next parts of this document, open new terminal windows.
Configure Ory Network
By default, the Ory Network uses internal redirect URLs for operations such as user login and consent. You can adjust these URLs
to point to pages that handle these operations in your setup. In this example, the sample application runs at
Follow these steps to configure Ory Network to call the sample application for login and consent screens:
Download the OAuth2 Federation Service configuration of your project and save it to a
## List all available projects
ory list projects
## Get config
ory get oauth2-config <project-id> --format yaml > config.yaml
Adjust the configuration in
Update the project configuration using the file you worked with:
ory update oauth2-config <project-id> --file config.yaml
Start a local web server acting as OAuth2 client
Use the Ory CLI to start a web server that acts as the OAuth2 client. To run the Authorization Code Grant, the client ID and client secret must be registered in the Ory Network.
Run this command to create the client. Using flags, provide the client ID and secret of the client created in Ory Network:
ory perform authorization-code \
--client-id ORY_CLIENT_ID \
--client-secret ORY_CLIENT_SECRET \
--project ORY_PROJECT_ID \
--port 5555 \
When this command runs successfully, a browser window opens automatically and displays a welcome page. If this doesn't happen, go
Run the flow
After completing the configuration steps, you can start the flow from the welcome page at
The login and consent application at
http://localhost:3000/ shows live logs in its terminal session. Inspecting them can give
you more insight into how this example works.
To execute the flow:
- In a browser window, go to
http://127.0.0.1:5555/and click Authorize application.
- On the login screen, provide the user details and log in to proceed.
- Choose the scopes you want to give the client access to and click Allow access. You must choose at least one scope.
- The next page shows the tokens the client got as a result of running the Authorization Code Grant flow.
You can get a closer look at the
access_token by decoding it at jwt.io. In the decoded token, you can find
information about the user on whose behalf the client acts and the URL of the issuer - your project.