Enterprise SSO Integration

Note: This guide covers Enterprise SSO integration where Loopwise acts as an OAuth client connecting to your organization's identity provider. For building third-party applications that access Loopwise data, see the OAuth Quickstart.

Introduction

This guide aims to help enterprise developers understand how to integrate the Loopwise platform with your OAuth provider system. This integration not only enhances security and data privacy but also provides a seamless user experience allowing users to access Loopwise's services using existing enterprise credentials.

Benefits

1. Enhanced Security: Leverages existing authentication mechanisms to reduce potential security risks.
2. Increased Efficiency: Users can log in using their company credentials without needing to create new accounts, simplifying the login process.
3. Unified User Experience: The integrated system offers a consistent user interface, improving user satisfaction.

Implementation Steps

Below is a detailed sequence diagram showing the OAuth integration flow:

To ensure a successful integration of Loopwise with your OAuth system, it is imperative that the following API endpoints and steps are fully implemented:

1. Authorization Endpoint: This endpoint is crucial for the authorization and authentication of users. It initiates the OAuth flow by redirecting users for login and consent, thereby granting Loopwise the necessary permissions to access user data under defined scopes.

2. Token Endpoint: After the authorization is complete, your system should redirect the user back to the specified redirect_uri with an authorization code. Loopwise will then use this code to request an access token from your token endpoint.

3. User Information Endpoint: This endpoint is essential for retrieving basic information about the user once they have been authenticated. Loopwise utilizes this data to personalize and enhance the user experience on our platform.

IP Allowlisting

To enhance security, we recommend setting up IP allowlisting for your OAuth integration. This ensures that only requests from trusted IP addresses are accepted.

Loopwise IP Address

Please add the following IP address to your allowlist:

52.194.91.27

Please carefully assess your system's capability to support these endpoints and steps. If there are any uncertainties regarding the specifications or implementation details, do not hesitate to reach out to Loopwise for further clarification or assistance. We are here to support you through every step of the integration process to ensure a seamless and efficient setup.

Authorization Endpoint

The Authorization Endpoint is primarily responsible for handling login requests from Loopwise users. When users click the "Login" button within the Loopwise system, they are redirected to your enterprise's login page. This step is the initial phase of the OAuth authentication process, aimed at obtaining user consent and performing authentication.

Process

1. User Interaction: The user selects the login option on the Loopwise interface.
2. Redirection: Loopwise redirects the user's browser to your enterprise's Authorization Endpoint URL. This URL typically includes necessary query parameters such as response_type, client_id, redirect_uri, and scope.
3. User Login: Users enter their credentials (e.g., username and password) on your enterprise login page.
4. Login Confirmation and Authorization Code Issuance: Once the credentials are verified as valid, your enterprise's OAuth service automatically redirects the user back to the redirect_uri provided by Loopwise, along with an authorization code (token).

https://yourdomain.com/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=https://loopwise.com/callback&scope=profile

Key Parameters

• response_type: Specifies the type of authorization requested. Here, code indicates that the authorization code flow is being used.
• client_id: The application identifier assigned to Loopwise by your enterprise OAuth system during the registration process.
• redirect_uri: The URI to which the user is redirected after successful authorization, typically carrying the authorization code.
• scope: Specifies the extent of access that Loopwise is requesting to the user's information. The scope can include details like profile and email, which define the specific data Loopwise can access from the user's account.
• state: A unique randomly generated value used to mitigate CSRF attacks.

Token Exchange

The Token Exchange process is a critical step in the OAuth 2.0 flow, occurring after the user has granted permission to your application. This process involves exchanging the authorization code received from the Authorization Endpoint for an access token, which is then used to make authenticated requests to the Loopwise API on behalf of the user.

Functionality

After receiving the authorization code, your application must make a secure server-to-server request to exchange this code for an access token.

Purpose

The Token Exchange process serves to:

1. Verify the authorization code's validity
2. Ensure the request is coming from the same client that initiated the authorization flow
3. Provide a secure method to obtain access tokens

API Example

POST https://yourdomain.com/oauth/token HTTP/1.1

&code={authorization_code}
&redirect_uri={REDIRECT_URI}

Key Parameters

• code: The authorization code received from the Authorization Endpoint.
• redirect_uri: Must match the redirect URI used in the initial authorization request.

Sample Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Fields Explained

• access_token: The token used to authenticate requests to the Loopwise API.
• token_type: Indicates how the access token should be used, typically "Bearer".
• expires_in: The lifetime of the access token in seconds.
• scope: The scopes granted to this access token.

User Information Endpoint

The User Information Endpoint is utilized post-authentication to retrieve essential user information, which can then be used by Loopwise to personalize the user experience or manage user-specific data. This endpoint is crucial for accessing profile details that the user has consented to share under the authorized scopes during the OAuth process.

Functionality

After a successful authentication and authorization process, where the user grants Loopwise permission to access their profile data, Loopwise can request user information from this endpoint using the access token obtained. This ensures that only necessary data is accessed, respecting user privacy and adhering to minimal data access principles.

Purpose

The User Information Endpoint is utilized post-authentication to retrieve essential user information, which can then be used by Loopwise to personalize the user experience or manage user-specific data. This endpoint is crucial for accessing profile details that the user has consented to share under the authorized scopes during the OAuth process.

API Example

GET https://yourdomain.com/oauth/userinfo
Authorization: Bearer access_token

Key Parameters

Authorization: This is a mandatory header where the Bearer access_token must be included. The access token is used to authenticate the request, ensuring that the request for user information is authorized.

Sample Response

The response from the User Information Endpoint typically includes JSON data containing the user's details as specified by the scopes authorized. Below is an example of what this might look like:

{
  "uid": "1234567890",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "picture": "http://example.com/jane.jpg"
}

Fields Explained

• uid: A unique identifier for the user, which is often used by the client to manage user sessions and database records.
• name: The full name of the user.
• email: The user's email address, which can be used for communication or identification purposes.
• picture: A URL to an image file representing the user's profile picture.

This setup allows Loopwise to effectively use the provided user data to enhance user interaction and provide a more tailored educational experience. By securing the endpoint and ensuring data is only available after proper authentication and authorization, both Loopwise and your enterprise can maintain high standards of data privacy and security.