Skip to main content

Custom UI with OAuth2 flows

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:

Setup​

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 Ory PAT in the Authorization header of the request.

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

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 Ory PAT and the SDK URL of your project as environment variables:

    tip

    Don't use previously existing Ory PATs that you use for other purposes. Create a new Ory PAT to use exclusively with the sample application.

    export ORY_PAT=ORY_PAT # Ory PAT 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 The 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 The 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.