Package org.opencabstandard.provider

Class IdentityContract

  • public final class IdentityContract
extends java.lang.Object
    Defines the contract for the OpenCab Identity Content provider. An OpenCab Identity provider app should define an Android ContentProvider class that follows this contract or should subclass the AbstractIdentityProvider class and implement the abstract methods.

    Single-sign on for one driver

    An example sequence where an Identity consumer detects a login and performs single-sign on might be the following:

    sequenceDiagram participant A as Identity Consumer participant B as Identity Provider Note over B: Driver A logs in B->>A: Broadcast: ACTION_DRIVER_LOGIN Note over A: App enumerates available Identity
    providers and selects one. Note over A: App queries provider for list of active drivers. A->>B: Call: METHOD_GET_ACTIVE_DRIVERS, version: "0.2" B->>A: Return: [Driver{username="A"}] Note over A: App currently has no logged in user,
    and notices that it now needs to have
    user A logged in to match
    the identity provider state. Note over A: The consumer makes a call to the Identity
    provider and signals that it understands
    version 0.3 of the contract and that it wants session
    credentials for all active drivers. This is a
    separate call from METHOD_GET_ACTIVE_DRIVERS
    since it may be expensive for a provider to fetch
    or generate credentials, and it should only be
    called when needed, not simply to monitor
    the list of active drivers. A->>B: Call: METHOD_GET_LOGIN_CREDENTIALS, version: "0.3" Note over B: The provider app sees the "0.3" version and knows the calling
    application supports team drivers via OpenCab.
    If the version is "0.2" or lower, the provider knows the
    calling application does not support team drivers via OpenCab. B->>A: Return:
    KEY_VERSION="0.3"
    KEY_ALL_LOGIN_CREDENTIALS=[
    IdentityContract.DriverSession{
    username="A",
    loginCredentials=LoginCredentials{
    authority="example"
    provider="com.eleostech.example"
    token="kf40m1fpl…d28zckhuf6"
    }
    }
    ]

    Single sign-on for a second (team) driver

    sequenceDiagram participant B as Identity Consumer participant A as Identity Provider Note over A: Driver B taps the option to log in and enters their
    credentials for the Identity provider app. A->>B: Broadcast: IdentityContract.ACTION_DRIVER_LOGIN Note over B: App queries provider for list of active drivers. B->>A: Call
    IdentityContract.METHOD_GET_ACTIVE_DRIVERS("0.2") A->>B: Return
    [Driver{username="A"}, Driver{username="B"}] Note over B: App currently has only driver A logged in, so it knows that it
    now needs to have user B logged in as well to match the
    identity provider state. Note over B: The app makes a call to the Identity provider and signals
    that it understands version 0.3 of the contract and that it
    wants session credentials for all active drivers. This is a
    separate call from METHOD_GET_ACTIVE_DRIVERS
    since it may be expensive for a provider to fetch or generate
    credentials, and it should only be called when needed, not
    simply to monitor the list of active drivers. B->>A: Call
    IdentityContract.METHOD_GET_LOGIN_CREDENTIALS("0.3") A->>B: Return
    KEY_VERSION="0.3"
    KEY_ALL_LOGIN_CREDENTIALS=[
    IdentityContract.DriverSession{
    username="A",
    loginCredentials=LoginCredentials{
    authority="example"
    provider="com.eleostech.example"
    token="kf40m1fpl…d28zckhuf6"
    }
    },
    IdentityContract.DriverSession{
    username="B",
    loginCredentials=LoginCredentials{
    authority="example"
    provider="com.eleostech.example"
    token="p0LLdm3Ma…KEAd8vMN12d"
    }
    }
    ] Note over B: App adjusts session state to be have driver A and B both logged in.

    • Field Detail

      • VERSION

        public static final java.lang.String VERSION
        This is the current version of the IdentityContract for the Open Cab Standard. The version will be passed as an argument to all method calls to the provider. The provider may reject or handle appropriately if the VERSION does not match the expected value. An OpenCab Identity provider allows access to authentication related information that can be used by an OpenCab Identity consumer app to enable SSO.
        See Also:
        Constant Field Values

      • AUTHORITY

        public static final java.lang.String AUTHORITY
        This authority is declared in the manifest for the Identity Content Provider. It is then used by the consumer app to identify any providers installed on the device.
        See Also:
        Constant Field Values

      • IDENTITY_CHANGED_RECEIVER

        public static final java.lang.String IDENTITY_CHANGED_RECEIVER
        This is the name of the receiver class. Application will be looking for classes with this name when it tries to broadcast an event.
        See Also:
        Constant Field Values

      • ACTION_DRIVER_LOGOUT

        public static final java.lang.String ACTION_DRIVER_LOGOUT
        This Action is broadcast when the driver logs out of the OpenCab provider app. Providers MUST publish this event when a user (either a team driver or the last primary user) logs out of the app. This event SHOULD correspond to a change in the result of METHOD_GET_ACTIVE_DRIVERS

        The OpenCab consumer app MAY listen to this broadcast and perform a logout of the consumer app.

        Note: The underlying string value of this constant erroneously begins with com.opencabstandard rather than org.opencabstandard. This error is preserved in order to maintain backwards compatibility.

        See Also:
        Constant Field Values

      • ACTION_IDENTITY_INFORMATION_CHANGED

        public static final java.lang.String ACTION_IDENTITY_INFORMATION_CHANGED
        This Action is broadcast when the identity information changes.

        You can subscribe to this event to receive updates indicating the active driver, or information about the active driver (such as their LoginCredentials token) has been updated. To get the updated value, call METHOD_GET_LOGIN_CREDENTIALS after receiving this event.

        Providers MUST publish this event when the values returned by METHOD_GET_LOGIN_CREDENTIALS change.

        See Also:
        Constant Field Values

      • ACTION_DRIVER_LOGIN

        public static final java.lang.String ACTION_DRIVER_LOGIN
        This Action is broadcast when the user logs in to the application. Providers MUST publish this event when a user authenticates with the app, such as by entering their credentials.
        See Also:
        Constant Field Values

      • METHOD_GET_LOGIN_CREDENTIALS

        public static final java.lang.String METHOD_GET_LOGIN_CREDENTIALS
        Provider method for retrieving the login credentials. The credentials include a token that uniquely identifies the driver and can be used to authenticate the driver.

        Example: 

         
     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + IdentityContract.AUTHORITY),

                                  IdentityContract.METHOD_GET_LOGIN_CREDENTIALS,
                                  IdentityContract.VERSION,
                                  null);

     LoginCredentials credentials = result.getParcelable(IdentityContract.KEY_LOGIN_CREDENTIALS);

        Diagram:

        sequenceDiagram participant A as OpenCab Consumer participant B as OpenCab Provider A->>B: contentResolver.call(Uri.parse("content://org.opencabstandard.identity"), "getLoginCredentials", "0.2", null) B->>A: android.os.Bundle
        See Also:
        Constant Field Values

      • METHOD_GET_ACTIVE_DRIVERS

        public static final java.lang.String METHOD_GET_ACTIVE_DRIVERS
        Provider method for retrieving the current active drivers. Active drivers can include the vehicle operator as well as any co-drivers in the vehicle.

        Example: 

         
     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + IdentityContract.AUTHORITY),
                                  IdentityContract.METHOD_GET_ACTIVE_DRIVERS,
                                  IdentityContract.VERSION,
                                  null);

     ArrayList<IdentityContract.Driver> drivers =
              result.getParcelableArrayList(IdentityContract.KEY_ACTIVE_DRIVERS);

        Diagram:

        sequenceDiagram participant A as OpenCab Consumer participant B as OpenCab Provider A->>B: contentResolver.call(Uri.parse("content://org.opencabstandard.identity"), "getActiveDrivers", "0.2", null) B->>A: android.os.Bundle
        See Also:
        Constant Field Values

      • KEY_ACTIVE_DRIVERS

        public static final java.lang.String KEY_ACTIVE_DRIVERS
        Use this key to retrieve the active drivers from the Bundle object that is returned from the IdentityContract.METHOD_GET_ACTIVE_DRIVERS method call.

        Example: 

         
     ArrayList<Driver> drivers =
              result.getParcelableArrayList(IdentityContract.KEY_ACTIVE_DRIVERS);
        See Also:
        Constant Field Values

      • KEY_ERROR

        public static final java.lang.String KEY_ERROR
        If an error has occurred in one of the provider method calls, use this key to retrieve the error from the Bundle object returned from the provider call method.

        Example: 

         
     String error = result.getString(IdentityContract.KEY_ERROR);
        See Also:
        Constant Field Values

      • KEY_VERSION

        public static final java.lang.String KEY_VERSION
        For the methods IdentityContract.METHOD_GET_LOGIN_CREDENTIALS and IdentityContract.METHOD_GET_ACTIVE_DRIVERS, the returned Bundle object will contain this key which maps to String indicating contract version supported.

        Example: 

         
     ContentResolver resolver = getApplicationContext().getContentResolver();
     Bundle result = resolver.call(Uri.parse("content://" + HOSContract.AUTHORITY),
                                  IdentityContract.METHOD_GET_LOGIN_CREDENTIALS,
                                  IdentityContract.VERSION,
                                  null);
     String version = result.getBoolean(IdentityContract.KEY_VERSION);
        See Also:
        Constant Field Values

    • Constructor Detail

      • IdentityContract

        public IdentityContract()