When an organisation implements Single Sign-On (SSO) using Google Workspace as the primary Identity Provider (IdP), administrators gain centralised control over user authentication. However, when an employee attempts to log into a third-party application like Salesforce, Slack, or Zendesk via SAML and the authentication fails, diagnosing the root cause can be incredibly frustrating. The user often simply sees a generic “Error 403: app_not_configured_for_user” message.
To properly diagnose and resolve complex SAML assertion errors, IT administrators must move beyond the basic graphical Admin Console and utilise the Google Workspace Admin Directory API to query the raw login event logs. This programmatic approach allows administrators to inspect the exact SAML attributes, certificates, and entity IDs being passed during the authentication handshake.
Understanding the SAML Authentication Flow
Before querying the API, it is essential to understand where the failure is occurring. A SAML authentication failure typically falls into one of three categories: a Service Provider (SP) configuration mismatch, a missing user attribute assignment, or an expired X.509 certificate. When a user clicks the login button, the SP sends an authentication request to Google. Google verifies the user, generates a SAML assertion containing the user’s identity data, signs it with a certificate, and sends it back to the SP. If any detail in this assertion fails to match the SP’s expectations, the login is rejected.
Accessing the Admin Reports API
To extract the detailed failure logs, administrators must query the Reports API, which is a component of the broader Google Workspace Admin SDK. You can interact with this API using the Google APIs Explorer, a custom Python script, or tools like Postman authenticated via OAuth 2.0.
You must authenticate using an admin account with the https://www.googleapis.com/auth/admin.reports.audit.readonly scope. The specific endpoint you need to query is the SAML application login audit log:
GET https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/samlFiltering and Interpreting the Audit Logs
By default, the API will return a massive JSON response containing every successful and failed SAML login event across your entire Google Workspace tenant. To isolate the failure, you must filter the results using query parameters based on the affected user’s email address and the specific timeframe of the error.
GET https://admin.googleapis.com/admin/reports/v1/activity/users/[email protected]/applications/saml?eventName=login_failureThe API will return a JSON object containing an events array. Examine the parameters array within the failed event. You will find critical diagnostic information that the graphical interface hides.
- failure_type: This field explicitly states why Google rejected the request before even sending the assertion. A common value is
app_not_configured, indicating the user’s Organizational Unit (OU) does not have the SAML app turned ON. - issuer: This is the Entity ID provided by the Service Provider. If this string does not perfectly match the Entity ID configured in your Google Workspace SAML settings (including trailing slashes and HTTP vs HTTPS protocols), the authentication will fail.
- acs_url: The Assertion Consumer Service URL. If the SP attempts to send the user to a different callback URL than what you have explicitly whitelisted in Google Workspace, the login is aborted for security reasons.
Resolving Attribute Mapping Failures
If the API indicates a successful login event on Google’s side, but the user is still rejected by the third-party application, the issue is almost certainly an attribute mapping failure. Google is sending a valid SAML assertion, but the SP cannot interpret the data. For example, the SP might require a custom attribute named DepartmentRole, but Google is sending the default Department attribute.
In these cases, you must return to the Google Workspace Admin Console, open the specific SAML app configuration, navigate to the SAML attribute mapping section, and ensure the Google Directory attributes are precisely mapped to the exact variable names demanded by the third-party Service Provider documentation.