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.

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

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.

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

Start by setting up your LoginRadius Admin Console to manage user identities, authentication settings, and integrations for your applications.

1. Navigate to Applications > Apps in the LoginRadius Admin Console.
2. Add a New App:
   • Click Add Apps.
   • Enter a unique App Name.
   • Select OAuth 2.0 under the Protocol.
   • Choose the App Type based on your use case:
     • Native App
     • Machine 2 Machine App
     • Single Page App
     • Web App
   • Click CREATE to generate a new app configuration.

Once the basic configuration is complete, proceed to fill out the additional details to configure OAuth settings for your app. Use the glossary below to accurately fill out the required fields:

• App Type: Choose the application type that best suits your use case (e.g., Native App, or Web App).

• Client ID and Client Secret:

  • Client ID: A unique identifier for your app.
  • Client Secret: A securely hashed authentication key (visible only once; save it).

• Grant Type: Select one or more grant types for acquiring tokens:

  • Authorization Code
  • Implicit
  • Password Credentials
  • Refresh Token
  • Device Code (additional fields will appear for this flow):
    • Verification URL
    • Verification Complete URL
    • Device Code Expiration (seconds)
    • Polling Interval (seconds)
    • User Code Character Set
    • User Code Mask

• Token Endpoint Auth Method: Specify how the Authorization Server authenticates the token endpoint.

• Login Redirect URL (Optional): Whitelist callback URLs for redirection.

• CORS Origin: For apps where the Client Secret cannot remain confidential (e.g., single-page apps), whitelist JavaScript web origins here.

• Token Expiration (Seconds): Set the lifetime of access tokens(Default 3600 Seconds).

• Refresh Token TTL (Seconds): Specify the duration for which refresh tokens remain valid(Default 86400 Seconds).

• Force Reauthentication: Enable this option to require users to reauthenticate during authorization requests.

• Scopes for Management API (Optional): Define the scopes permitted for Management API operations tied to the Client ID and Secret.

Once all fields are completed, click Save to finalize the configuration.

Step 2: Enable Connections

You can enable or disable specific connections for the app from the list of global social/custom identity providers (IDPs).

Following these steps will allow you to successfully configure OAuth 2.0 within LoginRadius, providing secure and seamless authentication for your application.

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.

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.

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.

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 Deployment > Apps > Web Apps in the Admin Console and whitelist the redirect URL that is being used for OAuth.