Package org.opencabstandard.provider

Class IdentityContract

java.lang.Object
org.opencabstandard.provider.IdentityContract
public final class IdentityContract extends Object

Identity Contract Provider

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 Details

    • VERSION

      public static final 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:

    • AUTHORITY

      public static final 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:

    • IDENTITY_CHANGED_RECEIVER

      public static final 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:

    • ACTION_DRIVER_LOGOUT

      public static final 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:

    • ACTION_IDENTITY_INFORMATION_CHANGED

      public static final 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:

    • ACTION_DRIVER_LOGIN

      public static final 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:

    • METHOD_GET_LOGIN_CREDENTIALS

      public static final 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:

    • METHOD_GET_ACTIVE_DRIVERS

      public static final 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:

    • KEY_ACTIVE_DRIVERS

      public static final 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:

    • KEY_LOGIN_CREDENTIALS

      public static final String KEY_LOGIN_CREDENTIALS
      Use this key to retrieve the IdentityContract.LoginCredentials from the Bundle object that is returned from the IdentityContract.METHOD_GET_LOGIN_CREDENTIALS method call.

      Example: 

       
     LoginCredentials credentials = result.getParcelable(IdentityContract.KEY_LOGIN_CREDENTIALS);
      See Also:

    • KEY_ALL_LOGIN_CREDENTIALS

      public static final String KEY_ALL_LOGIN_CREDENTIALS
      Use this key to retrieve the IdentityContract.DriverSession from the Bundle object that is returned from the IdentityContract.METHOD_GET_LOGIN_CREDENTIALS method call.

      Example: 

       
     LoginCredentials credentials = result.getParcelable(IdentityContract.KEY_ALL_LOGIN_CREDENTIALS);
      See Also:

    • KEY_ERROR

      public static final 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:

    • KEY_VERSION

      public static final 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:

  • Constructor Details

    • IdentityContract

      public IdentityContract()