Configure SSO with SAML

Description

In this tutorial you will learn how to configure OnSphere to delegate authentication to a SAML server.

Steps

1. Add the certificate

  • SAML using a not-self signed certificate

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

    2. Set the includeSystemCA flag to true.

  • SAML using a self signed certificate

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

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

    3. Push the new configuration.

    4. 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

    ../../_images/saml-import.png

    • 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

    ../../_images/saml-nameId-ad.png

    • Keycloak

    ../../_images/saml-nameId-keycloak.png

    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.

    1. 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.