You can configure the dotCMS SAML App to enable logins to dotCMS from Google GSuite. The details of the configuration may vary based on your implementation, but this document provides general steps to help you get started.
In Google
Start by navigating to https://admin.google.com/ac/apps You will get something like:
Click on the SAML apps in order to start a new IDP configuration. In our case we already have SSOs installed. Let’s add a new one, on the down right corner click on the plus yellow circle button: Google offers you some already SAML apps integrated, let’s use the “SET UP MY OWN CUSTOM APP” Google generates automatically for you the IDP configuration, here you can download the IDP metadata (also you can do it later), save it for later and click on “NEXT” Now give a name to the configuration. Usually for the SP configuration you only have to upload the XML metadata generated by dotCMS (will see it later), but on Google you just need to tell it which one is the ACS or “AssertionConsumerService” and the “Entity ID”. The ACS URL is always https://{host}/dotsaml/login/{hostId} Entity ID just needs to be unique, generally : https://{host}/dotAdmin Later when configuring dotCMS we will set the entityID but here you can set whatever you want, usually an URL. When the user gets logged into the IDP, the IDP returns user information, depending on this configuration how much information will be returned, so click on “ADD NEW MAPPING” to set up it. You can see the important values below
Attribute Mappings:
| dotCMS | |
|---|---|
| Basic Information > First Name | givenName |
| Basic Information > Last Name | sn |
| Basic Information > Primary Email | |
| SSO > role | authorizations |
Click Finish, and you will see the new configuration done.
How to add SSO Roles in Google
Go to your User Manager and edit a user Scroll down on the User’s Information and Click on SSO Roles You then need to add the Role Keys for the Roles that you want this user to inherit when they login to dotCMS via SAML
In dotCMS
In order to configure the SAML part on dotCMS, we have to use an app called SAML: Go to the Apps and you will see between your apps installed the Saml Integration, click on it to start the configuration. As soon as you get into the SAML App, you will see the configuration for each one (if it has any) and the SYSTEM_HOST, you can configure each host even with a different IDP or you can just configure the SYSTEM_HOST, an host without configuration will fallback to the SYSTEM HOST configuration.
Configuring our SAML Application
First thing you have to do is to generate your private key and certificate (public key), if you do not already have them, you will want to run this command to generate them. This is a self signed cert that is valid for 10 years.
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout mysaml.key -out mysaml.crt -days 3650
This command will generate two files, the mysaml.key and mysaml.crt (you can use another name if you want), the .key is the private key and the .crt is the public key.
Enable: if checked the configuration will be used for the host.
IDP Name. Can be anything, it is just the name for it.
Service Provider Issuer ID: this should be the same url we used on the Google IDP configuration: https://local.saml.com:8443/dotAdmin. Usually this is the url of the host.
Service Provider Endpoint Hostname/Port this is the host name without the protocol such as: local.saml.com:8443. If port is needed also include it.
Validation Type this value will depend on the IDP configuration, responses may need validation only on the Assertion or Response or both. For this example set Validation Type to Only Assertion
IDP Metadata File, cut and paste the contents of the XML previously downloaded from Google’s IDP.
Public Certifcate, cut and paste the public key previously generated. Private Key, cut and paste here the private key previously generated.
Custom Properties- SAML has a tons of configuration extra that is described on a separated document, this doc will help to face and control different aspects of the SAML validation, mapping, etc. In this example we need only one:
verify.signature.credentials=false
Syncing Roles
build.roles=... This is an optional property that will configure how roles will be synced from the IDP to DOTCMS. It defaults to “all”.
build.roles=allRemoves all user roles from DOTCMS; adds the roles to DOTCMS from IdP and role.extra (if set) -build.roles=idpRemoves all user roles and adds the roles to DOTCMS from IdPbuild.roles=staticonlyRemoves all user roles, adds roles from role.extra (if set) to DOTCMS. Ignore roles from IdP.build.roles=staticaddDo not alter existing user roles, adds the roles from role.extra (if set) to DOTCMS. Ignore roles from IdP.build.roles=noneDo not alter any user roles on DOTCMSallow.user.synchronization=falseThis is another optional property. For a
