In this guide, you will set up a hardened OpenID Certified™ OAuth2 Server andOpenID Connect Provider (OIDC / OP) using open-source technologyOry Hydra on theOry Network.
This five-minute guide is for you if
- you want to use OAuth2 for API security; or
- you want to open up your API to third-party developers likeGitHub; or
- you want to become an identity provider likeGoogle,Facebook, orTwitter; or
- you need to federate (delegate) authentication or authorization.
What is OAuth2 and OpenID Connect again?
The easiest way to explain OAuth2 and OpenID Connect is with an example.CircleCI is a service that integrates with GitHub similar to GitHub Actions.When you connect CircleCI to GitHub, CircleCI asks you (the user) to grantread/write permissions to GitHub repositories. Here, CircleCI is the OAuth2client. The user performs an OAuth2 Flow to grant CircleCI access torepositories on GitHub. GitHub will ask you what repositories you want to grantaccess to and if it is ok to grant other data (access to your email address,profile picture, ...) CircleCI has requested:
In this case, GitHub is the OAuth2 server. Ory OAuth2 & OpenID Connect (OryHydra) enables you to be the same! When executing a similar OAuth2 flow withOry, you get a similar user experience:
For a more technical and in-depth overview of the protocols and relatedterminologies - such as OAuth2 Server, OAuth2 Client, OpenID Connect Provider -head over to these excellent articles:
Ory Hydra: A OAuth2 and OpenID Connect Provider written in Golang
Ory Hydra is an OAuth2 Server and OpenID Certified™ OpenID Connect Providerwritten in Go. It powers the Ory OAuth2 & OpenID APIs on theOry Network.
Compared to other OAuth2 and OpenID Connect Providers it does not implement itsown user database and management (for user login, user registration, passwordreset, 2fa, ...), but uses theLogin and Consent Flow todelegate rendering the Login UI ("Please enter your email and password") andConsent UI ("Should application MyDropboxDownload be allowed to access all yourprivate Dropbox Documents?") to an external application.
When using Ory Hydra on the Ory Network, it automatically integrates with OryIdentities, meaning that you do not need to implement your own Login and ConsentUIs.
Ory Hydra can be integrated with any identity service (your own thing,IdentityServer, Azure AD, ...) and you have full control over the OAuth2 userconsent flow as well! An example application for an OAuth2 Login and Consent appis available atgithub.com/ory/hydra-login-consent-node.
Ory releases hundreds of open-source projects under the Apache 2.0 license. Theservices we use in this tutorial are available on GitHub:
Perform OAuth2 & OpenID Connect flows
Now that the introduction is out of the way, let's get started! To make thisguide as easy to reproduce as possible, we will use the Ory Command LineInterface (Ory CLI) to run Ory Hydra on the Ory Network.
For advanced users and hackers there is a second guide in this articleexplaining how torun Ory Hydra on your local machine using Docker.
To manage Ory resources and configuration we install the Ory CLI.
macOS
Install the Ory CLI on macOS using Homebrew:
# Or with Homebrew installedbrew install ory/tap/cliLinux
Install the Ory CLI on Linuxoid systems using curl and bash:
bash <(curl https://raw.githubusercontent.com/ory/meta/master/install.sh) -b . orysudo mv ./ory /usr/local/bin/Windows
To install the CLI on Windows, use scoop. Run:
scoop bucket add ory https://github.com/ory/scoop.gitscoop install oryCreate Ory Network project
Once the Ory CLI is installed and working, create a new Ory Network project. TheCLI might ask you to sign in or create a free account
ory create project \ --name "Ory Hydra 2.0 Example"and responds with project metadata
Project created successfully!ID 170de7c2-eef8-4405-b884-b0e9692eefb3SLUG elastic-goldstine-1n7d31aph0STATE runningNAME Ory Hydra 2.0 Examplewhich we use to set the environment variable project_id:
project_id="{set to the id from output}"# Example:# project_id="170de7c2-eef8-4405-b884-b0e9692eefb3"That's all you need, your OAuth2 and OpenID Connect server is now available onthe Ory Network at:
https://<slug>.projects.oryapis.com/.well-known/openid-configuration# Example:## https://elastic-goldstine-1n7d31aph0.projects.oryapis.com/.well-known/openid-configurationOAuth2 Client Credentials Grant & Machine-to-Machine
The easiest OAuth2 flow to try out is the Client Credentials Flow. To performthe flow we
- create an OAuth 2.0 Client;
- perform the OAuth 2.0 Client Credentials Flow;
- Receive an OAuth 2.0 Access Token.
- Validate the OAuth 2.0 Access Token.
The OAuth2 Client Credentials grant is often used for machine-to-machineauthentication.
Create OAuth2 Client for Client Credentials Flow
Let's create an OAuth2 client capable of performing the OAuth2 clientcredentials grant:
ory create oauth2-client --project $project_id \ --name "Client Credentials Demo" \ --grant-type client_credentialsFlag --grant-type client_credentials allows the OAuth 2.0 Client to performthe OAuth 2.0 Client Credentials grant. The CLI will respond with somethingsimilar to:
CLIENT ID a9dff982-bbf0-44d4-9c96-a9ed54fa9beeCLIENT SECRET bDZcNyaeh7otTb-JBOC67ScdgzGRANT TYPES client_credentialsRESPONSE TYPES codeSCOPE offline_access offline openidAUDIENCEREDIRECT URISNext we copy and paste the OAuth2 Client ID and Secret into the environmentvariables:
client_id="{set to client id from output}"client_secret="{set to client secret from output}"# Example:# client_id="a9dff982-bbf0-44d4-9c96-a9ed54fa9bee"# client_secret="bDZcNyaeh7otTb-JBOC67Scdgz"Perform OAuth2 Client Credentials Flow
Let's exchange the OAuth2 Client ID and Client Secret
ory perform client-credentials --project $project_id \ --client-id=$client_id \ --client-secret=$client_secretto receive an OAuth2 Access Token
ACCESS TOKEN ory_at_gTj6pxe_5SVTiTVrz-cEjxEaGFeWi2pb3TFiK8oLDnQ.3ZADwoHpJcPT-QE9ZwMawpiBM7XhaGCTEmgWh-Hl_6IREFRESH TOKEN <empty>ID TOKEN <empty>EXPIRY 2022-10-28 12:44:54 +0200 CESTand finally set it as environment variable access_token:
access_token="{set to access token from output}"# Example:# access_token="ory_at_gTj6pxe_5SVTiTVrz-cEjxEaGFeWi2pb3TFiK8oLDnQ.3ZADwoHpJcPT-QE9ZwMawpiBM7XhaGCTEmgWh-Hl_6I"Introspect and validate OAuth2 Access Token
Validate OAuth2 access tokens usingOAuth2 Token Introspection. The Ory CLIoffers a simple command to perform the API call
ory introspect token --project $project_id \ $access_tokenwhich responds with OAuth2 Access Token metadata:
ACTIVE trueSUBJECT a9dff982-bbf0-44d4-9c96-a9ed54fa9beeCLIENT ID a9dff982-bbf0-44d4-9c96-a9ed54fa9beeSCOPEEXPIRY 2022-10-28 12:44:54 +0200 CESTTOKEN USE access_tokenOry OAuth2 & OpenID (and Ory Hydra) issues opaque Access Tokens to greatlyreduce attack vectors per default but also supports Access Tokens formatted asJSON Web Tokens (JWT). The payload and expiry of all OAuth2 and OpenID Connecttokens is adjustable. For more information on this head over to thedeveloper documentation.
By the way, you can also format the output in the Ory CLI in a variety offormats, for example human-readable JSON
ory introspect token --project $project_id \ --format json-pretty \ $access_tokenresulting in output:
{ "active": true, "client_id": "a9dff982-bbf0-44d4-9c96-a9ed54fa9bee", "exp": 1666953894, "iat": 1666950294, "iss": "https://elastic-goldstine-1n7d31aph0.projects.oryapis.com", "nbf": 1666950294, "sub": "a9dff982-bbf0-44d4-9c96-a9ed54fa9bee", "token_type": "Bearer", "token_use": "access_token"}Perform OAuth2 Authorization Code Flow and OpenID Connect
The OAuth2 Authorization Code Grant is the most common OAuth2 grant. It is usedto authenticate users and authorize access to resources. The Ory CLI has a democommand to help you perform your first OAuth2 Authorization Code Grant usingOry. In a real-world application, this OAuth2 flow is not initiated by the OryCLI but instead with code in an app.
Create OAuth2 Client for Authorization Code Flow
Similar to the OAuth2 Client Credentials flow, we create an OAuth2 clientcapable of performing the OAuth2 authorization code flow
ory create oauth2-client --project $project_id \ --name "Authorize Code with OpenID Connect Demo" \ --grant-type authorization_code,refresh_token \ --response-type code \ --redirect-uri http://127.0.0.1:4446/callbackresulting in output:
CLIENT ID d2e066cd-060d-44c9-92c1-1e73cbd6016eCLIENT SECRET kMARNy2ZMv-ZoNsufkzDfZgK.CGRANT TYPES authorization_code, refresh_tokenRESPONSE TYPES codeSCOPE offline_access offline openidAUDIENCEREDIRECT URIS http://127.0.0.1:4446/callbackSet its OAuth2 Client ID and Client Secret as environment variables:
code_client_id="{set to client id from output}"code_client_secret="{set to client secret from output}"# Example:# code_client_id="d2e066cd-060d-44c9-92c1-1e73cbd6016e"# code_client_secret="kMARNy2ZMv-ZoNsufkzDfZgK.C"Perform OAuth2 Authorization Code Flow
Everything is set up! Let's perform the OAuth2 Authorization Code Flow. We usethe Ory CLI which sets up a demo webserver on your local machine with an OAuth2callback endpoint and a link that starts the OAuth2 flow:
ory perform authorization-code \ --project $project_id \ --client-id $code_client_id \ --client-secret $code_client_secretIf the browser does not open the URL, navigate tohttp://127.0.0.1:4446/ yourself, hit Sign Up andcreate a new user. Once signed up, accept all the permissions in the consentscreen and hit "Allow":
Ory OAuth2 & OpenID APIs (and Ory Hydra) are not anIdentity Managementsolution. Instead, they require an existing Identity Management system.
OAuth2 providers such as Keycloak, OpenAM, or IdentityServer are usuallyfull-stack enterprise identity and access management solutions. They come withcomplex deployment dependencies, technologies not particularly suited forcloud-native environments, and subtle, but annoying limitations at scale. Orysolves OAuth2 and OpenID Connect as a dedicated service, allowing it to beintegrated with any application stack.
To authenticate users, Ory Hydra defines the. A demoOAuth2 Login & Consent app is available atGitHub. On the Ory Networkthe OAuth2 Login and Consent flow is implemented already using Ory Identitiesand the Ory Account experience.
For a short explanation of the different stages of the flow check out thefollowing video which uses thedemo OAuth2 Login & Consent app:
Once you click "allow", the Ory CLI will now show you the access token, refreshtoken and ID token:
ACCESS TOKEN ory_at_GVG1AhpykEgTHBvsgzT4T4u7Xz6VzCw9zDZllX4y_94.Szlmx_66Sj51---BrjL8muA-8tUeSf43G8zfalQgiSQREFRESH TOKEN ory_rt_jz1982pL7-glrOd1_PeTyNTWGyacBF3WlELqVi0btiQ.7G9gj_HS_JHaI8NwaZXimTpWJYXGowiz8gg-_B2Aq7EID TOKEN eyJhbGciOiJSUzI1NiIsImtpZCI6IjkyMzVmNTMzLWY4YWItNDc2Yi04N2I4LWRhZTNhZTZlYTQ4YyIsInR5cCI6IkpXVCJ9.eyJhbXIiOlsicGFzc3dvcmQiXSwiYXRfa*gFzaCI6ImdueWFUNVVHV0FxVU9RbUdfeVBFUHciLCJhdWQiOlsiZDJlMDY2Y2QtMDYwZC00NGM5LTkyYzEtMWU3M2NiZDYwMTZlIl0sImF1dGhfdGltZSI6MTY2Njk1MjQzNSwiZXhwIjoxNjY2OTU2MDM4LCJpYXQiOjE2NjY5NTI0MzgsImlzcyI6Imh0dHBzOi8vZWxhc3RpYy1nb2xkc3RpbmUtMW43ZDMxYXBoMC5wcm9qZWN0cy5vcnlhcGlzLmNvbSIsImp0aSI6ImY2M2Y0MDAxLWVkYTUtNDY1NC1hMGJmLWE0MWMzZjZkYzgwNCIsIm5vbmNlIjoic3pvb3JlbmxkeXZxZGpqYnV5c3ZwbGdyIiwicmF0IjoxNjY2OTUyNDI4LCJzaWQiOiI1NTgyNTkyYy1kMDU1LTQ4M2MtODIyNi02MzkzY2M5MjQzYmIiLCJzdWIiOiI4ZjYyN2UzMi04ZGE4LTQwMTMtOTg0ZC0zODUxOTZiNmVkOWQifQ.CdJAqDHuADBDRqeXpuHf-0Ud9ReUN0LhMMycQnEknKzUOimB0_J-jF-G1feNaJ6Uckg7jZKmi31mpaZv-SL9JSMBUG-9Mkwu7L3Lj5ehWoDYG2uik9GYMaCek0aMpeLp1lRcCCDRgmO963HaRO-CYtR6F2ADSZfxXTOZFOxVrwEMSs9GLxOTpmG_DhDLkOKgQm5iN8kLKGatme5hY8kC4RtgYAvbbQMxhtLqiAFM7mG6PwTvOF32G4kFVL5jkBFbICYf*ckcdXDVd8LBgRXKFvvtGBiUBNhsZYvOLlDPrPI9zYJRWcTiOy6qlAtzFXAN9kqOeSQAc9kzwba0cOszcBkt1FbjcdHVZbAqkTBOvZmIsSPjMzGGj0jAy2DYa0w6ScPRdHjQPCtmTUgs2lfuTwzGrrsY3hADUmVH7ECUKLcAy-pHyjNTwpzcXhHv37a3TlHnuLxCNq_ThZLoycJrg6Nl2XGC5LCJsKDx5-gKdzz-AHVl_tc4ggPjueLny0tQUAVhoZPor7S06nDxwReTcfN18V8bKc-y6FDAK6S_O8nnenE2Lc-KSc0f7avqQOFeEahu2AAWxFzuKBjkxTDy-IUmRmxIAUcDCV6X2VdjVn6yGYD1SMx4YWdbVGe4mLo3z-V_-8gcVQzZwcdVjGjjVh-yrH0g_mbKzBmLrI1RhEfEEXPIRY 2022-10-28 13:20:39 +0200 CESTUsing ory introspect token you can inspect this access token too
code_access_token="{INSERT-ACCESS-TOKEN-FROM-CODE-FLOW-HERE}"ory introspect token --project $project_id \ --format json-pretty \ $code_access_tokenresulting in the following JSON:
{ "active": true, "client_id": "d2e066cd-060d-44c9-92c1-1e73cbd6016e", "exp": 1666962209, "iat": 1666958609, "iss": "https://elastic-goldstine-1n7d31aph0.projects.oryapis.com", "nbf": 1666958609, "scope": "offline openid", "sub": "6ac05266-0e70-4b7b-beb9-963e1c6440bf", "token_type": "Bearer", "token_use": "access_token"}Awesome, you performed all the essential OAuth2 Flows! Want to learn more? Headover to thedocumentation.
Keep reading if you want to learn how to use Ory open-source software in Dockerto reproduce the same results.
Run Ory OAuth2 & OpenID Connect on Docker
Ory develops its software as open source and provides binaries and Dockerimages. Running Ory software yourself is great for experimenting, developing,and contributing to open source!
Running Ory software yourself requires advanced skills in terms of softwareoperations and security. To replicate this guide please use a Unix-familyoperating systems with Docker installed.
AllOry technology follows architecture principlesthat work best on container orchestration systems such as Kubernetes,CloudFoundry, OpenShift, and similar projects. While it is possible to run theOry stack on a RaspberryPI, the integration with the Docker and Containerecosystem is best documented and supported. Ory's architecture is designed alongseveral guiding principles:
- Minimal dependencies (no system dependencies; might need a database backend)
- Runs everywhere (Linux, macOS, FreeBSD, Windows; AMD64, i386, ARMv5, ...)
- Scales without effort (no memcached, etcd, required, ...)
- Minimize room for human and network errors
All Ory software is a single dependency-free binary that you can download at theproject's respective GitHub repository(Ory Hydra,Ory Keto,Ory Kratos). The binaries run on baremetal machines, RaspberryPIs, ARM, Intel, Windows - you name it! Because thisguide requires PostgreSQL and NodeJS (for the UI), we will use Docker to set upthe examples.
Prepare Docker Deployment
Before we head into it, you need to make sure that there are no conflicts withexisting docker containers or other open ports. Please make sure that ports9000, 9001, 9010, 9020 are open.
For Linux
sudo ss -atuln | grep '9000\|9001\|9010\|9020'For Apple MacOS (/bin/bash and /bin/zsh)
sudo netstat -atuln | grep '9000\|9001\|9010\|9020'Note 'netstat' on the MAC does not support all options used in Linux andWindows. The 'lsof' command (\$ man -k lsof) augments some of netstat missingfunctionality.
For Microsoft Windows 10, use the following command:
netstat -an | findstr /r "9000 9001 9010 9020"If the result of the command lists open ports, you must kill the command thatlistens on that port first. Next, you should check if any existing Ory HydraDocker container is running. If there is one, you should kill that Dockercontainer.
docker ps | grep 'hydra'docker kill hydradocker kill --signal=HUP hydraFor Microsoft Windows use
docker ps | findstr "hydra"Create a Docker Network
Initially, a network must be created that attaches all Docker containers so thecontainers can talk to one another.
docker network create hydraguideThe result will be something like this:
641a26284ff2f8ee4580988371b91923d6711e20aa964ebbdf5b2e4b4f2592b8The next section explains how to set up the PostgreSQL database system.
Install and Run PostgreSQL in Docker
This docker command starts postgres container ory-hydra-example--postgres andsets up a database called hydra with user hydra and password secret.
Note: Some code listings use \ at the end of the line. Shells like bashconcatenate these to one line.
docker run --network hydraguide \ --name ory-hydra-example--postgres \ -e POSTGRES_USER=hydra \ -e POSTGRES_PASSWORD=secret \ -e POSTGRES_DB=hydra \ -d postgres:9.6By the way, we do not recommend deploying databases using Docker in production.Use a managed solution like Amazon RDS orGoogle Cloud SQL. Even small instances will beable to serve large traffic numbers, check out some of thebenchmarks.
Configure the Ory Hydra OAuth2 Server and OpenID Connect Provider
The system secret is used to encrypt data at rest, and to sign tokensand authorize codes. Once a database is initialized with a system secret, thatsecret must be used to access the database.
## Linux / macOS #### The system secret can only be set against a fresh database. This# secret is used to encrypt the database and needs to be set to the same value every time the process (re-)starts.# You can use /dev/urandom to generate a secret. But make sure that the secret must be the same anytime you define it.# You could, for example, store the value somewhere.export SECRETS_SYSTEM=$(export LC_CTYPE=C; cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)## Other systems #### While systems like Windows support creating random secrets, we will just use a fixed one for this example.# Keep in mind that this assumes that you're running some type of linux-ish shell:## export SECRETS_SYSTEM=this_needs_to_be_the_same_always_and_also_very_$3cuR3-._Define the Data Source Name (DSN)
The database URL must point to the Postgres container that was created above.The database will be used to persist and query data. Ory Hydra prevents dataleaks as only token signatures are stored in the database. For a valid token,both payload and signature are required.
export DSN=postgres://hydra:secret@ory-hydra-example--postgres:5432/hydra?sslmode=disableThe result will be something like:
postgres://hydra:secret@ory-hydra-example--postgres:5432/hydra?sslmode=disableRun SQL Migrations
Next, the following hydra migrate sql command initializes the database. Itpulls the latest Docker Image for Ory Hydra and runs a container that executesthe hydra migrate sql command.
docker run -it --rm \ --network hydraguide \ oryd/hydra:v2.0.1 \ migrate sql --yes $DSNFor safety's sake, SQL migrations do not run without explicit instructions Thisis the case for new and existing databases.
Run the Ory Hydra OAuth2 Server and OpenID Connect Provider
Besides setting the system secret (SECRETS_SYSTEM), the database URL (DSN ),the public URL (URLS_SELF_ISSUER) of the server, the user login endpoint (URLS_LOGIN) and the user consent endpoint (URLS_CONSENT) are passed usingenvironment variables.
Both user login and consent URLs point to one or two web service(s) thatwill be explained and set up in the next sections. For now, it connects OryHydra to an identity management system that handles user registration, profilemanagement, and user login.
In this example, Ory Hydra runs HTTP instead of HTTPS. This simplifies theapplication. In a production scenario, HTTPS and more secure values would beused.
There are two exposed ports in this case: 9000 and 9001. The former (9000)serves API requests coming from the public internet e.g.: /oauth2/auth/oauth2/token while the latter (9001) serves administrative API requests thatshould not be available, without administrator intention, to the publicinternet.
docker run -d \ --name ory-hydra-example--hydra \ --network hydraguide \ -p 9000:4444 \ -p 9001:4445 \ -e SECRETS_SYSTEM=$SECRETS_SYSTEM \ -e DSN=$DSN \ -e URLS_SELF_ISSUER=http://127.0.0.1:9000/ \ -e URLS_CONSENT=http://127.0.0.1:9020/consent \ -e URLS_LOGIN=http://127.0.0.1:9020/login \ oryd/hydra:v2.0.1 serve all --devIs it alive?
This is easy to answer, just check the docker logs! Or run this curl commandwhich should reply with {"status":"ok"}:
curl http://127.0.0.1:9001/health/ready{"status":"ok"}docker logs ory-hydra-example--hydra[...]time="2017-06-29T21:26:34Z" level=info msg="Setting up http server on :4444"Ory Hydra CLI
When running Ory Hydra outside of the Ory Network, use the hydra CLI tointeract with the Ory Hydra server. You can download the Ory Hydra CLI fromGitHub. Please make sure that theversion of the CLI matches the version of the Ory Hydra server!
For simplicity, we will use the Ory Hydra CLI included in the Docker container.To see the available commands, run the help command.
docker run --rm -it oryd/hydra:v2.0.1 \ helpThis command produces an overview of the CLI as follows:
Run and manage Ory HydraUsage: hydra [command]Available Commands: completion Generate the autocompletion script for the specified shell create Create resources delete Delete resources get Get resources help Help about any command import Import resources introspect Introspect resources janitor This command cleans up stale database rows. list List resources migrate Various migration helpers perform Perform OAuth 2.0 Flows revoke Revoke resources serve Parent command for starting public and administrative HTTP/2 APIs update Update resources version Display this binary's version, build time and git hash of this buildFlags: -h, --help help for hydraUse "hydra [command] --help" for more information about a command.Performing the OAuth2 Client Credentials Flow
To create an OAuth2 Client with a locally running Ory Hydra server, we use thesame command arguments as with the Ory CLI with two modifications:
- ory --project $project_id+ docker run --rm -it --network hydraguide oryd/hydra:v2.0.1 \ create oauth2-client \+ --endpoint http://ory-hydra-example--hydra:4445 \ --grant-type client_credentialsInstead of using the Ory CLI, we use the Ory Hydra CLI and add the --endpointflag to specify the administrative API endpoint of the Ory Hydra server
docker run --rm -it --network hydraguide oryd/hydra:v2.0.1 \ create oauth2-client \ --endpoint http://ory-hydra-example--hydra:4445 \ --grant-type client_credentialswhich outputs the OAuth2 Client details:
CLIENT ID 33b32af0-4722-4508-980f-2027dfc49c16CLIENT SECRET eh-d_leHfsmxWNkgAJwF8Z3UT5GRANT TYPES client_credentialsRESPONSE TYPES codeSCOPE offline_access offline openidAUDIENCEREDIRECT URISPerforming the client credentials grant using the Ory Hydra CLI
docker run --rm -it --network hydraguide oryd/hydra:v2.0.1 \ perform client-credentials \ --client-id {INSERT-CLIENT-ID_HERE} \ --client-secret "{INSERT-CLIENT-SECRET-HERE}" \ --endpoint http://ory-hydra-example--hydra:4444to receive an OAuth2 access token:
ACCESS TOKEN ory_at__s-lJ8wMAhiJHGk8NU1cP_qSRjjY8MJH9rwBWXXbcnU.Jw7wT-VTm4T2eFgubqiaTPNeWiJV9-2-gd0vjz82H_AREFRESH TOKEN <empty>ID TOKEN <empty>EXPIRY 2022-10-28 11:56:14 +0000 UTCAnd finally validating it using hydra introspect token
docker run --rm -it --network hydraguide oryd/hydra:v2.0.1 \ introspect token \ --endpoint http://ory-hydra-example--hydra:4445 \ "{INSERT-ACCESS-TOKEN-HERE}"to receive the OAuth2 access token metadata:
ACTIVE trueSUBJECT 33b32af0-4722-4508-980f-2027dfc49c16CLIENT ID 33b32af0-4722-4508-980f-2027dfc49c16SCOPEEXPIRY 2022-10-28 11:56:14 +0000 UTCTOKEN USE access_tokenPerform OAuth2 Authorization Code Flow on Docker
When running Ory Hydra in Docker, you need a running OAuth2 Login and Consentapp. In this example, we will use the demo application fromGithub and run it in Docker:
docker run -d \ --name ory-hydra-example--consent \ -p 9020:3000 \ --network hydraguide \ -e HYDRA_ADMIN_URL=http://ory-hydra-example--hydra:4445 \ -e NODE_TLS_REJECT_UNAUTHORIZED=0 \ oryd/hydra-login-consent-node:v1.10.2Once the container is running, we perform the same flow as on the Ory Network,but using the Ory Hydra CLI:
docker run --rm -it --network hydraguide oryd/hydra:v2.0.1 \ create oauth2-client \ --endpoint http://ory-hydra-example--hydra:4445 \ --name "Authorize Code with OpenID Connect Demo" \ --grant-type authorization_code,refresh_token \ --response-type code \ --redirect-uri http://127.0.0.1:4446/callbackcode_client_id="{set to client id from output}"code_client_secret="{set to client secret from output}"docker run --rm -it --network hydraguide oryd/hydra:v2.0.1 \ perform authorization-code \ --endpoint http://ory-hydra-example--hydra:4445 \ --client-id $code_client_id \ --client-secret $code_client_secretYour browser will show a simple screen asking you to authorize the application.If you remember the CircleCI example from the beginning of the article, thiswould be the "Log In with GitHub" button.
After clicking "Authorize application" you will be asked to log in. The screenyou are seeing is provided by the exemplary User Login & Consent app("ory-hydra-example--consent"). The contents of these screens are under yourcontrol and you can use any technology you like to implement them. As alreadynoted, the exemplary application has just one user. In a real-world scenario,you could probably sign up for a new account or use a social login provider(e.g. Google, Facebook) to sign in.
The consent screen is the second important screen shown by the User Login &Consent app. It asks the end user for permission to authorize. If a user hasprivacy concerns, they could not grant access to personal details. Since theexample only requests very basic permissions, all can be granted withoutconcern.
Once logged in and authorized, Ory Hydra will issue an access token, an refreshrefresh (if scope offline was granted), and an ID token (if scope openid wasgranted).
Continue using your OAuth2 Server
That's it, this article shows how to have a running OAuth2 server with anexemplary identity provider, and perform an OAuth2 request. Using the token fromthe last request and passing it to hydra token introspect as explained inearlier OAuth2 Client Credentials flow provides further details about the tokenproperties.
Ory Hydra is an Apache 2.0 licensed Go server solving OAuth2, OpenID Connect andAPI security in general. It secures millions of requests per day and has avibrant and welcoming online community.
Check out Ory Hydra at Github and the other OryAPI Security products.
