loading
Preparing LoginRadius developer resources
Mission: Help enterprises accelerate digital transformation with our fully-managed Customer IAM technology.
Skip to main content

OAuth 2.0

OAuth 2.0 is an open-standard authorization protocol that enables secure, delegated access to server resources on behalf of resource owners. This framework eliminates the need for users to share credentials with third-party applications, making it a cornerstone for modern authentication systems.

With OAuth 2.0, resource owners can authorize third-party clients to access their server resources by issuing an access token, ensuring a secure and seamless experience.

Note: LoginRadius also supports the Client Credentials grant, a core OAuth 2.0 flow used in machine-to-machine (M2M) authorization scenarios where no end-user is involved. This enables secure, automated access between trusted applications or services. For details, refer to our M2M Authorization using Client Credentials guide.

Real-World Use Cases of OAuth 2.0

Discover how OAuth 2.0 empowers developers to build more secure and user-friendly applications. Use cases include:

  • Social Logins: Simplify user onboarding with third-party authentication.
  • Secure API Access: Protect sensitive data with token-based access.
  • Federated Identity: Enable seamless cross-platform user authentication.

Case studies highlight practical examples of how integrating OAuth 2.0 enhances application functionality and user trust.

OAuth Roles

OAuth 2.0 defines four key roles that work together to facilitate secure authorization and resource access:

  1. Resource Owner
    The resource owner is the user or entity that grants an application permission to access their account. This access is restricted to the scope defined by the authorization, such as read-only or write permissions.
  2. Client (Service Provider)
    The client is the application requesting access to the resource owner’s account. It requires explicit authorization from the resource owner, which the API must validate before access is granted.
  3. Resource Server (Identity Provider, LoginRadius)
    The resource server hosts the protected resources and processes authenticated requests. After the client obtains a valid access token, the resource server ensures secure access to the requested data.
  4. Authorization Server (Identity Provider, LoginRadius)
    The authorization server authenticates the resource owner, and issues access tokens to the client upon successful authorization. This server acts as the gatekeeper for secure interactions between the client and the resource server.

OAuth 2.0 Integration with LoginRadius

The LoginRadius Identity Platform supports the standard OAuth 2.0 specifications, allowing seamless integration of OAuth clients. By leveraging LoginRadius, you can enable Single Sign-On (SSO) and simplify authentication for your application’s customers without requiring them to create separate accounts.

Getting Started with OAuth 2.0 on LoginRadius

This guide provides a step-by-step walkthrough for configuring an OAuth 2.0 application within the LoginRadius Identity Platform. Before proceeding, it's important to understand the key roles and components involved in the OAuth 2.0 flow.

Configure the Application

  1. Navigate to Applications in the Console.
  2. Click Add Application.
  3. Enter a unique Application Name and click Create Application.

Your app is now created and you will be taken to the app's configuration page.

OAuth 2.0 Flows Supported by LoginRadius

OAuth 2.0 defines several flows (grant types) supported by LoginRadius to obtain an access token. Each flow is tailored for specific application types and use cases:

  1. Authorization Code Flow (Explicit): Ideal for server-side applications requiring secure handling of secrets.
  2. OAuth 2.0 PKCE Flow: Designed for mobile and single-page applications (SPAs) to enhance security by preventing code interception.
  3. Implicit Flow: A legacy flow primarily for SPAs, though it’s less commonly used today due to security concerns.
  4. Resource Owner Password Credential Flow: The client can obtain access tokens directly by collecting user credentials, typically for trusted applications.
  5. Device Code Flow: Suitable for devices with limited input capabilities, such as TVs or IoT devices.

Audience-Restricted Tokens (Resource Indicators)

In addition to the flows above, LoginRadius supports the RFC 8707 resource parameter on both /authorize and /token. This binds each issued access token to a specific API audience (the JWT aud claim), so a token issued for one API cannot be replayed against another — particularly useful for multi-API platforms, machine-to-machine (Client Credentials) integrations, and multi-tenant deployments. See Resource Indicators for details.

Refreshing Access Token in OAuth 2.0

Once you have obtained an access token using the OAuth 2.0 flow, you can use the Refresh Access Token API to renew the access token when it expires. The refresh token provided during the token issuance process will be used to request a new access token without requiring the user to authenticate again.

Request Body Parameters for Refresh Token

To refresh the access token, make a POST request with the following parameters in the body:

  • client_id (required): The OAuth Client ID.
  • grant_type (required): This should be set to refresh_token.
  • refresh_token (required): The refresh token you received during the initial token exchange (e.g. when calling the 'Access Token by OAuth 2.0' or 'Access Token by Account Password' API).

API Endpoint

Make a POST request to the Refresh Access Token API:

POST https://{siteurl}/api/oauth/{OAuthAppName}/token

Response Example

On success, the API will return a new access token, the type of the token, the expiration time, and the refresh token.

{
  "access_token": "Loginradius Access Token",
  "token_type": "Bearer",
  "expires_in": "3600",
  "refresh_token": "New Refresh Token"
}
  • access_token: The new access token.
  • token_type: Type of the token, usually Bearer.
  • expires_in: The expiration time of the new access token in seconds.
  • refresh_token: The new refresh token.

Troubleshooting

Here are some common errors and their resolutions:

1. Error: “The code has expired” in Authorization Code Flow

  • Cause: The authorization code has expired. The expiration time for the authorization code is 50 seconds.
  • Solution: Ensure the authorization code is used within the 50-second window. If it expires, request a new code.

2. Error: “Invalid_request” in Authorization Endpoint

  • Cause: This error occurs when the OAuth client ID (or OAuth client secret) is incorrect.
  • Solution: Double-check your client_id and client_secret values. Ensure the secret is valid and correctly configured in your application.

3. Error: “Unauthorized_client” - “The client_secret is not valid”

  • Cause: The client's secret is invalid. Additionally, caching of the application configuration can delay updates after a new API secret is generated.
  • Solution: If you’ve generated a new API secret, wait at least 15 minutes for the app configuration cache to expire before attempting the API call again.

4. Error: “The host is not whitelisted” while calling the OAuth Authorization URL

  • Cause: The redirect URL used in the OAuth authorization request is not whitelisted in the LoginRadius Admin Console.
  • Solution: Go to Tenant Settings > General > Configured Domains in the Admin Console and whitelist the redirect URL that is being used for OAuth.