Configure SSO with SAML

🔴 Advanced

user

osp-keycloak

This example explains how to configure OnSphere to delegate authentication to a SAML server, supporting both self-signed and externally-issued certificates. No downloadable configuration example is provided for this page — follow the steps below manually.

• Add the SAML identity provider certificate to the Keycloak configuration (self-signed or externally-issued).

• Configure the SAML identity provider via the Keycloak admin console or the identityProviders.keycloak file.

• Map SAML user attributes (email, username, name) using Keycloak protocol mappers.

• Export the final configuration from Keycloak and integrate it into the OnSphere configuration files.

git checkout origin/osp-keycloak-configuration .

Steps

1. Add the certificate

• SAML using a not-self signed certificate

  1. Open the /modules/keycloak/keycloak-1/module.keycloak file

• SAML using a self signed certificate

  3. On the configuration create the certs/external folder if it doesn’t exist.

  4. Add the CA certificate as PEM into certs/external.

  5. Push the new configuration.

  6. Restart the Keycloak module.

2. Configure the server

• With the keycloak front-end (Recommended because it simplifies the test)

  1. Access the Keycloak administration console https://<stack_ip>:<stack_port>/auth/admin (for example https://stack-1.onsphere.local:5000/auth/admin).

  2. Login to Keycloak administration console using administration user and password configured when the stack was deployed (see System security).

  3. Access the Identity Providers tab.

  4. Select SAML v2.0 on the Add provider menu.

  5. At the bottom of the page under Import External IDP Config

  

  • Use the url providing the FederationMetadata.xml of your AD to configure it.

  • Directly import the FederationMetadata.xml.

  1. Configure your SAML server with the metadata from keycloak https://<stack ip or hostname>:<port>/auth/realms/onsphere/protocol/saml/descriptor.

  2. Configuration of the identifier for the user

  • AD

  

  • Keycloak

  

  1. When a user uses the Identity provider for the first time, it will need to provide an email, username, name and firstname.

  • This step is skipped if the mapper for the field is configured.

  2. Once everything is working properly, you can export the configuration and integrate it to the OnSphere configuration.

  • Go to the Export menu on the left and click Export

  • In the downloaded file search for IdentityProviders and identityProviderMappers

  • Copy the identity provider.

  • Open or create the /modules/keycloak/keycloak-1/identityProvider.keycloak file

  • Add the following content if missing

{
    "identityProviders": [],
    "identityProviderMappers": []
}

• Add the copied identity provider to the list.

• Remove all id to avoid any conflict.

• See osp-keycloak for a complete federation file.

  • With the configuration file

  1. Copy osp-keycloak complete identity provider file.

  2. Add its content to the /modules/keycloak/keycloak-1/identityProviders.keycloak file

  3. Update the file base on your LDAP configuration

  4. Push the configuration

  5. Check the keycloak logs to see if there are any errors.

  6. If necessary modify the configuration to fix the errors.

  7. Access the Keycloak administration console https://{stack_ip}:{stack_port}/auth/admin (for example https://stack-1.onsphere.local:5000/auth/admin).

  8. Login to Keycloak administration console using administration user and password configured when the stack was deployed (see System security).

  9. Check if the groups and user are properly created.