Integration Guide

0 mins to read

Nov 21, 2022

Introduction

MyGeotab (version 5.7.2101 and newer) supports Single Sign-On (SSO) user authentication via the SAML 2.0 specification with both Identity Provider (IdP)-initiated and Service Provider (SP)-initiated protocol bindings, including SAML authentication for Geotab Drive.

This document describes Geotab requirements and procedures for creating and configuring an IdP application, preparing a MyGeotab database to accept authentication from that IdP, configuring MyGeotab users for SAML authentication, as well as frequently asked questions and troubleshooting guidance. MyGeotab supports user authentication using SAML 2.0 only, as described in this document. OpenID Connect (OIDC), Secure Web Authentication, OAuth 2.0, Artifact Resolution, Artifact Binding, or other methods are not supported.

Because SAML is a published standard, this document assumes that authentication integration will work with any IdP that offers SAML as an SSO method. Where possible, any settings referenced will include a generic descriptive name and the corresponding SAML element name as it would appear in a SAML assertion. Settings where a particular IdP vendor uses a sufficiently different term are also noted.

Prerequisites and Assumptions

Successful SAML 2.0 integrations require the following:

  • Administrative access to an existing IdP with the following capabilities:
    • Setting up applications using a SAML 2.0 sign-on method;
    • Managing user assignments to that application; and
    • Accessing any relevant sign-on policy restrictions possibly implemented within the provider configuration.
  • Administrative access to a Geotab (MyGeotab, MyPreview, etc.) company database with the capability to access and modify both users and settings under Administration > System > System Settings (specifically including Certificates).
  • Ability to login and act as a user in IdP and MyGeotab environments suitable for testing the integration.
  • Awareness of the following Geotab-specific requirements or limitations:
    • The MyGeotab “User (Email):” value must match an IdP user identifier exactly.
    • The IdP user identifier must be sent as the content of a Geotab-specific attribute/claim to be created for the application called “Email”. This SAML attribute will not exist by default.
    • No SSO method other than SAML is supported.
    • Geotab user management processes will be unchanged - there is no current support for SCIM or other automated user provisioning or creation.
    • If an IdP application is created for connection to Geotab that allows sending of First Name and Last Name user attributes, those names must match the user First Name and Last Name in the MyGeotab database. Sending these name attributes is not recommended.
    • The steps provided in this document include values and procedures known to work in at least four commonly used IdPs. Other variations may be possible, but are as yet unknown.

IdP Application Configuration

Creating the Application Integration

Within the IdP user interface, do the following to initiate the creation of a new application via its Create App Integration/New Application or similar function:

  1. Select SAML or SAML 2.0 as the SSO method and/or property. All other options are invalid.
  2. Specify general IdP settings for name/logo/icon/visibility as desired.
  3. Specify common required SAML settings as follows:
    1. Application Consumer Service (ACS) URL: May also be presented as Single Sign On URL, Reply URL, Destination URL, Recipient URL, or multiples of these. For any of these options, enter https://my.geotab.com/apiv1/authenticateSaml?redirect=true as the URL (if using the default ACS). This is displayed in assertions within the “Response Destination” and “Recipient” elements. See the FAQ Application Consumer Service (ACS) URL topic for additional possibilities for this value, including those related to federations other than https://my.geotab.com.
    2. Audience restriction, audience URI, Identifier, Entity ID: Recommend https://my.geotab.com/. In Azure this item is “Identifier (Entity ID). For some IdPs this value must exactly match the value sent by Geotab as “Issuer” in a SAML Request for SP-initiated login. Some examples: Geotab production: https://my.geotab.com/ Geotab preview: https://mypreview.geotab.com/ Geotab government: https://gov.geotab.com/
    3. Default RelayState: No value is required or recommended. This is the common default within IdPs.
    4. Name ID format: Either “unspecified” or “EmailAddress”.
    5. Application username (“Subject” SAML element): The IdP user email is the preferred option.

Configuring Advanced SAML Settings for the IdP

Advanced SAML settings typically function correctly with their default IdP settings. Two items of note are as follows:

  1. Sign the response and assertion: Ensure the SAML assertion is signed to function properly with MyGeotab.
  2. Specify the SAML Issuer ID (saml2:Issuer) value: Cloud-based IdPs such as Okta and Azure use defaults consisting of generic URLs ending with generated alphanumeric entity IDs, which are used to identify (name) a certificate uploaded to MyGeotab. Specifying the value for the “saml2:Issuer” assertion element to something descriptive can be helpful in situations where multiple certificates are in use, or to link an installed certificate back to a specific IdP application instance. For example, a default Issuer might be “http://app.idpvendor.com/exkpa1k1izkCKeDS85d6”, which could instead be set to “TestCertForLocationLimitedSignOn”.

* NOTE: Specifying the saml2:Issuer value is completely optional for user function specific needs, and no additional recommendation applies.

Configuring Additional IdP Attributes

Configure additional IdP attributes as follows:

  1. Required attributes: Add an attribute and/or claim including the following:
    1. Name: Email
    2. Name format: Unspecified (no specific format required)
    3. Value/User attribute: User email (user.email/user.mail as a selectable IdP option for the user or user source attribute)
  2. Optional Attributes: If managing access to multiple Geotab databases, especially where an IdP username may exist in more than one database, add the following attribute and/or claim to define which database the user should be authenticated for (and thus logged into):
    1. Name: databaseRestriction
    2. Name format: unspecified (no specific format required)
    3. Value/User attribute: Name of the Geotab database user login should be restricted to (as free text entry)

Finalizing the Integration

After the attributes and settings above are completed you should be at the point where the application integration can be saved/completed. If prompted for publication/feedback, answers indicating that you are adding an internal application for internal use will complete the process. Ensure the following:

  1. Complete user assignments: The application should be assigned to the users and/or groups allowed to use the application, including at least one user available for testing the new application. All users assigned the application should also exist in the MyGeotab target database, with usernames and/or emails identical to the IdP user identifier selected to send in the Email attribute.
  2. Note the SP setup properties: The IdP interface to the new Geotab application includes an option to access or display SP setup instructions and/or properties. These should be noted for entry into the MyGeotab UI, as use of IdP metadata exchange is not currently supported. Required properties are as follows:
    1. Identity Provider Issuer: Enter the value in the MyGeotab UI as “Certificate Issuer”, which corresponds to the SAML Issuer ID value described above.

* NOTE: This is called “Azure AD Identifier” in Microsoft Azure.

  1. IdP Single Sign On URL: The destination endpoint used for SP-initiated authentication. Enter the value in the MyGeotab UI as “Login URL”.
  2. X.509 certificate: Signing certificate to be uploaded to Geotab as a file. The certificate should be downloaded from the IdP to prepare for upload. It should have a .cer extension (rename to .cer if downloaded as .cert). If an encoding option is offered (Azure), then both base64 and Raw should work.

* NOTE: Some customers have offered conflicting reports that one worked when the other did not.

MyGeotab Certificate Installation

Do the following as an administrator user in the MyGeotab database:

  1. In the main menu, navigate to Administration > System > System Settings.
  2. Click the User Account Policy tab and enable Allow SAML login.
  3. Click the Certificates tab and click Add new certificate.
  4. Upload your properly formatted .cer file. You will see a message indicating “The certificate key file <name of your file>.cer has been accepted” message.

* NOTE: This indicates a successful file load only — file contents are not validated.

  1. In the Certificate issuer field, enter the Identity Provider Issuer value as IdP Issuer, which indicates the signing options for response and assertion.
  2. In the Login URL field, enter the IdP Single Sign On URL, which is the destination endpoint used for SP-initiated authentication.
  3. In the Logout URL field, enter the URL where the user should be redirected after logging out of MyGeotab. An IdP provided logout URL may exist, but this field is optional and can be any valid URL. If left blank, the MyGeotab login dialog is displayed on logout.
  4. Click Save on the Certificates page.
  5. Click Save on the System Settings page.

MyGeotab User Management

Configuring SAML Authentication for a New or Existing User

MyGeotab accounts need to be configured for SAML authentication in order for this integration to function.

NOTE: The MyGeotab Certificate file must be successfully uploaded prior to completing this procedure.

Do the following to configure a MyGeotab user for SAML authentication:

  1. When adding or editing a User in MyGeotab, select SAML as the Authentication type.
  2. The interface will update to remove Password options and replace them with a Certificate Issuer drop-down list selector. Note the following:
    1. If only one certificate exists, it will be the selected default.
    2. If multiple certificates exist, ensure that you select the correct certificate for the application the user has been assigned at the IdP.
    3. Multiple MyGeotab Certificates can exist in the database, but only one can be assigned to a given User.
  3. Saving the user will complete the change. If the user already existed with Basic authentication, the password no longer exists, nor does the option to log in with a password. It is possible to change the user back to Basic authentication, but they will need to be re-initialized for password usage via an administrative password reset or the ‘force password change on next login’ option.

Because of the risk of temporarily losing access to a user account during the initial testing of authentication integration, it is highly recommended that a test user is created in both MyGeotab and the IdP to confirm the function before rolling-out to active users. Likewise, a Basic authentication administrator user should always exist as a backup in the event of any catastrophic failure (e.g. loss of access to IdP function, certificate invalidation, accidental deletion of IdP application, etc.).

Additional Options for Enabling SAML Authentication for Users

Modification of users is possible via the Geotab API interface as documented in the MyGeotab SDK. Specific procedures are beyond the scope of this document, with the exception of noting the existence of the following entities and entity properties:

  • The Certificate entity is the object stored when a certificate is saved in the UI. If examined via the result of a Get() method, its id property is the value used to associate the certificate to a user.
  • The User entity has the following properties specific to SAML authentication:
    • userAuthenticationType is an existing string property that can be changed from ‘BasicAuthentication’ to ‘SAML’
    • issuerCertificate is an object with the following properties:
      • Id: set to the id of a Certificate entity in the database.
      • isRoot: set to ‘false’
  • A sample Geotab SDK Runner API call to change a user from Basic to SAML via configuration of userAuthenticationType and issuerCertificate is as follows:

    api.multiCall([["Get",{

    "typeName": "User",

    search: {name: "May282021User@nomail.com"} /*replace with name of actual user*/

    }],],

    function(results)

    { var SAMLUser = results[0] && results[0][0] ? results[0][0] : null;

    if (SAMLUser){

    SAMLUser.userAuthenticationType = "SAML";

    SAMLUser.issuerCertificate = {

    id : "a6mATltOsVUGge8CjPyoPfQ"}; /*use ID of actual certificate*/

    api.call("Set",{

    typeName : "User",

    entity : SAMLUser}),

    console.log("User \"" + SAMLUser.name + "\" given certificate \"" + SAMLUser.issuerCertificate.id +"\"");}

    else {

    console.log("User is not found!");

    }},

    console.error);

    There is also a Bulk Edit Add-in tool that should allow manipulation of multiple users in a database, including the option to set SAML Authentication with an installed certificate. See How do I access the new Bulk Edit Add-In? On the Geotab Community for more information about installing the Add-in for your environment.

    Integration Testing

    Once you have the Integration Setup completed, you should now test the SAML 2.0 authentication process.

    SAML Authentication on MyGeotab (IdP-Initiated)

    Do the following:

    1. Click the application link while logged into IdP application portal as a user. The user account must be:
      • Assigned access to the Geotab application created in the IdP; and
      • Configured in MyGeotab for SAML authentication and assigned a certificate corresponding to the application created in the IdP.

Result: Browser is logged onto MyGeotab as the specified user.

SAML Authentication on MyGeotab (SP-Initiated)

Do the following:

  1. Navigate to https://my.geotab.com where login dialog should be displayed)
  2. Enter the User (Email) for a Geotab user that has a valid Login URL value associated with the installed certificate.
  3. Click Next.

Result: The browser window opens a new window/tab with the IdP login URL, where a successful login results in opening the MyGeotab UI.

SAML Authentication on Geotab Drive

Do the following:

  1. Open Geotab Drive and enter a Username configured to meet all requirements above for both IdP and SP initiated logins.
  2. Click Next

Result: The browser window opens a new window/tab with the IdP login URL, where a successful login results in opening the Geotab Drive UI.

Troubleshooting

! IMPORTANT: For all other authentication issues, contact Geotab support (or other relevant contact) indicating the problem encountered, the IdP used, the Geotab database, the number of users impacted, an example impacted user, and a copy of a SAML assertion captured in the network activity of the browser when the issue occured. A copy of the certificate file used to install in the Geotab database would also be helpful.

Geotab Rejected Authentication

Issue: User cannot be authenticated.

Symptom: JSON response at URL address https://my.geotab.com/apiv1/authenticateSaml?redirect=true indicates "Incorrect login credentials" with name "InvalidUserException" and code ‘-32000’.

Cause: Something about the provided SAML assertion does not match the expected combination of attributes required to complete user authentication.

Troubleshooting: All requirements in this document can be reviewed for completion in the relevant UIs. If the problem is not readily identified, install a browser SAML tracer add-in, or use the developer console to examine the sent SAML assertion. It should be identifiable as SAML from a header attribute.

Elements to examine in the assertion include the following:

  • saml2:Issuer: Should be identical to Certificate issuer value as entered for the certificate in MyGeotab. If misspelled in Geotab then an installed certificate doesn’t exist with the correct name.
  • saml2:AttributeStatement: Should contain saml2:Attribute Name="Email", with the attribute value set to the Username of the Geotab user being logged in. If incorrect in any aspect then the user does not exist.
  • saml2:Attribute Name="databaseRestriction": The specified value (if used) must match the database name that user is being logged into. If this value is misspelled in the IdP application then the database does not exist.

It is also possible for issues with certificates or certificate trust relationships to exist. These would typically occur in situations where a previously correctly functioning integration suddenly failed for all SAML users. If no other cause is identifiable then it will be valid to see if replacing the certificate resolves the issue, or confirm its function with another SP if available,

IdP Rejected Authentication

Issue: User cannot be authenticated.

Symptom: Possible symptoms are IdP specific.

Cause: Unknown unless indicated by IdP, but most immediate suspects would be no assignment of application to user, or user violation of IdP specific sign-on policies limiting access by location, time of day, platform, etc. May also occur with incorrect expectations around parent-child relationships among integrated directory groups used for application assignment. Geotab can not cause these failures — no SAML assertion would be sent for authentication when these occur.

Troubleshooting: Log on to the IdP portal as the impacted user directly and try to launch the application — see if the error generated provides guidance.

Authenticated User is Prompted for Re-Authentication

Issue: SAML authenticated user is prompted for re-authentication when using “Open Link in New Tab” functionality within the MyGeotab UI, or when clicking an Add-in link opening a new tab or window to the Geotab UI.

Cause: SAML authenticated sessions are managed differently than Basic (password) sessions. New instances of the MyGeotab UI do not acquire stored tokens for SAML authenticated sessions, necessitating re-authentication via the Login URL.

Troubleshooting: Entering the username of the SAML authenticated user should complete the process immediately if the user has a current valid login at the IdP.

FAQ

Q: Which browser extension/addon is able to capture SAML exchanges across multiple tabs and windows, and provide both SAML decode assertion and Summary views?

A: The following browser extensions are recommended:

Q: Is Geotab an SP for any other SSO methods other than SAML 2.0?

A: No. Geotab currently only supports SP HTTP-Redirect with IdP HTTP-POST binding interactions.

Q: Does Geotab support outbound SAML integration, whereby Geotab is the IdP?

A: No. Geotab understands the importance of supporting this type of configuration and is looking into becoming an IdP for an industry standard SSO implementation. OAuth will likely be the initial focus.

Q: Does Geotab support SP initiated SAML login whereby users can be redirected from the MyGeotab landing page to the login page of the IdP?

A: Yes. This functionality is available in MyGeotab version 2101 and up.

Q: Does Geotab implement any restrictions on user login via SAML, such as user location, platform, time of day, directory group membership, requirement for Multi-Factor Authentication, etc.?

A: Geotab does not implement such restrictions directly, and will accept any otherwise valid SAML assertion sent by the IdP. Any sign-on policy implemented at the IdP (or at the directory via the IdP, or by another module integrated with the IdP) that will prevent that assertion from being sent will also prevent a login to MyGeotab from succeeding.

Q: Is it possible to edit a MyGeotab Certificate once it has been uploaded to the database?

A: Yes. This functionality is available for MyGeotab version 2101 and up. Opening an installed certificate in the UI now exposes a “Change certificate” option that allows a new certificate file to be uploaded to allow the contained key to be extracted and associated with the existing certificate entity.

Q: Can both Basic and SAML Authentication be assigned to a MyGeotab account?

A: No. A User can only be assigned to a single authentication type. In some cases, it may make sense to create two MyGeotab User accounts for a user.

Q: In which circumstances would we not want to use the default Application Consumer Service (ACS) URL?

A: There are two specific circumstances where you would not want to use https://my.geotab.com/apiv1/authenticateSaml?redirect=true as the ACS URL:

  • If you are using a server on another Geotab federation differentiated by a URL path not serviced by https://my.geotab.com, then the URL should be modified to point to that federation. For example, if you have a test database in the mypreview.geotab.com environment, you’d want to replace my.geotab.com with mypreview.geotab.com, mypreview2.geotab.com, etc. as correct for your situation.
  • If you are developing or using an application integration that wants to receive a Geotab authentication LoginResult without a redirect response to the browser — for example, to have a service account session with access to the Geotab API — leave off the ?redirect=true part of the URL. Specifically:
    • The Assertion must be sent to MyGeotab in a standard SAML HTTP POST binding form to the following ACS: https://<Geotab federation URL>/apiv1/authenticateSaml.
    • The HTTP response will have a status code of 200 and the body will be a LoginResult.
    • Functionality of an IdP application using this mechanism should be confirmed in a standard web browser prior to any other usage, and only web browser functionality can be supported by Geotab. Usage in any other application will require the application to function as a SAML user-agent (as a browser would), with specific consideration for:
      1. Modification of the content of a SAML Response assertion issued by an IdP prior to submission via HTTP POST will not work and will not be supported.
      2. The Response assertion must comply with the requirements defined for SAML Core in https://www.oasis-open.org/committees/download.php/56777/sstc-saml-core-errata-2.0-wd-07-diff.pdf. Specifically including (but not limited to) section 2.5 Conditions, and the NotBefore and NotOnOrAfter condition.
      3. The Response assertion must comply with the requirements defined for the SAML HTTP POST binding (i.e. the Response side of an HTTP-Redirect/HTTP-POST Request/Response binding) in section 3.5 of https://www.oasis-open.org/committees/download.php/56780/sstc-saml-bindings-errata-2.0-wd-06-diff.pdf. Specifically including (but not limited to) sections 3.5.4 Message Encoding and 3.5.5.2 Security Considerations.
  • Q: Is it possible to add a certificate via the Geotab SDK API?

    A: Yes. What should be sent as the “key” property of an Add() method for a Certificate entity is actually a string containing the entire contents of an X.509 certificate file converted from ASCII to hexadecimal. The sent “key” is subsequently converted on receipt to the value stored as “key” for the entity created in the database. The value sent is the correct format if it begins with “2D2D2D2D2D424547494E204345525449” and ends with “43455254494649434154452D2D2D2D2DA” (i.e. “-----BEGIN CERTI” and “CERTIFICATE-----”). The following sample code would be executed in the SDK Runner to add a certificate to a database. For actual use, replace all example property values with those applicable for your IdP application and certificate:

    api.call("Add", {

    typeName : "Certificate",

    entity : {

    "issuer": "IdPIssuerIDForGeotab",

    "logInUrl": "https://loginurl.myidp.com",

    "logOffUrl": "https://logoff.tosomeurl.com",

    "key": "[X.509 certificate here]",

    "id": null

    }

    }, function () {

    console.log("Added certificate ");

    }, console.error);

    It is also possible to update a Certificate — if expiring, for example — to a new key property via a multi-call to Get() a certificate with a Set() on the entity to replace the key as submitted in the Add() example. This example would accomplish a change to Issuer or key for the certificate installed in the example above, but as provided would execute and change nothing, as it is the same certificate).

    api.multiCall([["Get",{

    "typeName": "Certificate",

    search: {issuer: "IdPIssuerIDForGeotab"} /*replace with actual issuer*/

    }],],

    function(results)

    { var SAMLCert = results[0] && results[0][0] ? results[0][0] : null;

    if (SAMLCert){

    SAMLCert.issuer = "IdPIssuerIDForGeotab"; /*Change here if Issuer ID also changing*/

    SAMLCert.key = "[X.509 certificate here]"

    api.call("Set",{

    typeName : "Certificate",

    entity : SAMLCert}),

    console.log("Certificate\"" + SAMLCert.issuer + "\" given key \"" + SAMLCert.key +"\"");}

    else {

    console.log("Certificate is not found!");

    }},

    console.error);

    Geotab Assisted Integration

    In the event that Geotab configuration troubleshooting may be required to assist with a SAML integration, the list of items below will ensure efficient progress on the effort:

    Personnel

    As many as three roles can be filled by a single person, but each role should be represented on the call(s). If implementation is urgent then it is vital that all of the following roles are available from start to end, including via email and for any related calls.

    1. IdP Administrator: Administrator of the IdP with access to the Geotab application and the user directory of the IdP.
    2. Geotab Database Administrator: An administrator of the Geotab customer database with ability to modify system settings and create/modify users.
    3. Test User: A relevant test user configured in both the IdP and the Geotab database. This user should have access to browser features such as the developer console, and ability to add browser extensions.

Configuration

Useful information relevant to the configuration:

  1. IdP provider: Azure, Okta, OneLogin, Google Workspace, SiteMinder, PingFederate, etc.
  2. Customer database(s): URL when signed in (i.e. https://my###.geotab.com/<databasename>).
  3. Setup Instructions and/or Metadata: IdP service provider setup instructions or IdP metadata including:
    1. EntityDescriptor: "Identity Provider Issuer","Azure AD Identifier", "Entity ID", "SAML Issuer ID", etc. This will be "Issuer" in the MyGeotab UI.
    2. SingleSignOnService: "Identity Provider Single Sign-On URL", "Login URL", "SSO URL", etc. Specifically for HTTP-Redirect binding if different from HTTP-POST). This is the value for Login URL in the MyGeotab UI.
    3. Copy of X509 certificate to be uploaded to Geotab.
  4. Items specific to the application as configured in IdP:
    1. A link allowing the user to access the application directly from a location outside IdP. May be called "User access URL", "App Embed Link", etc. Used when confirming IdP-initiated vs SP-Initiated functionality.
    2. Application Consumer Service (ACS) URL as entered. Normally https://my.geotab.com/apiv1/authenticateSaml?redirect=true.
    3. Entity ID/Audience Restriction URL as entered. Normally https://my.geotab.com/.
    4. Construction of Attribute/Assertion named "Email", with name format and value as user property (user.email, user.login, user.userprincipalname, etc.)
  5. Items specific to the test user:
    1. Geotab username identified as "User (email):" in the MyGeotab UI.
    2. "Authentication type:" verified as SAML.
    3. "Certificate issuer:" verified as match for EntityDescriptor from 3a above.
    4. Primary user identifier in IdP ("Username", "User Principal Name", "Login", etc.). Identity entered for IdP login.
    5. Value of user property as selected to send as "Email" attribute for 4a above.
    6. Confirmation of user assignment to the application within IdP.
    7. Test user should have a SAML Tracer extension/add-on installed on the browser to be used for testing.

NOTE: Links are available in the FAQ.

scroll-up