A Developer’s Guide to OAuth and OIDC Endpoints

Have you ever used "Login with Google" and wondered how it works behind the scenes? The magic lies in a powerful component called an authorization server, which uses specialized web addresses known as endpoints. Each endpoint has a specific role in ensuring secure authentication and authorization for applications. In this blog post, we’ll take a guided tour of these endpoints, exploring their functions and how they work together to keep your applications secure.

What Are Endpoints?

Endpoints are URLs on an authorization server that applications interact with to perform authentication and authorization tasks. They are the backbone of protocols like OAuth 2.0 and OpenID Connect (OIDC), enabling secure communication between applications, users, and servers.

OAuth 2.0: The Foundation

OAuth 2.0 is a framework for granting access to resources securely. It defines two mandatory endpoints and one optional endpoint:

1. /authorize Endpoint

   • Purpose: Handles the user-facing part of the process, where users log in and grant consent.
   • How it works: When an application needs access to a user’s data, it redirects the user to the /authorize endpoint. The URL includes query parameters like:
     • response_type=code: Indicates the authorization code flow.
     • client_id: Identifies the application.
     • redirect_uri: A pre-registered URL where the user is sent after consent.
     • scope: Lists permissions (e.g., profile, email) the application requests.
     • state: A unique string to prevent cross-site request forgery (CSRF) attacks.
   • The user sees a login and consent screen. If they approve, the server redirects them back to the redirect_uri with a temporary authorization code and the state value.

2. /token Endpoint

   • Purpose: Exchanges credentials (e.g., authorization code) for access tokens.
   • How it works: This is a secure back-channel communication between the application server and the authorization server. For the authorization code flow, the application sends:
     • The authorization code.
     • The client_id and client_secret to authenticate itself.
   • In return, the server issues an access token, and potentially an ID token and refresh token, depending on the requested scopes.
   • Other grant types:
     • Client Credentials Grant: Used for machine-to-machine communication, where the application authenticates with its own credentials to get an access token.
     • Refresh Token Grant: Uses a refresh token to obtain a new access token when the current one expires.

3. /introspect Endpoint (Optional)

   • Purpose: Allows a resource server to validate a token and check if it’s still active.
   • Use case: Useful for verifying token status without relying on local validation.

OpenID Connect: Enhancing OAuth 2.0 for Authentication

OpenID Connect (OIDC) builds on OAuth 2.0 to provide user authentication. It introduces additional endpoints to enhance security and functionality:

1. /well-known/jwks.json Endpoint

   • Purpose: Hosts the public keys needed to verify the digital signatures of ID tokens.
   • Why it matters: Ensures tokens haven’t been tampered with, maintaining trust in the authentication process.

2. /well-known/openid-configuration Endpoint

   • Purpose: Acts as a discovery document, providing metadata about the authorization server.
   • What it includes:
     • The server’s issuer (official name or URL).
     • URLs for other endpoints (e.g., /authorize, /token).
     • Supported scopes, response types, and claims (e.g., email, name).
     • Cryptographic algorithms used for signing tokens.
   • Benefit: Allows applications to dynamically configure themselves to work with any OIDC-compliant server, making integration seamless.

3. /userinfo Endpoint (Optional)

   • Purpose: Retrieves user profile information (e.g., name, email) using an access token.
   • How it works: The application presents an access token to this endpoint, which returns data based on the granted scopes:
     • sub: A unique user identifier (always included).
     • email and email_verified: Available if the email scope was granted.
     • name, given_name, family_name, picture: Available if the profile scope was granted.
   • Why it’s useful: Provides standardized access to user data without exposing the full user database, adhering to the principle of least privilege.

4. /logout Endpoint

   • Purpose: Provides a standardized way to log a user out of their session.
   • Use case: Ensures secure session termination across applications.

How It All Works Together

Let’s walk through a typical flow, such as the authorization code flow, to see how these endpoints interact:

1. Discovery: The application visits the /well-known/openid-configuration endpoint to retrieve the server’s metadata, including the URLs for the /authorize and /token endpoints.

2. Authorization: The application redirects the user to the /authorize endpoint with the necessary query parameters. The user logs in, consents to the requested permissions, and receives a temporary authorization code.

3. Token Exchange: The application server sends the authorization code to the /token endpoint, along with its credentials. The server responds with an access token, ID token, and possibly a refresh token.

4. Accessing User Data: With the access token, the application can query the /userinfo endpoint to retrieve user profile details, such as their email or name.

5. Token Validation: The application uses the /well-known/jwks.json endpoint to verify the ID token’s signature, ensuring its authenticity.

6. Logout: When the user logs out, the application calls the /logout endpoint to terminate the session.

Why These Endpoints Matter

Together, these endpoints form a robust and flexible system for secure authentication and authorization. They enable applications to:

• Access resources securely while respecting user privacy.
• Dynamically discover server capabilities, reducing manual configuration.
• Verify token authenticity and retrieve user data efficiently.

Understanding the role of each endpoint is crucial for building secure, compliant applications in today’s interconnected world. Whether you’re implementing “Login with Google” or creating a custom authentication system, these endpoints are the building blocks of modern identity management.

Conclusion

This guided tour through OAuth 2.0 and OpenID Connect endpoints has shown how authorization servers power secure authentication and authorization. From the user-facing /authorize endpoint to the secure /token endpoint, the discovery-focused /well-known/openid-configuration, and the data-rich /userinfo endpoint, each plays a vital role in keeping applications secure and user-friendly.