[Openid-specs-fapi] Issue #630: Android Carrier OpenID API (openid/fapi)

[Bjorn Hjelm]

New issue 630: Android Carrier OpenID API
https://bitbucket.org/openid/fapi/issues/630/android-carrier-openid-api

Bjorn Hjelm:

This is a replica of issue #[215](https://bitbucket.org/openid/mobile/issues/215/android-carrier-openid-api) in the MODRNA WG.

# Feature name: Carrier OpenId API

## Short description:

Applications that e.g. want to make use of carrier APIs are in some cases required to authenticate the user and collect the user’s consent. But application developers currently have no way to determine the carrier’s user authentication endpoint. GSMA standardized OpenId Connect \(OIDC\) authentication for privileged apps and that is already implemented in Android.  
See: [https://cs.android.com/android/platform/superproject/main/\+/main:frameworks/libs/gsma\_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/libs/gsma_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java)

This feature request is to make OIDC-based user authentication available to all Android apps.  
DT proposes an API that allows all Android applications to retrieve the carrier’s OIDC configuration e.g. [https://mobileconnect.telekom.de/.well-known/openid-configuration](https://mobileconnect.telekom.de/.well-known/openid-configuration)

OpenId Connect is _the_ standard for user authentication and used by carriers and Google. Deutsche Telekom is a corporate member of the OpenId Foundation. Google is a sustaining member of the OpenId Foundation. Filip Verley is Google's representative at the OIDF. [https://openid.net/foundation/board/](https://openid.net/foundation/board/) .

## Use case\(s\):

1. A bank wants to implement risk-based authentication for users of their online banking app and the bank wants to know the location of the user’s phone. Privacy-regulations might require the bank to get the user’s consent in some legislations.  
  The banking app would retrieve the carrier’s OIDC configuration and direct the user to the carrier’s user authentication page.
2. An application might want to know the mobile device’s status e.g. whether it is roaming. The vendor of the application needs the user’s consent when the vendor request device status information. By retrieving the carriers OIDC configuration the application can direct the user to authenticate at the carrier’s OIDC authentication endpoint, and then consent can be collected.
3. When the new Android phone is run for the first time, Android might redirect the user to the carrier's user authentication. A user account related to the carrier can be created after authentication. That account can then be used by all of the carrier's applications and other applications that use the Android user's online accounts.

## If this feature was accepted, what does success look like?:

All Android application can retrieve the carrier’s OIDC configuration. 3rd Parties using carrier APIs like those defined in Camara that need user consent use this new Android API to retrieve the carrier's OIDC configuration. OEMs and other providing first run UX to Android users now have a general way to determine the user authentication endpoint and more of the carrier, and use that to create carrier accounts on the new device.

## Impacts to partner/ecosystem \(e.g. accelerate build speeds 10x\):

This new API makes it possible for the API user to determine the carrier's OIDC configuration.

## Detailed description and list of technical documents

### getOidcConfiguration

Added in

[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

public

[String](https://developer.android.com/reference/java/lang/String) getOidcConfiguration \(int subscriptionId\)

Returns the URL as a string for the carrier's OIDC configuration endpoint for `subId`, or an empty string if not available.

This API is suitable for general apps that needs to e.g. authenticate the user at the carrier's OIDC authentication endpoint and collect consent.

The availability and correctness of the OIDC configuration URL depends whether the carrier has configured this value.  
Requires no permission.

Parameters

`subscriptionId`

`int`: the subscription ID, or `[DEFAULT_SUBSCRIPTION_ID](https://developer.android.com/reference/android/telephony/SubscriptionManager#DEFAULT_SUBSCRIPTION_ID)` for the default one.

Returns

`[String](https://developer.android.com/reference/java/lang/String)`

the URL of the carrier's OIDC configuration or an empty string if not available. This value cannot be `null`. The OIDC standard requires that this URL is an HTTPS-URL.

Throws

`[IllegalStateException](https://developer.android.com/reference/java/lang/IllegalStateException)`

if the telephony process is not currently available.

The new Android API might be implemented in SubscriptionManager. As the OIDC configuration is public no PERMISSIONS are needed. [https://developer.android.com/reference/android/telephony/SubscriptionManager](https://developer.android.com/reference/android/telephony/SubscriptionManager)

### Camara API examples

[https://camaraproject.org/device-status/](https://camaraproject.org/device-status/) [https://camaraproject.org/device-location/](https://camaraproject.org/device-location/)

### GSMA Standards

[https://www.gsma.com/newsroom/wp-content/uploads/TS.43-v9.0.pdf](https://www.gsma.com/newsroom/wp-content/uploads/TS.43-v9.0.pdf)

### OIDF Standards

[https://openid.net/specs/openid-connect-discovery-1\_0.html#ProviderMetadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata)

### TS.43 in Android

[https://cs.android.com/android/platform/superproject/main/\+/main:frameworks/libs/gsma\_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/libs/gsma_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java)

#### SIMILAR METHOD IN ANDROID

Android's Ts43AuthenticationLibary already has a similar method but retrieving the OIDC configuration allows to get all the information instead of just e.g. the OIDC token endpoint.

See: [https://cs.android.com/android/platform/superproject/main/\+/main:frameworks/libs/gsma\_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java;l=242](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/libs/gsma_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java;l=242)

> `/** * Get the URL of OIDC (OpenID Connect) server as described in * TS.43 Service Entitlement Configuration section 2.8.2. * The client should present the content of the URL to the user to continue the authentication * process.`

public

[void](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/libs/gsma_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java;drc=46470e17c23a347fca066508844a3dba55f371b7;bpv=1;bpt=1;l=277?gsn=void&gs=KYTHE%3A%2F%2Fkythe%3A%2F%2Fandroid.googlesource.com%2Fplatform%2Fsuperproject%2Fmain%2F%2Fmain%3Flang%3Djava%23void%2523builtin)

[requestOidcAuthenticationServer](https://cs.android.com/android/platform/superproject/main/+/main:frameworks/libs/gsma_services/ts43authentication/src/com/android/libraries/ts43authentication/Ts43AuthenticationLibrary.java;drc=46470e17c23a347fca066508844a3dba55f371b7;bpv=1;bpt=1;l=277?gsn=requestOidcAuthenticationServer&gs=KYTHE%3A%2F%2Fkythe%3A%2F%2Fandroid.googlesource.com%2Fplatform%2Fsuperproject%2Fmain%2F%2Fmain%3Flang%3Djava%3Fpath%3Dcom.android.libraries.ts43authentication.Ts43AuthenticationLibrary%23891bd20d7a94954077b21a3e4b633d7239ee2cc575fdb37aafd8add9019832e8)\(...\)

‌