Try out custom OAuth2 login and consent

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.

Prerequisites

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 /admin/clients API. This is a protected endpoint, which means that you must include the API Key in the Authorization header of the request.

tip

Read Authorization with API Keys to learn more about API Keys in the Ory Network.

Ory CLI

note

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 \
  --redirect-uri http://127.0.0.1:5555/callback

cURL

note

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, ory_apikey_ or ory_pat_ prefix included.

curl -X POST 'SDK_CONFIGURATION_URL/admin/clients' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ORY_API_KEY' \
  -d '{
    "client_name": "YOUR_CLIENT_NAME",
    "grant_types": [
      "authorization_code"
    ],
    "redirect_uris": [
      "http://127.0.0.1:5555/callback"
    ],
    "response_types": [
      "code",
      "id_token",
      "refresh_token"
    ],
    "scope": "openid offline"
  }'

tip

Learn more about creating OAuth2 clients in Ory Network by reading the API specification.

After you create the client, copy the client_id and 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:

1. Clone the repository with the application and install dependencies:

   git clone git@github.com:ory/hydra-login-consent-node.git
   cd hydra-login-consent-node/
   npm i

2. 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.

3. Start the application on port 3000:

   npm start

When you start the application, go to http://localhost:3000/ to see the application's welcome page.

note

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 http://localhost:3000.

Follow these steps to configure Ory Network to call the sample application for login and consent screens:

1. Download the OAuth2 Federation Service configuration of your project and save it to a yaml file:

   ## List all available projects
   ory list projects
   
   ## Get config
   ory get oauth2-config <project-id> --format yaml > config.yaml

2. Adjust the configuration in oauth2/urls/consent and oauth2/urls/login:

   config.yaml

   oauth2:
     # ...
     urls:
       consent: http://localhost:3000/consent
       error: /oauth2/fallbacks/error
       login: http://localhost:3000/login
       post_logout_redirect: /oauth2/fallbacks/logout

3. 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 \
  --scope openid,offline

When this command runs successfully, a browser window opens automatically and displays a welcome page. If this doesn't happen, go to http://127.0.0.1:5555/.

Run the flow

After completing the configuration steps, you can start the flow from the welcome page at http://127.0.0.1:5555/.

tip

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:

1. In a browser window, go to http://127.0.0.1:5555/ and click Authorize application.
2. On the login screen, provide the user details and log in to proceed.
3. Choose the scopes you want to give the client access to and click Allow access. You must choose at least one scope.
4. The next page shows the tokens the client got as a result of running the Authorization Code Grant flow.

note

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.