Psono Documentation

# Keycloak as IDP for OIDC-SSO

To set up the IDP you need a running instance of Keycloak with a configurable realm.

# Preamble

The Enterprise Edition (EE) server and client support the OIDC protocol that allows you to configure an external service as IDP (identity provider) for SSO (single sign on). This guide here will explain how to configure KeyCloak as OIDC-IDP for SSO. We assume that:

  • your Keycloak instance is running on https://keycloak.example.com,
  • you have a configured a realm named "psono",
  • your webclient can be accessed on https://psono.example.com
  • the server is reachable at https://psono.example.com/server (e.g. https://psono.example.com/server/info/ shows you some nice json output).

This is your first OIDC provider that you want to configure (therefore we give it the ID "1").

TIP

This feature is only available in the Enterprise Edition.

# Keycloak

  1. Navigate to your realm and click on Create client in the Clients-Section.

    client-create

  2. In there add your new client like shown below

    client-create

    client-create

    client-create

  3. Edit "Logout settings"

    Afterwards click on the client to edit and scroll down to the bottom of the settings to the "Logout settings", uncheck "Front channel logout" and enter the "Backchannel logout URL": https://psono.example.com/oidc/1/backchannel-logout/

    client-config

  4. Note down "Client secret"

    Switch to the "Credentials" tab and note the "Client secret" which will be used in the configuration of Psono later.

    client-config

  5. Create group mapper

    Go to "Client scopes" and select the "Dedicated scope and mappers for this client"

    keycloak click dedicated scope and mappers

    Click "Add predefined mappers"

    keycloak add predefined mappers

    And add "groups"

    keycloak add groups mapper

# Server (settings.yaml)

After setting up the IDP for the OIDC-Authentication it is time to configure your running Psono server to act as the SP. It is required that Psono can reach Keycloak and vise versa.

Edit the settings.yml like so:

# Make sure the 'OIDC'-entry is present in the following list
AUTHENTICATION_METHODS: ['OIDC']

OIDC_CONFIGURATIONS:
    1:
        OIDC_RP_SIGN_ALGO: 'RS256'
        OIDC_RP_CLIENT_ID: 'psono'
        OIDC_RP_CLIENT_SECRET: 'd61d048a-100e-4299-885f-b3e23539b60c'
        OIDC_OP_JWKS_ENDPOINT: 'https://keycloak.example.com/realms/psono/protocol/openid-connect/certs'
        OIDC_OP_AUTHORIZATION_ENDPOINT: 'https://keycloak.example.com/realms/psono/protocol/openid-connect/auth'
        OIDC_OP_TOKEN_ENDPOINT: 'https://keycloak.example.com/realms/psono/protocol/openid-connect/token'
        OIDC_OP_USER_ENDPOINT: 'https://keycloak.example.com/realms/psono/protocol/openid-connect/userinfo'
        OIDC_OP_END_SESSION_ENDPOINT: 'http://127.0.0.1:8080/realms/psono/protocol/openid-connect/logout'
  • OIDC_RP_CLIENT_ID: That's the Client ID in keycloak
  • OIDC_RP_CLIENT_SECRET: That's the Client secret in keycloak
  • OIDC_OP_..._ENDPOINT: The keycloak endpoints can be found on the ".well-known"-page (e.g. https://keycloak.example.com/realms/psono/.well-known/openid-configuration) of your installation.

TIP

Always restart the server after making changes in the setting.yml-file.

# Client (config.json)

Now you have to configure your client, so your users can use this configured IDP.

Update your config.json similar to the one shown below.

{
  ...
    "authentication_methods": ["OIDC"],
    "oidc_provider": [{
      "title": "OIDC Login",
      "provider_id": 1,
      "button_name": "Login "
    }]
  ...
}

The variable authentication_methods restricts the allowed login methods. In the example above only OIDC will be allowed and the normal login "hidden". The title and button_name can be adjusted however you like. The provider_id needs to match the one that you used on your server.

← OIDC - WSO2 Identity Server →