Mobile SSO Configuration

Overview

Mobile Single Sign-On (SSO) allows users to log in to your branded mobile app through your Identity Provider (IdP) using OpenID Connect (OIDC). You configure Mobile SSO with the Mobile SSO API, and your authentication web service validates each login.

NOTE: Mobile SSO applies to the mobile app only. To set up SSO for App Manager, refer to the SAML SSO Configuration Guide.

How It Works

When a user logs in with Mobile SSO, the following happens:

The user selects the SSO button on the mobile app's login screen.
The mobile app opens your IdP's sign-in page, and the user authenticates.
Your IdP redirects the user back to the mobile app with an ID token and an access token.
The mobile app sends a login request with those tokens to your authentication web service.
Your authentication web service validates the ID token, identifies the user, and returns the user's account information.

IMPORTANT: The Platform does not validate the ID token. Your authentication web service is responsible for all validation and user lookup described in Step 3. Skipping any of these checks can introduce security vulnerabilities.

Setting Up Mobile SSO

Prerequisite: Create an OIDC Application in Your IdP

Before configuring Mobile SSO, create an OIDC application in your IdP and set its redirect URI to:

https://fleetmobile.app/[environment]/oauth

Finding your environment: The environment is a unique Eleos value. To find it, navigate to App Manager and copy the environment query parameter from the URL.
Multi-tenant apps: Use your app's primary environment. If you do not know which environment is primary, contact support@eleostech.com.

After you create the application, your IdP provides values such as client_id, client_secret, authorization_endpoint, token_endpoint, and issuer_url. You send these values to the Platform in Step 1.

IMPORTANT: The redirect URI changed in mobile app version 1.64. If you set up Mobile SSO on version 1.63 or earlier, update the redirect URI in your IdP so users can log in with SSO on version 1.64 and later. The new redirect URI also works on version 1.63 and earlier, so updating it does not affect users on older versions.

Step 1: Send Your IdP Values to the Platform

Start in your test environment. Send a PUT request to /sso_configs/{code} to create or update your Mobile SSO configuration.
For every required and optional field, including data types, default values, and validation rules, refer to the API documentation.

At minimum, provide:

client_id and client_secret
authorization_endpoint, token_endpoint, and issuer_url
label, the text displayed on the SSO button in the mobile app

IMPORTANT: OIDC discovery is not supported. You must provide both authorization_endpoint and token_endpoint explicitly.

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 Production

After you test the configuration in your test environment, send the same PUT /sso_configs/{code} request to your production environment with enabled set to true. The SSO button then appears on the mobile app's login screen.

SSO button on the mobile app login screen

Each configuration appears as its own button. If you have multiple providers, set the sort property on each configuration with PUT /sso_configs/{code} to control the button order.

To hide the SSO button, send PUT /sso_configs/{code} with enabled set to false.

Step 3: Handle OIDC Login Requests

After a user authenticates with your IdP, the mobile app sends a login request to your authentication web service. The request includes:

oidc_id_token and oidc_access_token, the tokens issued by your IdP
oidc_refresh_token and oidc_expires_in, if your IdP provides them
oidc_nonce, a value for verifying the ID token
oidc_idp_code, the code of the SSO configuration used

NOTE: For every field and its format, refer to the Login 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 must:

Validate the ID token.
- Confirm it is signed by your IdP with the correct public key
- Confirm the issuer (iss) matches the issuer_url from Step 1
- Confirm the audience (aud) matches the client_id from Step 1
- Confirm the token has not expired
- Confirm the nonce claim in the decoded ID token matches the oidc_nonce value in the request
Return the user's account information.
Identify the user account from the sub value in the decoded ID token, then return your usual login response so the mobile app can complete the login.

SSO Configuration Requirements

Each Mobile SSO configuration must meet these requirements:

The authorization_endpoint and token_endpoint are provided explicitly
The redirect URI https://fleetmobile.app/[environment]/oauth is registered with your IdP
The scopes include at least openid and email
The ID token returned by your IdP contains a valid email claim

Session Behavior

As with username and password logins, your authentication web service manages session length. After a user logs in, later verification requests include the api_token you returned. To end a session and require the user to authenticate with your IdP again, return a 401.

For details, see the Forcing a User to Log Out tutorial.

Device Requirements

Mobile SSO requires mobile app version 1.61 or later. It relies on operating system support for web authentication, which requires Google Chrome as the default browser on Android and Safari on iOS. These browsers keep identity sessions active on the device, so users who are already signed in to your IdP can log in with one tap.

Sign Out Behavior

Mobile SSO handles sign-in only. It does not sign users out of your IdP.

IMPORTANT: On shared devices, users must log out of both your IdP and the mobile app before handing off the device. Otherwise, the previous user's IdP session stays active, and the next user who selects the SSO button is logged in as the previous user.