Understanding Login Traces

Login traces are a powerful tool that Edlink provides to help troubleshoot SSO issues. They provide a detailed, step-by-step account of the SSO login process, including all the events that occurred during the login attempt. This guide will help you understand how to read and interpret these traces.

Where to Find Login Traces

Login traces can be found in the Edlink Dashboard by clicking on any integration and looking for the Troubleshooting section of the left hand sidebar (towards the bottom). Under this section, click the Logins tab. This tab provides a list of all recent login attempts, along with their status - click any one of the attempts to view the full trace details.

What Login Requests Are Traced

Virtually all SSO requests that are initiated by a user or an application are traced. The only situations in which a login request is not traced are:

• If Edlink was unable to determine the client_id of the application that initiated the login request (or if the client_id is not associated with a developer application).
• If the login request took place before tracing was implemented (roughly May 2025).

In situations where Edlink was able to resolve the client_id, the login request will be traced, even if the request did not complete to a point where we were able to resolve the corresponding integration. What this means for you is that you cannot currently see the full trace in the Edlink UI, but we may be able to provide you with the full trace if you contact support with the associated request ID (or a rough timestamp). The request ID is visible on Edlink SSO error pages.

SSO Trace Events and Details Payload

The following table shows all of the possible trace events. For a more details description of each (and its payload), please scroll further down.

Initiate By Provider

{
    "details": {
        "provider": "clever", // or "google", "classlink"
        "query": {
            "param1": "value1",
            "param2": "value2"
            // ... other query parameters
        }
    }
}

This event signifies the beginning of an SSO authentication flow that was initiated directly by an external identity provider (IdP). This typically occurs in IdP-initiated SSO scenarios where a user clicks an application link from the IdP's portal (e.g., Clever Portal, ClassLink LaunchPad). The provider field indicates which IdP started the flow, and the query object contains any URL query parameters that were part of the initial request from the IdP.

This can also occur for Google SSO requests, if you opt to add a "Sign In With Google" button that initiates an Edlink SSO request without a specific integration ID.

Initiate By Integration

{
    "details": {
        "query": {
            "param1": "value1",
            "param2": "value2"
            // ... other query parameters
        }
    }
}

This event is logged when an SSO flow is started by an internal system or a specific integration rather than an end-user directly interacting with a generic login button or an external IdP. The query object captures any parameters passed along with this initiation request, which might be used to control or customize the SSO flow for that particular integration.

Initiate By Quick Launch URL

{
    "details": {
        "query": {
            "param1": "value1",
            "param2": "value2"
            // ... other query parameters
        }
    }
}

This event indicates that the SSO flow was triggered by a user accessing a "Quick Launch" URL. These URLs are often designed to provide a direct path into an application, potentially with pre-selected roles or contexts embedded within the URL's query parameters. The query object contains all parameters from the Quick Launch URL.

Initiate By Instant Login

{
    "details": {
        "login_id": "some_unique_login_identifier",
        "query": {
            "param1": "value1"
            // ... other query parameters
        }
    }
}

This event marks the initiation of an SSO flow through an "Instant Login" link or mechanism. Instant Login links are typically user-specific or context-specific URLs that allow for an expedited sign-in process. The login_id provides a unique identifier for this specific login attempt or link, and query contains any additional parameters.

Initiate By LTI 1.1 Launch

{
    "details": {
        "query": {
            "lti_message_type": "basic-lti-launch-request",
            "user_id": "lti_user_id",
            "roles": "Learner",
            "oauth_consumer_key": "consumer_key"
            // ... other LTI 1.1 launch parameters
        }
    }
}

This event signifies that an SSO flow was initiated as part of an LTI (Learning Tools Interoperability) 1.1 launch request. This typically happens when a user clicks a link in a Learning Management System (LMS) to access an external LTI tool. The query object contains the LTI launch parameters sent by the LMS, such as user ID, roles, and resource information.

Initiate By LTI 1.3 Launch

{
    "details": {
        "integration_id": "integration_identifier_for_lti13",
        "application_id": "application_identifier",
        "clever_application_id": "clever_specific_app_id",
        "query": {
            "iss": "https://lms.example.com",
            "login_hint": "user_login_hint",
            "target_link_uri": "https://tool.example.com/launch"
            // ... other OIDC/LTI 1.3 launch parameters
        }
    }
}

This event marks the beginning of an SSO flow triggered by an LTI 1.3 launch. LTI 1.3 uses OAuth 2.0 and OpenID Connect for a more secure and standardized launch process compared to LTI 1.1. The details payload includes identifiers for the integration_id (the specific LTI integration configuration), application_id (the target application), potentially a clever_application_id if applicable, and the query parameters associated with the OIDC authentication request from the LTI platform.

Resolved Application

{
    "details": {
        "application_id": "target_application_identifier"
    }
}

This event occurs during an SSO flow when the system has successfully identified the target application to which the user is attempting to gain access. The application_id uniquely identifies this application within the SSO system. This step is crucial for directing the user appropriately and applying application-specific policies.

Resolved Integration

{
    "details": {
        "integration_id": "specific_integration_identifier"
    }
}

This event is logged when a specific integration or configuration involved in the SSO process has been determined. This could refer to an LTI integration, a custom SAML/OIDC connection, or another defined method of connection. The integration_id helps in pinpointing the exact configuration being used for the current SSO transaction.

Resolved Person

{
    "details": {
        "person_id": "unique_person_identifier"
    }
}

This event signifies a key moment in the SSO flow where the user attempting to sign in has been successfully identified and resolved to a unique person_id within the system. This typically happens after the user authenticates with an IdP and their identity is mapped to an internal user record.

Resolved Class

{
    "details": {
        "class_id": "unique_class_identifier"
    }
}

This event is logged when a specific class or course context has been identified as relevant to the current SSO flow. This is common in educational technology scenarios, particularly with LTI launches where the user is accessing a tool within the context of a specific class. The class_id identifies this class.

Resolved Source

{
    "details": {
        "source_id": "identity_provider_source_identifier"
    }
}

This event indicates that the source identity provider (IdP) or originating system for the SSO attempt has been successfully identified. The source_id could refer to a specific district's SAML configuration, a particular OAuth provider, or another defined authentication source. This helps in understanding where the authentication request originated.

Person Shared With Developer

{
    "details": {
        "person_id": "unique_person_identifier_shared"
    }
}

This event is logged after a user's identity has been resolved (ResolvedPerson) and their information (or specific attributes, based on consent and configuration) has been authorized for sharing and subsequently shared with the target developer application. The person_id indicates which user's data was shared.

Class Shared With Developer

{
    "details": {
        "class_id": "unique_class_identifier_shared"
    }
}

This event occurs when information about a specific class, previously resolved in the SSO flow (ResolvedClass), has been authorized for sharing and then shared with the developer application. This is particularly relevant for LTI tools that require class roster information or context. The class_id specifies which class's data was shared.

Upstream Redirect

{
    "details": {
        "url": "https://identityprovider.example.com/auth?param=value",
        "query": {
            "param": "value"
            // ... other query parameters sent to upstream provider
        }
    }
}

This event indicates that the SSO system is redirecting the user's browser to an external, upstream identity provider (e.g., Google, Clever, a district's SAML IdP) for authentication. The url field contains the full redirection URL, and the query object breaks down any parameters being sent as part of that redirection, such as SAMLRequest or OIDC authentication request parameters.

Downstream Initiation

{
    "details": {
        "url": "https://service.example.com/initiate_sso_leg",
        "query": {
            "param1": "value1"
            // ... query parameters for the downstream initiation
        }
    }
}

This event marks the beginning of a subsequent, or "downstream," phase of the SSO process. This might occur after initial authentication with a primary IdP, where the flow then needs to initiate another step, perhaps involving an intermediate service or directly towards the target application with new parameters. The url and query specify the destination and parameters for this downstream initiation.

Downstream Redirect

{
    "details": {
        "url": "https://application.example.com/callback?token=xyz",
        "query": {
            "token": "xyz"
            // ... other query parameters sent to the downstream application
        }
    }
}

This event is logged when the user's browser is being redirected to the target application or another downstream service after successful authentication or processing by the SSO system. The url is the destination URL for the application, often a callback or assertion consumer service URL, and query includes parameters like authorization codes, tokens, or SAML assertions being sent to the application.

Error Redirect

{
    "details": {
        "redirect_uri": "https://application.example.com/sso_error",
        "state": "application_provided_state_value",
        "code": "error_code_string"
    }
}

This event occurs when the SSO flow encounters a recoverable error or a situation that requires redirecting the user back to the relying party (application) with error information. The redirect_uri is the URL provided by the application to receive error notifications, state is an optional value passed by the application to maintain context, and code is an error code indicating the nature of the error.

Login Required

This event indicates that the current SSO attempt has determined that the user must authenticate. This typically happens if no active session is found for the user, if an existing session has expired, or if the requested resource requires a higher level of assurance than the current session provides. There is no specific payload for this event beyond the standard trace step information.

Issued Token

{
    "details": {
        "type": "access_token", // or "id_token"
        "refresh_id": "unique_refresh_token_identifier",
        "issued_id": "unique_issued_token_identifier"
    }
}

This event logs the successful issuance of an authentication token (e.g., an OAuth 2.0 access token or an OpenID Connect ID token) to the client application. The type field specifies the kind of token issued. refresh_id and issued_id are internal identifiers that can be used to track the lifecycle or revocation of these tokens.

Scheduled Partial Sync

{
    "details": {
        "class_external_id": "external_identifier_for_class",
        "context_memberships_url": "https://lms.example.com/api/lti/courses/course_id/names_and_roles"
    }
}

This event typically occurs in an LTI context, specifically related to LTI Advantage services like Names and Role Provisioning Services (NRPS). It indicates that a task has been scheduled to perform a partial data synchronization, such as fetching or updating the membership (roster) for a specific class. The class_external_id identifies the class, and context_memberships_url is the endpoint from which to fetch the roster.

Deep Linking

{
    "details": {
        "login_id": "login_identifier_for_deep_linking_session",
        "client_id": "application_client_identifier",
        "redirect_uri": "https://lms.example.com/deep_link_return",
        "return_url": "https://lms.example.com/deep_link_return", // Often same as redirect_uri in LTI
        "data": {
            // Opaque data passed by the platform to the tool during the deep linking request
            "custom_param": "value"
        }
    }
}

This event signifies that an LTI Deep Linking workflow is currently active. In this flow, a user (often an instructor) in an LTI platform (like an LMS) launches an external tool to select specific content or activities (e.g., a chapter from an e-textbook, a specific quiz) to be embedded back into the platform. The details payload contains information relevant to this process, including identifiers, URIs for returning the selected content, and any opaque data passed from the platform.

Class Selection Redirect

{
    "details": {
        "url": "https://sso.example.com/select_class?session_id=xyz",
        "query": {
            "session_id": "xyz"
            // ... other query parameters for the class selection page
        },
        "classes": [
            { "id": "class_id_1", "name": "Algebra 101" },
            { "id": "class_id_2", "name": "History 202" }
            // ... other available classes
        ]
    }
}

This event is logged when the SSO flow cannot determine a single, unambiguous class context for the user and needs to redirect the user to a page where they can select the intended class. This might happen if a user is associated with multiple classes and the initial launch didn't specify one. The url and query point to the class selection page, and the classes array provides the list of classes the user can choose from.

Returned From Upstream Provider

This event marks the point in the SSO flow where the user's browser has been redirected back to the SSO system from an external, upstream identity provider (e.g., Google, Clever, SAML IdP) after an authentication attempt at that provider. This event typically precedes the processing of the authentication response (e.g., SAML assertion, OIDC token) from the IdP. There is no specific payload for this event beyond the standard trace step information.

Authorization Code Exchange Attempt

{
    "details": {
        "request_id": "unique_identifier_for_this_exchange_attempt"
    }
}

This event logs an attempt by the system's backend to exchange an OAuth 2.0 authorization code for tokens (typically an access token, ID token, and/or refresh token). This is a standard step in the OAuth 2.0 authorization code grant flow. The request_id can be used to correlate logs related to this specific exchange attempt.

Authorization Code Exchanged

{
    "details": {
        "refresh_id": "unique_refresh_token_identifier_from_exchange",
        "issued_id": "unique_access_or_id_token_identifier_from_exchange"
    }
}

This event confirms the successful completion of an authorization code exchange. It signifies that the previously obtained authorization code was valid and has been successfully exchanged with the authorization server for the requested tokens. The refresh_id and issued_id are internal identifiers for the newly obtained tokens.

Error

{
    "details": {
        "code": "ERROR_CODE_EXAMPLE",
        "message": "A descriptive error message.",
        "request_id": "optional_request_identifier_for_correlation"
    }
}

This is a generic event indicating that an unrecoverable error or an notable issue occurred at some point during the SSO process that doesn't fit into more specific error events like ErrorRedirect. The code provides a machine-readable error identifier, message offers a human-readable explanation of the error, and request_id (if present) can help correlate this error with other logs or system events.