> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oloid-demo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a Custom Login with OLOID Button Using Okta Federation

> This article explains how to add a custom Login with OLOID button to your application using Okta federation.

When a user clicks this button, the app sends the user to the Okta authorization endpoint with a specific idp parameter so Okta routes authentication directly to OLOID instead of showing the standard Okta login page.

## Overview

Use this method when:

* your application is integrated with Okta
* OLOID is configured in Okta as an external Identity Provider
* you want users to go directly to the OLOID sign-in flow

This approach is useful for creating a branded login experience such as:

**Login with OLOID**

***

## How it works

When the user clicks the **Login with OLOID** button:

1. The application builds an Okta authorization URL.
2. The URL includes the `idp` parameter for the OLOID federated Identity Provider.
3. Okta skips the default login page.
4. The user is redirected to OLOID for authentication.
5. After successful sign-in, Okta redirects the user back to the configured `redirect_uri`.

***

## Authorization URL

Use the following Okta authorization endpoint:

> [!NOTE]
>
> **Note:** [https://dev-10453970.okta.com](https://dev-10453970.okta.com) will be your OKTA domain

```
https://dev-10453970.okta.com/oauth2/v1/authorize
```

## Sample authorization request

```
https://dev-10453970.okta.com/oauth2/v1/authorize?idp=0oaonnwcphJKjciYE5d7&client_id=0oaonnx8k6fDYWdPb5d7&response_type=code&response_mode=fragment&scope=openid%20profile%20email&redirect_uri=https%3A%2F%2Fdev-10453970.okta.com&state=asnneFSGWYbwgqyw&nonce=jdrhuebwbe
```

> [!NOTE]
>
> **Note:** In production, the `state` and `nonce` values must be generated dynamically for every request.

***

## Parameter reference

Parameter

Value

Description

Base URL

`https://dev-10453970.okta.com/oauth2/v1/authorize`

The Okta authorization endpoint.

`idp`

`0oaonnwcphJKjciYE5d7`

Crucial parameter. This tells Okta to skip the standard login page and route the user directly to the specific external Identity Provider configured for OLOID.

`client_id`

`0oaonnx8k6fDYWdPb5d7`

The unique identifier for your application registered in Okta.

`response_type`

`code`

Indicates Authorization Code Flow, which is the recommended and most secure method for exchanging credentials.

`response_mode`

`fragment`

Instructs Okta to return response parameters in the URL fragment (`#`) rather than in the query string.

`scope`

`openid profile email`

The permissions being requested, including basic identity and email information.

`redirect_uri`

`https://dev-10453970.okta.com`

The authorized URL where Okta sends the user after successful authentication. This must be added in the Okta application as a valid **Sign-in redirect URI**.

`state`

`asnneFSGWYbwgqyw`

A random string used to prevent Cross-Site Request Forgery (CSRF). This must be auto-generated for every request.

`nonce`

`jdrhuebwbe`

A random string used to associate a client session with an ID token and help mitigate replay attacks. This must be auto-generated for every request.

***

## Steps to add the button

## 1. Add a custom button to your login page

Add a button labeled:

**Login with OLOID**

Example:

```
<button id="oloid-login-btn">Login with OLOID</button>
```

## 2. Build the authorize URL

When the button is clicked, construct the Okta authorize URL using the required parameters.

## 3. Generate `state` and `nonce`

Before redirecting the user, generate unique random values for:

* `state`
* `nonce`

Do not hardcode these values outside of testing.

## 4. Redirect the browser to Okta

Once the URL is built, redirect the browser to that URL.

***

## Example implementation

```
<button id="oloid-login-btn">Login with OLOID</button>

<script>
  function randomString(length = 24) {
    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    let result = '';
    const values = new Uint8Array(length);
    crypto.getRandomValues(values);
    for (let i = 0; i < length; i++) {
      result += chars[values[i] % chars.length];
    }
    return result;
  }

  document.getElementById('oloid-login-btn').addEventListener('click', function () {
    const baseUrl = 'https://dev-10453970.okta.com/oauth2/v1/authorize';
    const idp = '0oaonnwcphJKjciYE5d7';
    const clientId = '0oaonnx8k6fDYWdPb5d7';
    const responseType = 'code';
    const responseMode = 'fragment';
    const scope = 'openid profile email';
    const redirectUri = 'https://dev-10453970.okta.com';

    const state = randomString();
    const nonce = randomString();

    const authUrl =
      `${baseUrl}` +
      `?idp=${encodeURIComponent(idp)}` +
      `&client_id=${encodeURIComponent(clientId)}` +
      `&response_type=${encodeURIComponent(responseType)}` +
      `&response_mode=${encodeURIComponent(responseMode)}` +
      `&scope=${encodeURIComponent(scope)}` +
      `&redirect_uri=${encodeURIComponent(redirectUri)}` +
      `&state=${encodeURIComponent(state)}` +
      `&nonce=${encodeURIComponent(nonce)}`;

    window.location.href = authUrl;
  });
</script>
```

***

## Expected behavior

After clicking **Login with OLOID**:

* the user is redirected to Okta
* Okta identifies the `idp` value
* Okta forwards the authentication request to OLOID
* after successful login, Okta redirects the user to the configured `redirect_uri`

***

## Important implementation notes

## `idp` is the key parameter

The `idp` parameter is what makes this a federated login flow. Without it, Okta may show its regular login screen instead of routing directly to OLOID.

## `redirect_uri` must be allowed in Okta

The `redirect_uri` must exactly match one of the allowed **Sign-in redirect URIs** in the Okta app configuration.

## `state` and `nonce` must be dynamic

For security reasons, both values must be generated per request and validated as part of the authentication flow.

## URL-encode parameter values

Always encode all query parameter values before constructing the URL.

***

## Troubleshooting

## User sees the regular Okta login page

Verify that the `idp` parameter is present and correct.

## Okta returns redirect URI error

Make sure the `redirect_uri` is configured in the Okta application exactly as used in the request.

## Authentication succeeds but app does not complete login

Check whether your application correctly handles the authorization response returned using `response_mode=fragment`.

## Security validation fails

Confirm that your app generates and validates `state` and `nonce` correctly.

***

## Summary

To add a **Login with OLOID** button using Okta federation:

* create a custom login button in your app
* send users to the Okta `/authorize` endpoint
* include the OLOID `idp` value
* use Authorization Code Flow
* generate `state` and `nonce` for every request
* ensure the `redirect_uri` is configured in Okta

This gives users a direct **Login with OLOID** experience while still using Okta as the federation and authorization layer.