OIDC Integration

The following uses Keycloak as an example to demonstrate how to integrate OIDC authentication in MrDoc.

## Keycloak Configuration

### Realm

In this demonstration environment, we created a new realm named "mrdoc":

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/8c66e0594f474950a63ae96754bca95d7632.png)

### Client

Next, create a new client of type "OpenID Connect" within the "mrdoc" realm, and set the Client ID to "mrdoc-oidc":

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/719825e1f7514824914f9fa604b798501520.png)

Then, configure the "mrdoc-oidc" client.

In the "Access Settings," enter the relevant URLs for your MrDoc instance:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/346b6d4f145c4658814e12747c42a0a33804.png)

In the "Capability Config," enable "Client Authentication" and "Authorization":

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/d1d1bff76f764b21a0a231aeaafaec8a8335.png)

After configuring, save the settings.

### Client Credentials

Switch to the "Credentials" tab on the "mrdoc-oidc" client configuration page and obtain the "Client Secret" for later use:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/18b08592a9cc4f098692209db2a04d194145.png)

## MrDoc Configuration

Navigate to the "Third-party Login" section in the admin panel, switch to the "OIDC" tab, and click the "Add OIDC Provider" button:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/b5e7cc8723ee4589a0640732163e820b5092.png)

In the pop-up dialog, enter the corresponding information for the OIDC provider:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/3314d5b922a24a1fb1d3ea789c72994e8401.png)

Where:

- **Name**: Used to identify the OIDC provider and must be unique within MrDoc.
- **Client ID**: The Client ID created in Keycloak.
- **Client Secret**: The "Client Secret" from the "Credentials" tab of the client in Keycloak.
- **Metadata URL**: In Keycloak, the metadata URL is typically: `{OIDC Service URL}/realms/{Realm Name}/.well-known/openid-configuration`

Therefore, based on the Keycloak configuration above, configure the OIDC provider information as follows:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/0c93c7efb88e4be0bacab313822792875543.png)

After configuration, an OIDC login icon will appear on the MrDoc login page:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/64272fe3c2684654920aed00aa26682e6040.png)

Clicking it will redirect to the OIDC provider's authentication address:

![](http://file.mrdoc.pro/mrdoc-oss/img/2025/02/26/cd842148b08c4609a235013fae3939343955.png)

Enter the account credentials from the OIDC service to log in and be redirected back to MrDoc.