# Configure OIDC authentication

## Overview

{% hint style="warning" %}
Since Curity Community Edition is used, we'll use Google Authenticator as a workaround. The Google Authenticator is a standard OIDC authenticator.
{% endhint %}

This document outlines the steps to configure OpenID Connect (OIDC) authentication for a client application using the OIDC Discovery mechanism. The Discovery endpoint provides metadata for the OIDC Provider (OP), allowing dynamic configuration without manual entry of endpoints and other settings.

OpenID Connect (OIDC) is an authentication protocol based on the OAuth 2.0 framework. It adds a standardized identity layer on top of OAuth 2.0, enabling Single Sign-On (SSO) functionality. OIDC allows clients to verify the identity of users based on the authentication performed by an Authorization Server, and to obtain basic profile information about the user in an interoperable and REST-like manner.

## Key terminology

To avoid confusion, let's define some key terms:

* The **End User**: The person who wants to log in.
* The **Client (in this case, the Application, Curity)**: The entity that wants to authenticate users using OIDC.
* The **Provider (also known as OpenID Connect Provider)**: The entity that provides the authentication services. It often has an Identity Provider associated with it, and is able to provide the user's identity information.
* The **Identity Provider (in this case, the Provider)**: The entity that provides user identities and authentication services.
* The **Discovery Document**: A public JSON document that contains information about the Provider, including endpoints, supported scopes, and other metadata. Often accessible at `https://<auth hostname>/.well-known/openid-configuration`.
  * Example: <https://accounts.google.com/.well-known/openid-configuration>

## Configuration

### OIDC Provider side (Your Identity Provider)

Go to your OIDC Provider administration console and configure the necessary settings for OIDC authentication.

To configure OIDC authentication, you can follow these general steps:

1. Create an OAuth Client in your Identity Provider.
2. Set the Redirect URI to `https://<auth hostname>/7bf98083-e4ff-4769-baa7-da4fde86d932/authentication/authentication/oidc/callback`
   * `7bf98083-e4ff-4769-baa7-da4fde86d932` correspond the the helm chart default value `global.tenantID`. In which, it has no other function beside naming the tenant. This used internally at Toucan.
   * `oidc` (before the `/callback`) correspond to the name of the OIDC authenticator (see below), in the OIDC client configuration. If you plan to use another name, replace `oidc` by the name of the authenticator.
3. Fetch the client ID and client secret. Also fetch the Provider's discovery URL.

That's should be it! Of course, some OIDC providers might require additional configuration, but this should be the minimal requirements.

### OIDC Client side (Curity)

#### Method 1: Using Helm

To configure OIDC authentication, follow these steps:

1. Create a secret with the client ID and client secret:

{% code title="yaml: sso-secret.yaml" overflow="wrap" %}

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: sso-secret
  namespace: <namespace>
type: Opaque
stringData:
  client-secret: '<client secret>'
```

{% endcode %}

Deploy with `kubectl apply -f sso-secret.yaml`.

2. In the Helm Charts, set these parameters:

{% code title="yaml: values.override.yaml" %}

```yaml
curity:
  config:
    sso:
      authenticators:
        - id: oidc # Influences the url, see above
          type: oidc
          configurationURL: 'https://sso.example.com/.well-known/openid-configuration'
          scopes: openid profile email
          clientID: '<client id>' # From above
          clientSecret:
            secretName: sso-secret
            secretKey: client-secret
```

{% endcode %}

3. Deploy the Helm Charts (`helm upgrade -f ./values.override.yaml ...`).

{% hint style="warning" %}
Curity has its own configuration database. The Helm Charts use a merging strategy with the Curity configuration database. This means adding/updating values in the Helm Charts will override the values in the Curity configuration database. **But removing values in the Helm Charts will not remove them from the Curity configuration database.**
{% endhint %}

#### Method 2: Using the UI

To configure OIDC authentication, follow these steps:

1. In the Helm Charts, make sure the admin interface is accessible:

{% code title="yaml: values.override.yaml" %}

```yaml
curity:
  admin:
    ingress:
      enabled: true
      ingressClassName: nginx
      hostname: <auth hostname>
      path: /admin
      tls: true
```

{% endcode %}

And deploy it (`helm upgrade -f ./values.override.yaml ...`).

2. Fetch the credentials for the admin interface:

{% code title="shell" overflow="wrap" %}

```shell
# The secret may be named something else based on your configuration.
kubectl get secret --namespace toucan toucan-stack-curity -o jsonpath='{.data.curity-admin-password}' | base64 --decode
```

{% endcode %}

3. Access the UI at the following URL: `https://<auth hostname>/admin` and use the credentials `admin` as username and the password you got from the previous step.
4. You should be at the home page. Go to the Profiles tab (![profiles-button](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-3468aa2a50fc72bcb5934a69d91875c65b687572%2Fprofiles-button.png?alt=media)) and select the first section (![authentication](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-8fb452f825aaa776cf01f262e743689ab8206dc2%2Fauthentication-button.png?alt=media)) of the first profile.

   ![Curity Profiles](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-8c3411e8a55a8d7caab869f8eced2f247d510255%2Fcurity-profile.png?alt=media)
5. Go to authenticators:

   ![Curity Authenticators](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-d037da567ae1f31b9a27fd41e0c3518de40e66ed%2Fcurity-authenticators.png?alt=media)
6. Push the new authenticator button ![image-20250523162017911](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-9c8db79e891082887fb9d94ee083a14ee7d086f6%2Fnew-auth.png?alt=media).
7. Name it `oidc` and the type is Google ![image-20250523162055605](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-c0b2406eb6850b41621c7ac6cca1541a3960d21b%2Fgoogle-button.png?alt=media).
8. Replace the fields:
   * Configuration URL: **The provider discovery document URL**
     * Example: `https://accounts.google.com/.well-known/openid-configuration` (it should end with `.well-known/openid-configuration`)
   * Client ID: **The client ID fetched from the provider**
   * Client Secret: **The client secret fetched from the provider**
   * Scopes: `openid email profile` (the discovery document will tell you the available scopes)
   * ![OIDC Configuration](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-2c6c4b77feabfeb58e6cb6c993e5a5f41609fe2a%2Foidc-config.png?alt=media)
9. We'll need to setup some Login actions:
10. `default_create_account`:
    1. Click on Add Action ![add-action](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-1f06e5c92cfe6e9a533d25421e51005c8ec4c91b%2Fadd-action.png?alt=media) on the right side of Login. 2. Select Default\_create\_account![default-create-account](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-a8069b64069d87745abba7bf307b150162f73e18%2Fdefault-create-account.png?alt=media)
11. Do the same:
    * `default_copy_attribute`
    * `default_lookup_account_by_email_to_action_attributes`
    * `prepare_tenant_id_workspace_id`
    * `prepare_update_user_from_sso`
    * `default_update_user_from_attributes`
12. At this point, it should looks like:

    ![Actions Pipeline](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-0c7b8550dc564a98577d27d01d66d8e75ee802bb%2Factions-pipeline.png?alt=media)
13. Commit the changes:

    ![Commit](https://1809014303-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZxYYf1KpgarKMgMsDCrw%2Fuploads%2Fgit-blob-40779921139514d3df5513e3792e71bd0b5dc399%2Fcommit.png?alt=media)

The actions create the user in the Curity user database and provision permissions in the layout service.

By default, users coming from SSO are given **admin** privileges. You can change the behavior by editing the values in the Helm Charts:

{% code title="yaml: values.override.yaml" %}

```yaml
curity:
  config:
    sso:
      permissionsProvisioning:
        isAdmin: true
        # list of strings (names of groups)
        groups:
          []
          # - group-1
          # - group-2
        # map of string (app name) -> string (permission)
        # available permissions are 'view', 'edit'
        appPermissions:
          {}
          # app-1: 'view'
          # app-2: 'edit'
```

{% endcode %}