Mobile SSO Configuration

  • Updated on Aug 4, 2025
  • Published on Aug 1, 2025
  • 4 minute(s) read
Prev Next

Mobile Single Sign-On (SSO) allows users to authenticate into your branded mobile app using your Identity Provider (IdP) via OpenID Connect (OIDC). This guide outlines how to set up Mobile SSO using the /sso_configs API, explains the expected configuration, and describes behavior and troubleshooting steps.

Set Up SSO

Prerequisite: Create an OIDC Application in Your IdP

Before configuring Mobile SSO in Eleos, you'll need to create a new OpenID Connect (OIDC) application in your Identity Provider (IdP). During this process:

  • Set the redirect URI to: https://fleetmobile.app/oauth. This is where your IdP will redirect users after a successful login.

  • After creating the application, your IdP may provide values such as client_id, client_secret, authorization_endpoint, token_endpoint and issuer_url. You’ll enter these values into Eleos via API.

Step 1: Provide IdP values to Eleos via API

Use the PUT /sso_configs/{code} endpoint to create or update your Mobile SSO configuration. This defines how your app connects to your IdP using OIDC.

At minimum, you’ll need to provide your IdP’s client_id, client_secret, and relevant endpoints (e.g., authorization_endpoint, token_endpoint, and issuer_url), along with a label for the button text shown in the app.

Discovery is not supported. You must explicitly provide both authorization_endpoint and token_endpoint.

For a complete list of required and optional fields — including data types, default values, and validation rules — refer to the API documentation.

Example: 

curl -i --location --request PUT 'https://platform.driveaxleapp.com/api/v1/sso_configs/AZURE' \
--header 'Authorization: {{Eleos API Key}}' \
--header 'Content-Type: application/json' \
--data '{
        "archived": false,
        "authorization_endpoint": "https://login.microsoftonline.com/9b7f4c22-3e3d-4e6d-910f-123456789abc/oauth2/v2.0/authorize",
        "button_color": "cae1fd",
        "button_color_dark": "f74a8f",
        "client_id": "a23cd456-78e9-41f2-934b-abcdef123456",
        "client_secret": "PzJ9B~a1kL2vNdsX4WgTrhSeZ8MPqLo89-XYz123",
        "enabled": true,
        "issuer_url": "https://login.microsoftonline.com/9b7f4c22-3e3d-4e6d-910f-123456789abc/v2.0",
        "label": "Login with SSO",
        "scopes": [
            "email",
            "openid"
        ],
        "title": "Azure SSO",
        "token_endpoint": "https://login.microsoftonline.com/9b7f4c22-3e3d-4e6d-910f-123456789abc/oauth2/v2.0/token"
    }'

Step 2: Enable SSO in your environment

Once a configuration is set up and tested in your sandbox environment, copy the configuration to your production environment with the enabled field set to true. This will display the SSO button in your mobile app’s login screen.

Each configuration appears as a distinct button in the app. Use the PUT /api/v1/sso_configs endpoint to set a sort order if you have multiple providers.

If you need to hide or disable SSO for any reason, use the same endpoint to set enabled to false, which will hide the SSO button from that environment.

Step 3: Handle OIDC Authentication Requests

After a driver successfully authenticates with your IdP, the mobile app will send a login request to your authentication web service.

This request includes:

  • An ID token and access token from the IdP

  • A nonce for verifying the request

  • Metadata about the session and SSO config used

For the full list of fields and their formats, refer to the API documentation.

Example:

curl --request POST https://your-auth-endpoint.example.com/authenticate \
-H "Eleos-Platform-Key: abcdef1234567890" \
-H "Eleos-Mobile-App-Platform: android" \
-H "Eleos-Mobile-App-Version: 1.61" \
-H "x-forwarded-for: 203.0.113.17" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "is_team_driver_login=false" \
--data-urlencode "oidc_idp_code=AZURE" \
--data-urlencode "oidc_nonce=s8TrnO3U4kQxtZmuD7wXs" \
--data-urlencode "oidc_id_token=eyJhbGciOi...UzI1NiIsInR5cCI6IkpXVCJ9..." \
--data-urlencode "oidc_access_token=eyJz93a...k4laUWw" \
--data-urlencode "oidc_expires_in=3600" \
--data-urlencode "oidc_refresh_token=0.ARcAq2...eAzQ"

Your authentication web service is responsible for:

  1. Validating the ID token

    • Ensure it is signed by your IdP using the correct public key

    • Check that the issuer (iss) matches the issuer_url configured in Step 1

    • Check the token’s audience (aud) matches your client_id configured in Step 1

    • Confirm the token has not expired

    • Verify the nonce matches the one Eleos provided (oidc_nonce)

  2. Returning user account information to Eleos
     If the ID token is valid and you identify a user account (returned in the sub value of the decoded oidc_id_token value), respond with your usual user payload so Eleos can complete the login.

Note: Eleos does not validate the ID token. Your system is responsible for all validation and user lookup listed above. If your web service or identity service does not perform all the steps listed above, you may introduce security risks or vulnerabilities.

SSO Configuration Requirements

Each Mobile SSO configuration must meet these criteria:

  • The authorization and token endpoints must be explicitly provided.

  • The redirect URI must be registered with your IdP and must be https://fleetmobile.app/oauth.

  • The scopes must include at least openid and email.

  • The ID token returned by the IdP must contain a valid email address claim (email).

Session Behavior

Like with username and password authentication, session lengths are managed by your authentication web service. Once a driver has been authenticated, subsequent verify requests will contain the driver’s api_token. Your authentication web service can then return a 401 to log the user out and require them to reauthenticate with the IdP.

Device Requirements

Mobile SSO is available on Eleos Platform apps version 1.61 and greater. Mobile SSO depends on OS-level support for web authentication. This requires Google Chrome to be the default browser on Android and Safari on iOS, as these browsers handle identity sessions for their respective platforms. This allows the mobile app to pick up active user sessions on the device and allows the user to bypass entering credentials, giving them a true one-tap login.

Sign Out Behavior

Mobile SSO only supports single sign on and does not include any sign out functionality. For fleets operating a slip-seating model, drivers will have to manually log out of the IdP and Eleos before returning the tablet. If not, when the next driver begins using the tablet, the last driver’s IdP session will remain on the device and the new driver will automatically be logged in as the old driver when tapping the SSO button in your mobile app.

Team Driving

Mobile SSO does not support team driving.