--- title: Configuring Android apps for OIDC sign-on description: PingOne PingOne Advanced Identity Cloud PingAM OIDC-compliant servers Android component: orchsdks page_id: orchsdks:oidc:usage/android-centralized-login canonical_url: https://developer.pingidentity.com/orchsdks/oidc/usage/android-centralized-login.html revdate: Tue, 17 Oct 2025 11:22:33 +0100 keywords: ["OAuth 2.0", "OpenID Connect", "Setup & Configuration", "Source Code", "Integration", "SDK", "Android"] section_ids: android_oidc_server_config: Before you begin android_oidc_redirects: Step 1. Configuring your app to handle redirects android_oidc_modules: Step 2. Installing modules android_oidc_properties: Step 3. Configuring connection properties android_oidc_start_oauth2: Step 4. Starting the OAuth 2.0 flow android_oidc_access_token: Step 5. Obtaining an Access Token android_oidc_logout: Step 6. Revoking tokens and signing out android_oidc_tabs: Step 7. Customizing browser tabs --- # Configuring Android apps for OIDC sign-on [icon: circle-check, set=far]PingOne [icon: circle-check, set=far]PingOne Advanced Identity Cloud [icon: circle-check, set=far]PingAM [icon: circle-check, set=far]OIDC-compliant servers [icon: android, set=fab]Android You can configure your Android apps to use your authorization server's UI, or your own web application, for sign-on requests. When a user attempts to sign on to your app it redirects them to the central sign-on UI. After the user authenticates, the authorization server redirects them back to your application or site. Changes to authentication journeys or flows on your authorization server are available to all your apps that use the OIDC sign-on method, without the need to rebuild or redistribute the app. Likewise, any rebranding applied to your central sign-on UI is reflected immediately in your client apps. Your app doesn't need to access user credentials directly, just the result of the authentication from the server—usually an access token. To configure an Android app to perform OIDC sign-on, complete each of the following steps: * [Before you begin](#android_oidc_server_config) * [Step 1. Configuring your app to handle redirects](#android_oidc_redirects) * [Step 2. Installing modules](#android_oidc_modules) * [Step 3. Configuring connection properties](#android_oidc_properties) * [Step 4. Starting the OAuth 2.0 flow](#android_oidc_start_oauth2) * [Step 5. Obtaining an Access Token](#android_oidc_access_token) * [Step 6. Revoking tokens and signing out](#android_oidc_logout) * [Step 7. Customizing browser tabs](#android_oidc_tabs) ## Before you begin You need to prepare your server for OIDC sign-on. Select your server from the options below and complete the tasks before proceeding to configure your application. * PingOne * Advanced Identity Cloud * AM * PingFederate This tutorial requires you to configure your PingOne server as follows: > **Collapse: Task 1. Create a demo user** > > The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication. > > To create a demo user in PingOne, follow these steps: > > 1. Log in to your PingOne administration console. > > 2. In the left panel, navigate to Directory > Users. > > 3. Next to the Users label, click the plus icon ([icon: plus, set=fa]). > > PingOne displays the Add User panel. > > 4. Enter the following details: > > * **Given Name** = `Demo` > > * **Family Name** = `User` > > * **Username** = `demo` > > * **Email** = `demo.user@example.com` > > * **Population** = `Default` > > * **Password** = `Ch4ng3it!` > > 5. Click Save. > **Collapse: Task 2. Register a public OAuth 2.0 client** > > To register a *public* OAuth 2.0 client application in PingOne for use with the Orchestration SDKs for Android and iOS, follow these steps: > > 1. Log in to your PingOne administration console. > > 2. In the left panel, navigate to Applications > Applications. > > 3. Next to the Applications label, click the plus icon ([icon: plus, set=fa]). > > PingOne displays the Add Application panel. > > 4. In Application Name, enter a name for the profile, for example `sdkNativeClient` > > 5. Select Native as the Application Type, and then click Save. > > 6. On the Configuration tab, click the pencil icon ([icon: pencil, set=fa]). > > 1. In Grant Type, select the following values: > > `Authorization Code` > > `Refresh Token` > > 2. In Redirect URIs, enter the following values: > > `com.example.demo://oauth2redirect` > > 3. In Token Endpoint Authentication Method, select `None`. > > 4. In the **Advanced Settings** section, enable **Terminate User Session by ID Token**. > > 5. Click Save. > > 7. On the Resources tab, next to Allowed Scopes, click the pencil icon ([icon: pencil, set=fa]). > > 1. In Scopes, select the following values: > > `email` > > `phone` > > `profile` > > | | | > | - | ------------------------------------------ | > | | The `openid` scope is selected by default. | > > The result resembles the following: > > ![Adding scopes to an application.](../../_images/pingone-oidc-native-scopes-en.png)Figure 1. Adding scopes to an application. > > 8. Optionally, on the Policies tab, click the pencil icon ([icon: pencil, set=fa]) to select the authentication policies for the application. > > | | | > | - | -------------------------------------------------------------------------------------------------------------------------------------- | > | | Applications that have no authentication policy assignments use the environment's default authentication policy to authenticate users. | > > If you have a DaVinci license, you can select PingOne policies or DaVinci Flow policies, but not both. If you do not have a DaVinci license, the page only displays PingOne policies. > > To use a *PingOne policy*: > > 1. Click [icon: plus, set=fa]Add policies and then select the policies that you want to apply to the application. > > 2. Click Save. > > PingOne applies the policies in the order in which they appear in the list. PingOne evaluates the first policy in the list first. If the requirements are not met, PingOne moves to the next one. > > For more information, see [Authentication policies for applications](https://docs.pingidentity.com/pingone/applications/p1_auth_policies_for_applications.html). > > To use a *DaVinci Flow policy*: > > 1. You must clear all PingOne policies. Click Deselect all PingOne Policies. > > 2. In the confirmation message, click Continue. > > 3. On the DaVinci Policies tab, select the policies that you want to apply to the application. > > 4. Click Save. > > PingOne applies the first policy in the list. > > 9. Click Save. > > 10. Enable the OAuth 2.0 client application by using the toggle next to its name: > > ![Enable the application using the toggle.](../../_images/pingone-apps-enable-native-client-en.png)Figure 2. Enable the application using the toggle. > > The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Android and iOS PingOne example applications and tutorials covered by this documentation. This tutorial requires you to configure your PingOne Advanced Identity Cloud tenant as follows: > **Collapse: Task 1. Create a demo user** > > The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication. > > To create a demo user in PingOne Advanced Identity Cloud, follow these steps: > > 1. Log in to your PingOne Advanced Identity Cloud tenant. > > 2. In the left panel, click Identities > Manage. > > 3. Click [icon: plus, set=fa]New Alpha realm - User. > > 4. Enter the following details: > > * **Username** = `demo` > > * **First Name** = `Demo` > > * **Last Name** = `User` > > * **Email Address** = `demo.user@example.com` > > * **Password** = `Ch4ng3it!` > > 5. Click Save. > **Collapse: Task 2. Register a public OAuth 2.0 client** > > Public clients do not use a client secret to obtain tokens because they are unable to keep them hidden. The Orchestration SDKs commonly use this type of client to obtain tokens, as they cannot guarantee safekeeping of the client credentials in a browser or on a mobile device. > > To register a *public* OAuth 2.0 client application for use with the SDKs in PingOne Advanced Identity Cloud, follow these steps: > > 1. Log in to your PingOne Advanced Identity Cloud tenant. > > 2. In the left panel, click Applications. > > 3. Click [icon: plus, set=fa]Custom Application. > > 4. Select OIDC - OpenId Connect as the sign-in method, and then click Next. > > 5. Select Native / SPA as the application type, and then click Next. > > 6. In Name, enter a name for the application, such as `Public SDK Client`. > > 7. In Owners, select a user that is responsible for maintaining the application, and then click Next. > > | | | > | - | ---------------------------------------------------------------------------------- | > | | When trying out the SDKs, you could select the `demo` user you created previously. | > > 8. In Client ID, enter `sdkPublicClient` > > 9. Select **Configure for SDK Sample Apps**. > > 10. Click Create Application. > > PingOne Advanced Identity Cloud creates the application and displays the details screen. > > 11. On the Sign On tab: > > 1. In Sign-In URLs, ensure the following values appear, or add them if they don't: > > `com.example.demo://oauth2redirect` > > `https://demo.example.com/oauth2redirect` > > | | | > | - | ----------------------------------------------------------- | > | | Also add any other domains where you host SDK applications. | > > 2. In Grant Types, ensure the following values appear: > > `Authorization Code` > > `Refresh Token` > > 3. In Scopes, ensure the following values appear: > > `openid profile email address` > > 12. Click Show advanced settings, and on the Authentication tab, confirm the following properties: > > 1. In Token Endpoint Authentication Method, select `none`. > > 2. In Client Type, select `Public`. > > 3. Enable the Implied Consent property. > > 13. Click Save. > > The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the example applications and tutorials covered by this documentation. > **Collapse: Task 3. Configure the OAuth 2.0 provider** > > The provider specifies the supported OAuth 2.0 configuration options for a realm. > > To ensure the PingOne Advanced Identity Cloud OAuth 2.0 provider service is configured for use with the Orchestration SDKs, follow these steps: > > 1. In your PingOne Advanced Identity Cloud tenant, navigate to Native Consoles > Access Management. > > 2. In the left panel, click [icon: plug, set=fa]Services. > > 3. In the list of services, click OAuth2 Provider. > > 4. On the Core tab, ensure Issue Refresh Tokens is enabled. > > 5. On the Consent tab, ensure Allow Clients to Skip Consent is enabled. > > 6. Click Save Changes. This tutorial requires you to configure your AM server as follows: > **Collapse: Task 1. Create a demo user** > > The samples and tutorials in this documentation often require that you have an identity set up so that you can test authentication. > > To create a demo user in PingAM, follow these steps: > > 1. Log in to the PingAM admin UI as an administrator. > > 2. Navigate to [icon: address-card, set=fa]Identities, and then click [icon: plus, set=fa]Add Identity. > > 3. Enter the following details: > > * **User ID** = `demo` > > * **Password** = `Ch4ng3it!` > > * **Email Address** = `demo.user@example.com` > > 4. Click Create. > **Collapse: Task 2. Register a public OAuth 2.0 client** > > Public clients do not use a client secret to obtain tokens because they are unable to keep them hidden. The Orchestration SDKs commonly use this type of client to obtain tokens, as they cannot guarantee safekeeping of the client credentials in a browser or on a mobile device. > > To register a *public* OAuth 2.0 client application for use with the SDKs in AM, follow these steps: > > 1. Log in to the PingAM admin UI as an administrator. > > 2. Navigate to [icon: list-alt, set=fa]Applications > OAuth 2.0 > Clients, and then click [icon: plus, set=fa]Add Client. > > 3. In Client ID, enter `sdkPublicClient`. > > 4. Leave Client secret empty. > > 5. In Redirection URIs, enter the following values: > > `com.example.demo://oauth2redirect` > > https\://demo.example.com/oauth2redirect > > | | | > | - | ---------------------------------------------------------------------- | > | | Also add any other domains where you will be hosting SDK applications. | > > 6. In Scopes, enter the following values: > > `openid profile email address` > > 7. Click Create. > > PingAM creates the new OAuth 2.0 client, and displays the properties for further configuration. > > 8. On the Core tab: > > 1. In Client type, select `Public`. > > 2. Disable Allow wildcard ports in redirect URIs. > > 3. Click Save Changes. > > 9. On the Advanced tab: > > 1. In Grant Types, enter the following values: > > ```none > Authorization Code > Refresh Token > ``` > > 2. In Token Endpoint Authentication Method, select `None`. > > 3. Enable the Implied consent property. > > 10. Click Save Changes. > **Collapse: Task 3. Configure the OAuth 2.0 provider** > > The provider specifies the supported OAuth 2.0 configuration options for a realm. > > To ensure the PingAM OAuth 2.0 provider service is configured for use with the Orchestration SDKs, follow these steps: > > 1. Log in to the PingAM admin UI as an administrator. > > 2. In the left panel, click [icon: plug, set=fa]Services. > > 3. In the list of services, click OAuth2 Provider. > > 4. On the Core tab, ensure Issue Refresh Tokens is enabled. > > 5. On the Consent tab, ensure Allow Clients to Skip Consent is enabled. > > 6. Click Save Changes. This tutorial requires you to configure your PingFederate server as follows: > **Collapse: Task 1. Register a public OAuth 2.0 client** > > OAuth 2.0 client application profiles define how applications connect to PingFederate and obtain OAuth 2.0 tokens. > > To allow the Orchestration SDKs to connect to PingFederate and obtain OAuth 2.0 tokens, you must register an OAuth 2.0 client application: > > 1. Log in to the PingFederate administration console as an administrator. > > 2. Navigate to **Applications** [icon: angle-right, set=fa] **OAuth** [icon: angle-right, set=fa] **Clients**. > > 3. Click **Add Client**. > > PingFederate displays the **Clients | Client** page. > > 4. In **Client ID** and **Name**, enter a name for the profile, for example `sdkPublicClient` > > Make a note of the **Client ID** value, you will need it when you configure the sample code. > > 5. In **Client Authentication**, select `None`. > > 6. In **Redirect URIs**, add the following: > > `com.example.demo://oauth2redirect` > > https\://demo.example.com/oauth2redirect > > | | | > | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | Also add any other URLs where you host SDK applications.Failure to add redirect URLs that exactly match your client app's values can cause PingFederate to display an error message such as `Redirect URI mismatch` when attempting to end a session by redirecting from the SDK. | > > 7. In **Allowed Grant Types**, select the following values: > > `Authorization Code` > > `Refresh Token` > > 8. In the **OpenID Connect** section: > > 1. In **Logout Mode**, select **Ping Front-Channel** > > 2. In **Front-Channel Logout URIs**, add the following: > > `com.example.demo://oauth2redirect` > > https\://demo.example.com/oauth2redirect > > | | | > | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | Also add any other URLs that redirect users to PingFederate to end their session.Failure to add sign off URLs that exactly match your client app's values can cause PingFederate to display an error message such as `invalid post logout redirect URI` when attempting to end a session by redirecting from the SDK. | > > 3. In **Post-Logout Redirect URIs**, add the following: > > `com.example.demo://oauth2redirect` > > https\://demo.example.com/oauth2redirect > > 9. Click Save. > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | | After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.In the PingFederate administration console, navigate to **System > Server > Cluster Management**, and click **Replicate**. | > > The application is now configured to accept client connections from and issue OAuth 2.0 tokens to the Orchestration SDK PingFederate example applications and tutorials covered by this documentation. > **Collapse: Task 2. Configure CORS** > > [Cross-origin resource sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (CORS) lets user agents make cross-domain server requests. In PingFederate, you can configure CORS to allow browsers or apps from trusted domains to access protected resources. > > To configure CORS in PingFederate follow these steps: > > 1. Log in to the PingFederate administration console as an administrator. > > 2. Navigate to **System** [icon: angle-right, set=fa] **OAuth Settings** [icon: angle-right, set=fa] **Authorization Server Settings**. > > 3. In the **Cross-Origin Resource Sharing Settings** section, in the **Allowed Origin** field, enter any DNS aliases you use for your SDK apps. > > This documentation assumes the following configuration: > > | Property | Values | > | ---------------- | ----------------------------------- | > | `Allowed Origin` | `com.example.demo://oauth2redirect` | > > 4. Click **Save**. > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | | After changing PingFederate configuration using the administration console, you must replicate the changes to each server node in the cluster before they take effect.In the PingFederate administration console, navigate to **System > Server > Cluster Management**, and click **Replicate**. | > > Your PingFederate server is now able to accept connections from origins hosting apps built with the Orchestration SDKs. ## Step 1. Configuring your app to handle redirects After completing authentication in the browser, the server redirects the user back to your application, by using the value of the `redirect_uri` parameter. You need to configure your app to open and accept the data the server sends as part of the redirect. There are two methods for configuring an Android app to handle redirect URIs. To ensure that only your app is able to obtain authorization tokens during OIDC sign-on we recommend you configure it to use [Android App Links](https://developer.android.com/studio/write/app-link-indexing). If you don't want to implement Android App Links, you can instead use a custom scheme for your redirect URIs. * Android App Links / HTTPS * Custom Scheme You can configure your Android app to open and handle redirects that match the base domain of your authorization server, and use the HTTPS protocol. Using this method, your redirect URI will resemble the following: `https://demo.example.com/oauth2redirect` To configure App Links in an Android application, perform the following steps: 1. In your application, configure the Orchestration SDK `browser` module to use the HTTPS scheme for capturing redirect URIs, by adding an `` for `com.pingidentity.browser.CustomTabActivity` to your `AndroidManifest.xml`: AndroidManifest.xml ```xml ``` * You must set `android:autoVerify` to `true`. This instructs Android to verify the specified host against the `assetlinks.json` file you update in the next step. * Specify the `scheme`, `hosts`, and `path` parameters to use in your redirect URIs. The host value must match the domain where you upload the `assetlinks.json` file. To learn more about intents, refer to [Add intent filters](https://developer.android.com/studio/write/app-link-indexing#intent) in the Android Developer documentation. 2. For Android 11 or higher, add the following to the `AndroidManfest.xml` file: AndroidManifest.xml ```xml ``` 3. Create or update a Digital Asset Links (`assetlinks.json`) file that associates your app with your domain. You must host the file in a `.well-known` folder on the same host that you entered in the intent filter earlier. The file will resemble the following: https\://demo.example.com/.well-known/assetlinks.json ```json [ { "relation": [ "delegate_permission/common.handle_all_urls", ], "target": { "namespace": "android_app", "package_name": "com.example.demo", "sha256_cert_fingerprints": [ "c4:15:c8:f1:...:fe:ce:d7:37" ] } } ] ``` * To learn more, refer to [Associate your app with your website](https://developer.android.com/studio/write/app-link-indexing#associatesite) in the Android Developer documentation. 4. Upload the completed file to the domain that matches the host value you configured in the earlier step. For information on uploading an `assetLinks.json` file to an Advanced PingOne Advanced Identity Cloud instance, refer to [Upload an Android assetlinks.json file](https://docs.pingidentity.com/pingoneaic/latest/end-user/upload-android-assetlinks.html). You can configure your Android app to open and handle redirects that use a custom scheme, rather than HTTPS. Using this method, your redirect URI will resemble the following: `com.example.demo://oauth2redirect` To configure a custom scheme in an Android application, perform the following steps: 1. Add the custom scheme your app will use to your `gradle.build.kts` file: ```gradle android { defaultConfig { manifestPlaceholders["appRedirectUriScheme"] = "com.example.demo" } } ``` | | | | - | ------------------------------------------------------------------------------------- | | | The custom scheme consists of the string before the colon (`:`) character in the URI. | 2. For Android 11 or higher, add the following to the `AndroidManfest.xml` file: ```xml ``` ## Step 2. Installing modules For OIDC sign-on, you need these modules: * `oidc` * `browser` To install these modules into your Android app: 1. In the **Project** tree view of your Android Studio project, open the `build.gradle.kts` file. 2. In the `dependencies` section, add the `oidc` and `browser` modules as dependencies: ```gradle dependencies { implementation("com.pingidentity.sdks:oidc:2.0.0") implementation("com.pingidentity.sdks:browser:2.0.0") } ``` ## Step 3. Configuring connection properties Configure the `oidc` module to connect to your OpenID Connect 1.0-compliant authorization server: Required parameters to configure the `oidc` module ```kotlin val web = OidcWebClient { logger = Logger.STANDARD module(com.pingidentity.oidc.module.Oidc) { discoveryEndpoint = "https://auth.pingone.ca/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration" clientId = "6c7eb89a-66e9-ab12-cd34-eeaf795650b2" redirectUri = "https://demo.example.com/oath2redirect" scopes = mutableSetOf("openid", "email", "address", "profile", "phone") } } ``` Update the following properties with values that match your environment: * *discoveryEndpoint* The `.well-known` endpoint from your OAuth 2.0 application. > **Collapse: How do I find my PingOne .well-known URL?** > > To find the `.well-known` endpoint for an OAuth 2.0 client in PingOne: > > 1. Log in to your PingOne administration console. > > 2. Go to **Applications > Applications**, and then select your OAuth 2.0 client. > > For example, sdkPublicClient. > > 3. On the **Overview** tab, expand the **Connection Details** section, and then copy the **OIDC Discovery Endpoint** value. > > ![Locating the .well-known URL in a PingOne client profile.](../../_images/p1-client-well-known.png) > **Collapse: How do I form my PingFederate .well-known URL?** > > To form the `.well-known` endpoint for a PingFederate server: > > 1. Log in to your PingFederate administration console. > > 2. Navigate to **System** [icon: angle-right, set=fa] **Server** [icon: angle-right, set=fa] **Protocol Settings**. > > 3. Make a note of the **Base URL** value. > > For example, `https://pingfed.example.com` > > | | | > | - | --------------------------------- | > | | Do not use the admin console URL. | > > 4. Append `/.well-known/openid-configuration` after the base URL value to form the `.well-known` endpoint of your server. > > For example, `https://pingfed.example.com/.well-known/openid-configuration`. > > The SDK reads the OAuth 2.0 paths it requires from this endpoint. > **Collapse: How do I find my PingOne Advanced Identity Cloud URL?** > > You can view the `.well-known` endpoint for an OAuth 2.0 client in the PingOne Advanced Identity Cloud admin console: > > 1. Log in to your PingOne Advanced Identity Cloud administration console. > > 2. Click Applications, and then select the OAuth 2.0 client you created earlier. For example, sdkPublicClient. > > 3. On the Sign On tab, in the Client Credentials section, copy the Discovery URI value. > > For example, `https://openam-forgerock-sdks.forgeblocks.com/am/oauth2/alpha/.well-known/openid-configuration` > > | | | > | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | If you are using a custom domain, your `.well-known` is formed as follows:`https:///.well-known/openid-configuration`Learn more in [Access OIDC configuration discovery endpoint](https://docs.pingidentity.com/pingoneaic/latest/realms/custom-domains.html#access-oidc-configuration-discovery-endpoint). | > **Collapse: How do I find my PingAM URL?** > > To form the `.well-known` URL for an PingAM server, concatenate the following information into a single URL: > > 1. The base URL of the PingAM component of your deployment, including the port number and deployment path. > > For example, `https://openam.example.com:8443/openam` > > 2. The string `/oauth2` > > 3. The hierarchy of the realm that contains the OAuth 2.0 client. > > You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the `realms/` keyword. > > For example, `/realms/root/realms/customers` > > | | | > | - | ------------------------------------------------------------------------------- | > | | If you omit the realm hierarchy, the top level `ROOT` realm is used by default. | > > 4. The string `/.well-known/openid-configuration` > > For example, `https://openam.example.com:8443/openam/oauth2/realms/root/.well-known/openid-configuration` For example, `https://auth.pingone.ca/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration` * *clientId* The client ID of your OAuth 2.0 application. For example, `6c7eb89a-66e9-ab12-cd34-eeaf795650b2` * *redirectUri* The redirect URI as configured in the OAuth 2.0 client profile. This value must exactly match one of the values configured in your OAuth 2.0 client. For example: * App link / HTTPS redirect URI: `https://demo.example.com/oauth2redirect` * Custom scheme redirect URI: `com.example.demo://oauth2redirect` * *scopes* The scopes you added to your OAuth 2.0 application. For example, `"openid", "email", "address", "profile", "phone"` You can pass optional OAuth 2.0 parameters into configuration to affect the OAuth 2.0 flow on the server. Adding optional parameters when configuring the `oidc` module ```kotlin val web = OidcWebClient { logger = Logger.STANDARD module(com.pingidentity.oidc.module.Oidc) { discoveryEndpoint = "https://auth.pingone.ca/3072206d-c6ce-ch15-m0nd-f87e972c7cc3/as/.well-known/openid-configuration" clientId = "6c7eb89a-66e9-ab12-cd34-eeaf795650b2" redirectUri = "https://demo.example.com/oath2redirect" scopes = mutableSetOf("openid", "email", "address", "profile", "phone") acrValues = "Single_Factor%20Multi_Factor" loginHint = "demo.user@example.com" } } ``` For example, you can add the following parameters: * *acrValues* An optional space-separated list of Authentication Context Class Reference (`acr`) values, in order of preference. The server can use these values to help determine how the user should be authenticated. For example, you can specify a DaVinci flow policy ID, or PingOne policy names to request that PingOne follows a particular path to authenticate the user. The Orchestration SDK sends this as the `acr_values` parameter in the authentication request, as per the specification. * *loginHint* An optional string that lets the server know what identifier the user might use to authenticate with. The server can use this to pre-populate a sign-on form, or to customize the UI to match a particular brand or organization. The Orchestration SDK sends this as the `login_hint` parameter in the authentication request, as per the specification. Learn more about OAuth 2.0 authentication request parameters in [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest), in the *OpenID Connect Core 1.0* specification. ## Step 4. Starting the OAuth 2.0 flow The `oidc` module provides the `authorize()` method, which launches the web browsers and starts the OAuth 2.0 flow. Start the OAuth 2.0 flow by using the `authorize()` method ```kotlin web.authorize() .onSuccess { user -> ... }.onFailure { throwable -> ... } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can inject or override OAuth 2.0 parameters, and pass custom key-pair values when starting the OAuth 2.0 flow with the `authorize()` method.Adding parameters when using the `authorize()` method```kotlin web.authorize( "acrValues" to "Social_Signon", "loginHint" to "+1 303 555 0100", "customParameter" to "my_custom_value" ).onSuccess { user -> ... }.onFailure { throwable -> ... } ``` | ## Step 5. Obtaining an Access Token After successfully starting the OAuth 2.0 flow and authenticating the user, the server redirects control back to your application. Your application receives the OAuth 2.0 `code` and `state` parameters it needs to continue the flow and obtain an access token. To obtain an access token on behalf of a user, follow these steps: 1. Create an object that represents a user's authentication session by using the `user()` method: Create a user object by calling the `user()` method ```kotlin val user = web.user() ``` 2. Retrieve a token on behalf of the user by calling the `token()` method on your `user` object, and handle the result: Obtain an access token for a user by calling `user.token()` and handle the result ```kotlin when (val result = user.token()) { is Result.Failure -> { when (result.value) { is OidcError.ApiError -> TODO() is OidcError.AuthenticationRequired -> TODO() is OidcError.AuthorizeError -> TODO() is OidcError.NetworkError -> TODO() is OidcError.Unknown -> TODO() } } is Result.Success -> { val accessToken = result.value } } ``` ## Step 6. Revoking tokens and signing out You can call the following methods on your `user` object to revoke OAuth 2.0 tokens, and sign out the user from the server: * `user.revoke()` Revokes the OAuth 2.0 tokens on the server, and deletes them from storage. * `user.logout()` Removes an session tokens the user may have, and contacts the server to end the user's session. ## Step 7. Customizing browser tabs The **OIDC** module uses Auth Tabs for OIDC sign-on where possible, and falls back to use a custom tab if not. You can customize aspects of how both of these appear in your app: * Auth tabs Auth Tabs provide enhanced security features for OAuth 2.0 flows and are automatically used when supported by the device and when the redirect URI uses a custom scheme. Learn more in [Simplify authentication using Auth Tab](https://developer.chrome.com/docs/android/custom-tabs/guide-auth-tab) in the *Chrome for Developers* documentation. To customize the auth tab, add your preferred configuration to `BrowserLauncher.authTabCustomizer` before you call `authorize()`, as follows: Customizing auth tabs on Android ```kotlin BrowserLauncher.authTabCustomizer = { setColorScheme(CustomTabsIntent.COLOR_SCHEME_DARK) // Add other AuthTabsIntent configurations as needed } ``` * Custom tabs The **OIDC** module falls back to using custom tabs if auth tabs are not supported on the device. To customize the auth tab, add your preferred configuration to `BrowserLauncher.customTabsCustomizer` before you call `authorize()`, as follows: Customizing custom tabs on Android ```kotlin BrowserLauncher.customTabsCustomizer = { setShowTitle(false) setColorScheme(CustomTabsIntent.COLOR_SCHEME_SYSTEM) // Use the system default color scheme setToolbarColor( ContextCompat.getColor( context, R.color.colorPrimary ) ) // Set a specific toolbar color setUrlBarHidingEnabled(true) // Add other CustomTabsIntent configurations as needed } ``` Learn more in [Customizing the UI](https://developer.chrome.com/docs/android/custom-tabs/guide-ui-customization) in the *Chrome for Developers* documentation.